Getting started with Kits Explorer API

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:

1. You can generate your client_id and a client_secret via. the admin.audienceproject.com portal (API keys tab):

   

1. 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

1. Define setA:
   1. touchpoints list or preset (e.g. ALL_MY_MEDIA)
   2. reporting period or preset (e.g. YESTERDAY)
2. Define setB
3. Decide if you want to include your own not validated data. This is not included by default.
4. Decide on re-calculation schedule (makes sense only for presets)
5. Create Kits Explorer report
6. Wait for calculation (can take up to 8 hours)
7. Query the metrics you need

All API's - links to all FIAM related API Reference Documents and Playgrounds