REST API: my wishlist to Santa Claus

Thanks, Pierre. This is excellent feedback. Both of these features (a “station” timeseries and an explicit “scale” parameter) are on our roadmap. And (perhaps an early Christmas present for you?) the “scale” feature actually already exists (though it’s undocumented)! We added it to support the graph zooming feature in our apps (described more here: Data archive buckets explained). We haven’t publicly documented it, however, since it’s fairly application-specific and is very subject to change.

But, if you feel adventurous, and with the caveat that this is an undocumented feature so you should use it at your own risk, here’s how it works: Simply add a bucket parameter to your /observations/device request to explicitly ask for a specific scale/zoom level:

  • bucket=a
    • time step = 1 minute
    • max range = 1 day
  • bucket=b
    • time step = 5 minutes
    • max range = 5 days
  • bucket=c
    • time step = 30 minutes
    • max range = 30 days
  • bucket=d
    • time step = 180 minutes
    • max range = 180 days
  • bucket=e
    • time step = 1 day
    • max range = none

Note, bucket can only override the default value when fewer data points would be returned, compared to the default. For example, it is valid to ask for bucket=e for any time range but if you ask for bucket=a for a time range greater than one day, you will get an error (status_code=3) with a (hopefully) helpful explanation.

Again, use this feature at your own risk, if at all. If you have feedback on the current implementation and/or the definitions of what’s returned at each “bucket level”, we’d love to hear it!

Yes, we agree day_offset is a nice convenience feature. We have no plans to remove that parameter.

documenting all possible errors is also on our roadmap!

5 Likes