API Best Practices

Best practices 

The AudienceReport API facilitates access to report and items data, allowing users to retrieve, filter and analyze information efficiently. This documentation outlines best practices for utilizing the API effectively.

Paging

All GET endpoints in AudienceReport API provide cursor-based pagination. It utilizes two optional parameters:

  • pageSize - the number of items per page. Default value is 50, maximum is 100
  • cursor - the pagination starting point. If not specified, pagination starts from the beginning of the result collection. Next page cursor can be obtained from the response:

"pagination": {

  "hasNextPage": true, //can be used as an iteration stop condition

  "nextCursor": "NA==",//next page starting point

  "totalCount": 10 //total number of items that fall under the query conditions

}

Paging request example:

curl -X 'GET' \  'https://api.audienceproject.com/audiencereport/v2/accounts/countries?pageSize=5&cursor=NA%3D%3D

' \

  -H 'accept: application/json'

Response:

{

    "pagination": {

        "hasNextPage": false,

        "nextCursor": "Ng==",

        "totalCount": 7

    },

    "data": [...]

}

Filtering

AudienceReport API supports generic search with a q parameter. Depending on the endpoint q search is applied to different fields that seem logical.

Search request example:

curl -X 'GET' \  'https://api.audienceproject.com/audiencereport/v2/accounts/countries?q=ABC

' \

  -H 'accept: application/json'

Account

Search query applies to such fields:

  • Name
  • CID

Additional filters:

  • accountIds - filter by ids
  • agencyAccountId - filter all client accounts that belong to an agency
  • type - filter by account type (Client, Agency)
  • isActive - filter active/inactive accounts

Channel

Search query applies to such fields:

  • Name
  • Internal channel ID

Additional filters:

  • clientAccountId - filter by client account
  • agencyAccountId - filter all client accounts that belong to an agency
  • channelIds - filter by ids
  • platformCode - filter by platform

Country

Search query applies to such fields:

  • Country code
  • Name

Items

Search query applies to such fields:

  • Name
  • Trackpoint CID
  • Trackpoint ID

Additional filters:

  • clientAccountId - filter by client account
  • agencyAccountId - filter all client accounts that belong to an agency
  • itemIds - filter by ids
  • parentId - filter items by parent item
  • channelId - filter by channel
  • level - filter by item level (Campaign, LineItem, etc.)
  • platformCode - filter by platform
  • externalId - filter by item’s external ID

Platform

Search query applies to such fields:

  • Platform code
  • Name

Additional filters:

  • clientAccountId - filter by client account
  • agencyAccountId - filter all client accounts that belong to an agency

Report

Search query applies to such fields:

  • Name
  • Country code

Additional filters:

  • clientAccountId - filter by client account
  • agencyAccountId - filter all client accounts that belong to an agency
  • reportIds - filter by ids
  • itemId - filter by item included to a report
  • isArchived - filter archived/active reports
  • label - filter reports by labels

Sorting

Sorting in the AudienceReport API is applied using the orderBy parameter. Expected format orderBy={fieldName},{direction}. Supported directions - asc, desc, if not specified sorted by ascending. Both field names and directions are case insensitive.

Request example

curl -X 'GET' \ 'https://api.audienceproject.com/audiencereport/v2/accounts/countries?orderBy=Name%2Cdesc' \

  -H 'accept: application/json'

Supported fields for sorting:

Account

  • AccountId
  • Name
  • Cid
  • Type
  • AgencyAccountId
  • IsActive

Channel

  • Id
  • Name
  • PlatformCode
  • ClientAccountId
  • InternalChannelId
  • IsEditable
  • CreatedAt
  • UpdatedAt

Country

  • CountryCode
  • Name

Item

  • Id
  • Name
  • PlatformCode
  • ClientAccountId
  • ChannelId
  • Level
  • ExternalId
  • Cid
  • TailCode
  • CreatedAt
  • UpdatedAt

Platform

  • Code
  • Name

Report

  • Id
  • Name
  • ClientAccountId
  • CountryCode
  • StartDate
  • EndDate
  • CreatedAt
  • UpdatedAt
  • IsArchived

Error handling

For a number of reasons the report calculation may fail, the data will not be provided. More details on the execution issues can be found as part of report output:

"output": {

   "status": "Failed",

   "executionIssues": [

     {

       "issueCategoryCode": "string",

       "issueCode": "string",

       "issueDetails": [

         {

           "key": "string",

           "value": "string"

         }

       ]

     }

   ]

}

How did we do?

How do I use the AudienceReport Next API?

Contact