[Reporting API] Major improvements to detection of relative periods

The Reporting API, which is behind Explorer, Data Query, Dashboards and Reports, was updated on the 14/03/2019 to better manage relative periods in specific cases.

Days: yesterday, last n days, etc.

Before the update

When on 15 January at 0:02am (site's timezone, set up during the site creation) you call data from D-1, you would expect to receive all data from the previous day (14 January), from midnight to 23:59pm. But as you know, 3 to 5 minutes are necessary between data collection and availability in all analyses. Until now, we have provided data from the last entire day collected, so in this case, D-2 (13 January).

After the update

The call date (January 15) is taken into account in the detection of the relative period. So by calling D-1 at 12:02am on January 15, if all the previous day's data is not available, a message will inform you that the data is not ready and that the call must be renewed later on.

Hours

The same logic applies to relative hours. The current hour is the reference hour. A call for data from H-1 made at 4:17pm will return data from 3:00pm to 3:59pm, whereas the same call, if made at 4:01pm, will generate an informational message stating that the data from 3:00pm to 3:59pm is not yet ready, rather than returning data from 2:00pm to 2:59pm.  

Minutes

When you request the last n minutes, we will always take the hour and minute of the site as the reference time.
For example, by accessing the last 30 minutes at 2:13pm (period={R:{MN:{MN:{start:-30,end:0}}}), the Reporting API will attempt to return the data from 1:43pm to 2:13pm. However, as described above, 3 to 5 minutes are necessary between the collected data and the returned data. Therefore, the last available minute will be between 2:07pm and 2:12pm.

Consequences in the Analytics Suite

Explorer & Data Query

The calendar will automatically be adjusted. Please find below the details on Data Query.

Period called

Definition

Today

Data Query returns all available data, from 12.00am to the last available minute.

Yesterday

Data Query returns the data of the day before, based on the site local date, only if the whole day is ready.

Current week

Data Query returns the data from Monday to “yesterday”, based on the site local date, only if the entire period data is ready.

If the query is run on a Monday, this will behave as you were querying “Today”.

Current month

Data Query returns the data from the 1st day of the month to “yesterday”, based on the site local date, only if the entire period data is ready.

If the query is run on a the 1st day of the month, this will behave as you were querying “Today”.

Previous week

Data Query returns data of the past week, from Monday to Sunday, based on the site local date, only if the entire period data is ready.

Previous month

Data Query returns data of the past month, based on the site local date, only if the entire period data is ready.

Last X periods

Data Query returns the entire requested period, based on the site local date, only if the entire period data is ready.

Period -X

Data Query returns the entire requested period, based on the site local date, only if the entire period data is ready.

 

Dashboards & Reports

Dashboards and Reports offer richer default periods regarding the relative periods: last 5, 10, 30 and 60 minutes. As mentioned above, the last 3 to 5 minutes always being unavailable, we automatically add a 5-minute delay.

At 10am, when querying:

  • "the last 5 minutes", we will return data from 9.50am to 9.55am,
  • "the last 10 minutes", we will return data from 9.45am to 9.55am,
  • "the last 30 minutes", we will return data from 9.25am to 9.55am,
  • "the last 60 minutes", we will return data from 8.55am to 9.55am.

Reporting API

We highly recommend using the GetMaxDate to know which is the last minute available, before you do your calls. It will helps you understand why the API returns an informative message.

We therefore recommend that you no longer use "end:0" when you request minutes - they will never be available. For example, it is necessary to shift by 5 minutes: period={R:{MN:{start:-35,end:-5}}}

In any case, the Reporting API uses the time and the date of the site. If for any reason the data is not available within 3 to 5 minutes, you will have to retry your calls some minutes later.

Period called

Definition

&period={R:{M:'0'}}

The Reporting API returns the data from the 1st day of the month to “yesterday”, based on the site local date, only if the entire period data is ready.

If the query is run on a the 1st day of the month, this will behave as you were querying “Today”.

&period={R:{M:'-1'}}

The Reporting API returns data of the past month, based on the site local date, only if the entire period data is ready.

&period={R:{W:'0'}}

The Reporting API returns the data from Monday to “yesterday”, based on the site local date, only if the entire period data is ready.

If the query is run on a Monday, this will behave as you were querying “Today”.

&period={R:{W:'-1'}}

The Reporting API returns data of the past week, from Monday to Sunday, based on the site local date, only if the entire period data is ready.

&period={R:{D:'0'}}

The Reporting API returns all available data, from 12.00am to the last available minute.

&period={R:{D:'-1'}}

The Reporting API returns the data of the day before, based on the site local date, only if the whole day is ready.

&period={R:{H:'0'}}

The Reporting API returns all the available minutes of the current hour, based on the site local date.

&period={R:{H:'-1'}}

The Reporting API returns all the minutes of the past hour (from xx:00 to xx:59), based on the site local date, only if all the minutes are available.

&period={R:{MN:'0'}}

The Reporting API will always return the 3003 error code (data not ready).

This will also be the case for the -4, -3, -2, -1 and 0 minutes.

&period={R:{MN:'-10'}}

The Reporting API returns the -10 minutes, based on the site local time.

Have more questions? Submit a request