“period” parameter

 

Introduction

To request a fixed period, there are “start” and “end” attributes. Nonetheless, syntax short cuts allow you to directly obtain calendar periods. Please take a look at the standard formats.

It is also possible to apply filters directly within a period in order to obtain, for example, all Mondays, the 1st day of every month, all 8:00am time slots, etc.

The API enables you to make API calls for fixed periods as well as for relative periods to simplify your usage.

When you request a period, you must specify the label of this period (in the case of using multiple periods) as well as the granularity of the period (Y: year, S: semester, Q: quarter, M: month, W: week, D: day, H: hour, MN: minutes).

The full periods (down to the minute) must be requested according to the ISO norm: YYYY-MM-DDTHH:MN (with T separating the time and the period)

Example:

period={p1:{H:2017-02-21T08},p2:{...}}

In this case, the period called p1 takes the 8th hour (8:00:00 to 8:59:59) of 21 February 2017.

  • The API allows you to query real-time data.
  • The period labels must follow the format pn, with n ranging from 1 to 3.
  • You may not use the p2 period if the p1 period does not exist.
  • If the period is named, all the metrics called in columns must refer to this period name: https://apirest.atinternet-solutions.com/data/v2/json/getData?&columns={d_source,p1.m_visits,p2.m_visits}&sort={-p1.m_visits}&space={s:#YourSiteID#}&period={p1:{D:2017-03-08},p2:{D:2017-03-07}}&max-results=50&page-num=1
  • In the case of multiple periods, the periods are separated by commas.
 

Comparing real-time data

When querying the Reporting API, you can include up to 2 comparison periods (p2 and p3). When comparing the current day (real time) versus a past period, you may want to analyse 2 things:

  • compare the current day with the entire compared day, from 12am to 23:59pm,

https://apirest.atinternet-solutions.com/data/v2/json/getData?&columns={d_site,p1.m_visits,p2.m_visits}&sort={-p1.m_visits}&space={s:000000}&period={p1:{R:{D:'0'}},p2:{R:{D:'-1'}}}

  • compare the current day with the compared day, from 12am up to the today’s exact time.

https://apirest.atinternet-solutions.com/data/v2/json/getData?&columns={d_site,p1.m_visits,p2.m_visits}&sort={-p1.m_visits}&space={s:000000}&period={p1:{R:{D:'0'}},p2:{p1:'-1','same'}}

In this example, p2:{p1:’-1′,’same’} means that p2 is the same previous (-1) time period type as p1.

 

Fine-tune the analysis period

An analysis period has a start and an end dates, that’s common sense. However, it doesn’t have to be that simple. Let’s take a look at the following use cases.

 

Report on the working hours

Let’s imagine you want to analyse a specific day, on a limited time frame: 8am to 12.30pm and 2pm to 6.30pm to report only on the working hours:

https://apirest.atinternet-solutions.com/data/v2/html/getData?&columns={m_visits}&sort={-m_visits}&space={s:000000}&period={MNe:{start:'2018-06-16T08:00',end:'2018-06-16T12:30'},MNe:{start:'2018-06-16T14:00',end:'2018-06-16T18:30'}}&max-results=10000&page-num=1

By combining the 2 periods within the period parameter, you exclude all the traffic before 8am, between 12.30pm and 2pm and after 6.30pm.

 

Report on the Sales periods

If you want to stay focused on the Sales periods:

  • Summer sales: 4th of July to 21st of July 2017
  • Winter sales: 1st of December to 20th of December 2017

https://apirest.atinternet-solutions.com/data/v2/html/getData?&columns={d_time_date,m_visits}&sort={d_time_date}&space={s:547656}&period={D:{start:'2017-07-04',end:'2017-07-21'},D:{start:'2017-12-01',end:'2017-12-20'}}&max-results=10000&page-num=1

Your dataset is now only focused on the 2 sales periods, in one unique query.

Was this post helpful?
Yes
No
Last update: 29/06/2018