Advertising Reporting API Documentation
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.
- https://api.sovrn.com/reporting/advertising/publishers/:publisherId/account
- https://api.sovrn.com/reporting/advertising/publishers/:publisherId/bid
- https://api.sovrn.com/reporting/advertising/publishers/:publisherId/breakout
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.