Getting Started

Initial Setup

Before you begin using the Sovrn Advertising API you will need to create an API Key on your account where you will be provided with your Publisher ID and the API Key value. The API Key is used for authorization to give access to your account’s data. The following sections will provide you with more information about the Reporting API.

⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼

Data Retention

The data in the Reporting API is broken up into three levels of aggregation, with different retention periods:

Hourly (10 days)
Daily (2 years)
Monthly (indefinite)

However, as some of the data provided is new, we are unable to backfill to fill up the retention periods. Data will be available starting from 10/01/2021. The Daily and Monthly aggregations are only available in UTC.

API Endpoints

Account Level Reporting

For account level information, replace the :publisherId with your publisher ID.

Domain Level Reporting

For Domain level information, replace the :publisherId with your publisher ID and the :domainName with the domain you are wanting reports from.

How to Provide the API Key to Pass Authentication

The API Key is provided as part of the request header, as a key/value pair (find detailed instructions here). The header name is ‘x-api-key’ and the value is the API Key that you have received. It will be a 7 character sequence followed by a ‘.’ and then a 32 character UUID. It will look like the following:


          1234567.a34d7eb0-abfc-44fea-9fcc-7es42be45663

Example Request

Below is an example CURL request that you can run to verify everything is working correctly:

        
          curl --request GET \ --url
          'https://api.sovrn.com/reporting/advertising/publishers/262681/domains/sovrntest.com/account?start=2021-08-01T00%3A00%3A00Z&end=2021-09-02T00%3A00%3A00Z&metrics=publisherRevenue&dimensions=domain%2CzoneId'
          \ --header 'x-api-key: prefix1.XXXXXXXX-YYYY-ZZZZ-AAAA-BBBBBBBBBBBB'

Rate Limit Quotas

How to View Response Header Information About Rate Limiting

A Publisher can make up to 15 requests every 1 minute, based on API key. If you go over that number you will receive an error, with a message telling you you have gone over the amount.

In addition, we are limiting overall requests per IP address to 2000 requests every 5 minutes.

Contact

If you have any questions or feedback about this documentation and the Advertising Reporting API, please contact support.