Getting started with Kits Explorer API
Welcome to the Kits Explorer API! Using this API you can create and read Kits Explorer Reports. You also have a dynamic Explorer available where you can run and test the API.
Authorization
To authenticate you will need to obtain AudienceProject API key (client_id and client_secret) and a UserReport account ID.
When you run a query in Explorer, it will prompt you for a Client ID and a Client Secret. You will need to pass the account ID in GraphQL queries and mutations.
To obtain a token programmatically you can use the following OAuth2 client_credentials flow:
You can generate your client_id and a client_secret via. the admin.audienceproject.com portal (API keys tab):
Note that you must be an admin to see this tab. Please contact support if you don't see this tab.
2. When you have your credentials ready you can exchange them to an access token.
You can use the AudienceProject OAuth server for this. The following example shows how an access token should be received. The authorization header string is Basic Base64Encode(client_id:client_secret).
curl --location --request POST 'https://api.audienceproject.com/oauth/v1/token' \
--header 'Accept: application/json' \
--header 'Authorization: Basic bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'
For more details please find AudienceProject OAuth API References Postman collection.
For ease of use inside Postman, note that you can store your client_id and client_secret in collection variables called client_id and client_secret and this Collection will automatically use it to make your API calls.
Each time you need to access API, you need to exchange long-living API keys to a short-living API token using the OAuth 2.0 client_credentials flow.
Send the obtained token as a Bearer authentication token with each request to an API.
ACCESS TOKEN RELATED ERROR RESPONSE
If an access token is missing, malformed, or invalid, you will receive a 401 Unauthorized response code and the following JSON response:
{
"errorType": "AuthenticationException",
"errorMessage": "The application is not authorized to access this resource."
}
If you try to get resources you don't have access to you will receive a 403 Forbidden response code.
The JavaScript code for doing this is:
const oauthEndpoint = 'https://api.audienceproject.com/oauth/v1/token';
const client_id = explorer.environment.get('client_id');
const client_secret = explorer.environment.get('client_secret');
const auth = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(`${client_id}:${client_secret}`));
const { body } = await fetch(oauthEndpoint, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': `Basic ${auth}`
},
body: 'grant_type=client_credentials',
});
if (body) {
console.log("Token set");
explorer.environment.set('token', body.token);
} else {
console.error("Unable to obtain token");
}
Main concepts
Touchpoint
Touchpoints are the core building block of your Explorer report. It represents a Media, Section, Media Title, Media Title section, Group or Measurement member.
It is a flat structure, but the relationship between entities are coded into the data structure. Composite touchpoints, like Media Titles, will have a property called atoms which describes the atomic parts (media and sections) it consists of.
Sections and Media Title Sections have a parentId that identifies the Media or Media Titles that logically owns it.
Explorer
Explorer has name, target group, sections to show in the UI and also one or two MediaSets.
MediaSet has: * name * date range * touchpoints
Date range can be a preset (e.g. YESTERDAY) or specific start/end-dates.
Touchpoints can be a preset (e.g. ALL_MY_MEDIA_TITLES) or list of touchpoint IDs. It is allowed to add Medias and their sections to one Explorer.
Workflow for working with the Kits Explorer API
Define setA:
touchpoints list or preset (e.g. ALL_MY_MEDIA)
reporting period or preset (e.g. YESTERDAY)
Define setB
Decide if you want to include your own not validated data. This is not included by default.
Decide on re-calculation schedule (makes sense only for presets)
Create Kits Explorer report
Wait for calculation (can take up to 8 hours)
Query the metrics you need
All API's - links to all FIAM related API Reference Documents and Playgrounds
API name | Purpose | Base endpoint | Reference / Playground |
Core Rest API | Manage owned medias/sections/media titles/media titles sections (trackpoints) Get access to trackpoints owned by FIAM members Get validation status of trackpoints on period | ||
Kits Rest API | Work with Kits (regardless of calculation method) | ||
Kits Explorer GraphQL API | Create Kits Explorer reports Get Kits Explorer API |