The API Accounts enable you to distribute and share data within your organisation, in a secure and controllable manner. It’s likely that external consultants, agencies and partners need to access part of your analytics data at a certain point in time. With this application, you can create virtual accounts associated with specific Reporting API URLs allowing anybody to whom you communicate the URL to view the corresponding data. A unique code (GUID) allows us to embed the authentication directly within the URL, eliminating the need to create an AT Internet user account for each recipient.
NotePlease note that these API Accounts are not allowed to query neither the Data Flow API, nor the Campaigns API.
Rights to create an API Account
An API Account can only be created by an authenticated user who can manipulate data. This user must have at least one of the following roles:
- Advanced Analyst
- or Custom Role with the “Handle data” tool
- Data Supervisor
The API Account is created, enabled, disabled and deleted by each user independently.
Create an API Account
In the Analytics Suite 2, click on the menu and then go to Settings > API Accounts.
- Click on the “New” button on the home page,
- Name your account [a],
- Choose a site [b],
- Indicate the period for which you want to grant access to the data [c] and [d],
- Click “OK” to save [e].
NoteThe dates refer to the API account’s validity, not the period contained in the API calls.
It might be helpful to add the name of the site directly as the name of the API account.
Add a URL to an API account
Once you have created the account you will then be able to add one or several URLs that you wish to associate with the account [a].
As you can see, a global GUID has been associated to the account you have created [b].
To add a URL, click to add a label name [c].
You can either go to the Data Query application to create a new one [d], select a Standard Template suggested by Data Query [e], or paste a URL you have already created [f].
This action will open a new tab in your browser. Click on Save [g].
Share the URL
Once you have added an API URL to the API account, you just need to click on the link icon [a].
A pop-up will appear, containing the final URL to communicate [b].
The authentication key is automatically embedded in the URL. That way, the person with whom you have shared the URL only has to call the URL in any web browser in order to display the data.
If necessary, you can edit or delete the URL by clicking on the pen icon.
Here is the list of the only parameters that can be modified in the URL (and therefore by the final user):
- MaxResult > Included in the URL by default: &max-results=
This parameter corresponds to the number of lines to display. Per default it is set to 20 but it can be set to up to 10,000.
- Call period > Included in the URL by default: &period=
Per default the period refers to the previous day (d-1).
- Decimal separator (dot or comma) > Not included in the URL by default. Add: &sep=comma or &sep=dot
- Language > Not included in the URL by default. Add &lng=
To change the language, you can add the &lng= parameter anywhere in the URL and add the corresponding value:
- fr for French,
- en for English,
- es for Spanish,
- de for German,
- pt for Portuguese,
- ru for Russian.
There are 6 functional rules:
- API account validity: the end date must be later than the start date.
- API Accounts only work for Level 1 sites.
- It is impossible to associate an API account with a URL that depends on a site different from the one selected during account creation.
- Once a URL has been associated with an API account, it is impossible to modify the account’s reference site
- Only Reporting API URLs are authorised (the ones that you create in Data Query).
- If the Piano Analytics account of the user who has created the API account is deleted, the corresponding API accounts will stop working.