include parameter

Data API / REST API / Response structure parameters rest / “include” parameter

The “include” parameter allows to enrich the API response with extra contextual data such as the total, the data type, etc.

Here’s how the parameter is formatted: &include={total:displayed,total:all,reference:space,context}.

total:displayed

“Displayed” total: corresponds to the total of metrics shown in your dataset (and therefore paginated, if you have more than 10,000 rows in your entire results data set). This is the sum of all displayed rows.

Example:

&include={total:displayed}

total:all

“Sum of all elements”: Corresponds to the total of metrics shown in your entire dataset, without notion of pagination. If you have more than 10, 000 rows, say, for example, 45,600 rows, we will display the sum of all 45,600 rows.

Example:
&include={total:all}

reference:space

“Reference”: corresponds to the total of metrics of the site in question. This total allows you to therefore identify the proportion of data contained in your call compared to the total site-level metrics. This is the total sum of the chosen site.

Example:
&include={reference:space}

context

This value allows you to capture information related to the metadata of the call: periods, perimeters, pagination, etc.

Example:
&include={context}

Context for space

• Label: site label
• Currency: currency of site
• TimeZone: time zone of site
• Start: start date of the site

XML example with 1 site:

<Spaces>
  <Space>
    <Sites>
      <Site ID="1" Label="AT Internet" Currency="EUR" TimeZone="(UTC+1:00) Romance Standard Time" Start="YYYY-MM-DD"/>
    </Sites>
  </Space>
</Spaces>

Context for periods

• ID: period label (p1, p2, p3)
• Value: list of dates (separators: “,” for a time interval (start, end) “;” for potentially non-consecutive periods)

XML example:

<Periods>
  <Period ID="p1" Value="2013-05-01,2016-05-31;2016-06-21"/>
  <Period ID="p2" Value="2016-02-01"/>
</Periods>

Context for ranges (information relative to the pagination of results)

• ID with the values:
  • page-num: equivalent of querystring parameter
  • max-results: equivalent of querystring parameter
  • url-next: provides a Rest URL toward the next page of traffic data, regardless of whether there is data
• Value: value of metadata

XML example:

<Ranges>
  <Range ID="page-num" Value="1" />
  <Range ID="max-results" Value="30" />
  <Range ID="url-next" Value="https://apirest...&page-num=2" />
</Ranges>

Context for profile (information on the general profile of the results)

Profile with the attributes:

• Language: EN, FR, ES, DE
• FirstDayWeek: Monday

XML example:

<Profile language="FR" FirstDayWeek="Mo" />

Last update: 31/07/2017