Developers » Data API » Rest API » Response structure & Parameters » Relative periods
Relative periods
Request a relative period
Relative periods allow you to use periods that are automatically updated based on the last minute of available data. It is no longer necessary to change the date, week, etc. in period: you simply need to specify which month, week, etc. you want to refer to for this last minute of available data.
The naming remains the same for granularity: but here we introduce the notion of translating the period.
To specify that its a relative period, we must always start with R:{}
For example, considering that the time of the API call is 21 February 2017, at 23:54 (week 8):
| Notation | Description |
|---|---|
| &period={R:{H:0}} | Current hour (23:00 up to the last available minute) |
| &period={R:{H:-1}} | Previous hour (22:00 to 22:59) |
| &period={R:{D:-1}} | Previous day (20 February 2017) |
| &period={R:{W:-1}} | Previous week (week 7) |
| &period={R:{H:{start:-3,end:0}}} | The 4 previous hours (20:00 up to the current hour) |
| &period={R:{MN:{start:-9,end:0}}} | This will always return a “3003” error. With this setting, the API is trying to query the last 10 minutes, from 23:45 to 23:54. As you may know, there is always a 3 to 5 minutes delay between the current time and the last minute available. We recommend shifting this setting by 5 minutes if you need to get the last 10 minutes available: &period={R:{MN:{start:-14,end:-5}}} |
| &period={R:{M:{start:-12,end:-1}}} | The last 12 months (February 2016 to January 2017) |
Please refer to this section to find out more about the relative periods.
When using these relative periods, you must verify that the request does not overlap between the current day and the previous days. For example: considering that the last available minute is 21 February 2019 at 14:34, R:{D:{start:-3,end:0}}} : this requests from the 18th to the 21st of February (impossible) R:{H:{start:-16,end:0}}} : the last 17 hours, which fall beyond the day period (21 February) Etc.
Request several relative periods
Relative periods function in the same way as when a request is made for several periods. It is possible to create different periods that are relative to each other.
Example:
&period={p1:{R:{W :0}},p2:{p1 :-1}}
Here, 2 periods are declared. The first one refers to the current week, and the second one refers to the week preceding the first period.
&period={p1:{R:{H:0}},p2:{R:{H:-25}}}
Here we compare the current hour, against the same hour on the day before. This also works with “MN” instead of “H”.
Last update: 14/03/2019