v0.0.1

Introduction

This documentation is a work in progress. Don't hesitate to contact us if you don't find what you're looking for.

Please read the Terms and Conditions before using this Reporting API.

If you want to run some examples, you can open our collection with Postman:

Run in Postman

Basic example

var data = JSON.stringify({
"columns": [
"visit_device_type",
"m_visits",
"m_users"
],
"sort": [
"-m_visits"
],
"space": {
"s": [429023]
},
"period": {
"p1": [
{
"type": "D",
"start": "2019-10-24",
"end": "2019-10-24"
}
]
},
"max-results": 50,
"page-num": 1
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.atinternet.io/v3beta/data/getData");
xhr.setRequestHeader("x-api-key", "YOURAPIKEY");
xhr.send(data);
ParameterRequiredDescription
spacetrueAnalysis scope (single site or multi-sites).
columnstrueList of properties & metrics to query (separated by a comma).
periodtrueAnalysis period (single, multiple, relative).
filterfalseFilters to be applied on properties/metrics.
evofalseTo obtain the evolution of a group of metrics over a certain time period.
sorttrueList of properties / metrics according to which the results will be sorted.
max-resultstrueNumber of results in the results page.
page-numtruePage number of the data set.

Parameter syntax

ParameterSyntax
space"space": { "s":[547656] }
columns"columns": [ "visit_device_type", "m_visits" ]
period"period": { "p1": [ { "type": "D", "start": "2019-10-20", "end": "2019-10-24" } ] }
filter"filter": { "metric": { "m_visits": { "$eq": 19 } }, }
evo"evo": { "granularity": "D", "top": { "max-results": 5, "page-num": 1, "sort": ["-m_visits"] } }
sort-by"sort": [ "m_visits" ]
max-results"max-results": 50
page-num"page-num": 1

Authentication

To authorise, use this code:

xhr.setRequestHeader("x-api-key", "YOURAPIKEY");

An API Key gives the same permissions than the user who created it. If the user loses rights on a site, then he won’t be able to use his API key to get data on this site anymore. If the user gets rights on a new site, then he will be able to use his API key to get data on this site.

The API Key aims at being used with REST URLs retrieved from Data Query. We invite you to use an API Key instead of providing login details using basic authentication, when querying the API with an external tool (Script or other). If you are an SSO user, you must use an API Key to query AT Internet REST API.

You can create a new API key on your profile page.

An API Key can only be created by an authenticated user who can manipulate data. This user must have at least one of the following roles:

  • Administrators
  • Delegates
  • Advanced Analysts
  • Analysts or Custom Roles with the “Handle data” tool

The API Key is created, enabled, disabled and deleted by each user independently.

API key has to be included in all API requests to the server in a header that looks like the following: x-api-key: YOURAPIKEY

POST or GET method ?

The Reporting API v3.0 is designed to be used with the POST method. As you may have noticed, the content of the API call is getting longer and longer as all the fields are well described, and the GET method can be limited because of th length of the http request.

POST method

The POST method is the one we recommend to manage the API calls as it's way more flexible and is not limited in the body call length.

If you want to run some examples, you can open our collection with Postman:

Run in Postman

Query "Headers"

KEYVALUE
Content-Typeapplication/json
x-api-keyYOURAPIKEY

Query "Body"

Select "raw" and paste the content of the param parameter and choose the JSON format:

GET method

In Data Query 3, you are now able to copy the content of the query, which uses by default the GET method.

Sites

Querying 1 site:

"space": {
"s":[547656]
},

Querying multiple sites:

"space": {
"s":[547656, 547657]
},

See Postman example

The space parameter allows you to define the scope of the site(s) you need to query.

ParameterDescriptionPossibles values
space-Array of int

Properties and metrics

Body with one period:

"columns": [
"visit_device_type",
"m_visits"
]

Body with multiple periods:

"columns": [
"visit_device_type",
"p1.m_visits",
"p2.m_visits"
]

See Postman example

In the columns parameter you can enter all properties and metrics that might be available in the call. To obtain the properties and metrics labels, you can go to your Data Model and look for the property key, or go to Data Query 3 and hover the (i) next to the name:

Image of Yaktocat

Period

See Postman example

p1 object is mandatory, it is the main period of analysis.

p2 object is optional, it describes the comparison period.

ParameterDescriptionPossible values
type-R(elative) or Absolute: D(ay), M(onth)

Absolute periods

"period": {
"p1": [
{
"type": "D",
"start": "2019-10-20",
"end": "2019-10-24"
}
],
"p2": [
{
"type": "D",
"start": "2019-10-15",
"end": "2019-10-19"
}
]
}

Date format: yyyy-mm-dd

Relative periods

"period": {
"p1": [
{
"type": "R",
"granularity": "D",
"offset": -1
}
],
"p2": [
{
"type": "R",
"granularity": "D",
"offset": -2
}
]
}

In the case of a single site call, the relative period will be in relation to the time zone of the site. In the case of a multi-site call, the relative period will be in relation to the most easterly time zone of the requested sites.

If you call a site A (UTC-1) and a site B (UTC+2), then the relative period will be relative to the site B.

ParameterDescriptionPossible values
granularity-Y(ear), Q(uarter), M(onth), W(eek), D(ay)
offSet-Number

Filter

Example: (visit equal to 19) AND (device type equal to Tablet or Desktop) AND (source start by Referrer )

"filter": {
"metric": {
"m_visits": {
"$eq": 19
}
},
"property": {
"$AND": [
{
"$OR": [{
"visit_device_type": {
"$in": ["Tablet","Desktop"]
}
}]
},
{
"visit_src": {
"$start": "Referrer"
}
}
]
}
}

See Postman example

If you want to filter your dataset, you have to use the filter object. You can filter on both properties and metrics.

Filter on number

ParameterDescription
$eqEquals to
$neqDoes not equal
$inArray
$gtGreater than
$gteGreater or equal to
$ltLower than
$lteLower or equal to
$natrue or false - NULL value
$undefinedtrue or false - undefined
$emptytrue or false - combinaison of $na and $undefined

Filter on string

ParameterDescription
$eqEquals to
$neqDoes not equal
$inArray
$lkContains
$nlkDoes not contain
$startStart with
$nstartDoes not start with
$endEnd with
$nendDoes not end with
$natrue or false - NULL value
$undefinedtrue or false - undefined
$emptytrue or false - combinaison of $na and $undefined

Filter on date

ParameterDescription
$eqEquals to
$gtGreater than
$gteGreater or equal to
$ltLower than
$lteLower or equal to

Filter on boolean

ParameterDescription
$eqEquals to
$neqDoes not equal
$natrue or false - NULL value
$undefinedtrue or false - undefined
$emptytrue or false - combinaison of $na and $undefined

Evolution

Basic :

"evo": {
"granularity": "D", // mandatory
"top": {
"max-results": 5,
"page-num": 1,
"sort": ["-m_visits"]
}
}

Advanced :

"evo": {
"granularity": "D", // mandatory
"top": {
"max-results": 5,
"page-num": 1,
"sort": ["-m_visits"],
"period": {
"p1": [
{
"type": "D",
"start": "2017-05-12",
"end": "2017-05-16"
}
]
}
}
}

See Postman example

The parameter evo describes the context of the evolution of the analysis. It is composed of different mandatory parameters:

ParameterDescriptionPossibles values
granularityGranularity of the evolutionM(onth), W(eek), D(ay), H(our)
topDescription of the selected elements, top of the elements according to the period, pagination and sorting, the number of elements depends on the parametersSee below
Top parameterDescriptionValeurs possibles
max-results-any number
page-num-any number
sortsort by metricsany metrics

Sort by

Simple sorting:

"sort": [
"m_visits"
]

If you have 2 periods, you can sort on the comparison period metric values:

"sort": [
"-p1.m_visits"
]

You can filter on several metrics and several properties:

"sort": [
"-visit_geo_country",
"visit_device_type",
"-m_visits",
"m_users"
]

See Postman example

The "-" allows you to sort in a decreasing way.

It is possible to sort on as many columns (metrics and properties) as desired.

It is not possible to sort on a column not present in the "columns" parameter of the URL.

Error codes

2006

If you have 2 periods, don't forget to add p1. or p2. in front of your metrics and in the sort parameters.

Terms & Conditions

The Reporting API 3.0 is included in the Analytics Suite. In order to ensure a stability in the usage, here are the terms & conditions:

  • 20 concurrent API calls per organisation
  • 5 concurrent API calls per user

If you exceed these quotas, the 429 error code will be returned.

We try to make the usage as fair as possible. Please make sure you follow the terms & conditions to maintain access to the Reporting API 3.0

If your user account or organisation have been blacklisted, please get in touch.