API Reference

Web Display & Video Custom API

Required Query Parameters and Their Possible Values

Required Parameters

There are 5 required parameters needed to make a successful request to the Custom Reporting API.

  • start: This is a date string that follows the ISO date format, i.e. 2021-08-10T19:00:00Z (This value is INCLUSIVE, meaning items matching it are included in the response.)
  • end: This is a date string that follows the ISO date format, i.e. 2021-08-10T20:00:00Z (This value is EXCLUSIVE, meaning items matching it are NOT included in the response. )
  • metrics: This should be a comma separated string, i.e. ‘requests,impressions’
  • dimensions: This should be a comma separated string, i.e. ‘endpoint,country,demandPartnerId’
  • granularity: This is the level of granularity for returned data, i.e. "hour", "day", "month".
⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼

Query Notes

For the start and end parameters, please request in UTC (providing the “Z” at the end for the offset). Specifying a timezone is a future feature. Also, please only request one hour, one day, or one month in a request. The endpoints will automatically determine which data aggregation to use.

Granularity

There are limitations in place for how much data you can request, depending on the type of granularity provided in the request. We have the following data available for each granularity:

  • hour:for the past 45 days
  • day: for the past 2 years
  • month:starting with January 2017
  • Note: many of our dimensions are not available back to 2017, most are available starting in 2022.

You cannot request all of the available data for a granularity in one request. The limitations in one request are:

  • hour: minimum of 1 hour, maximum of 24 hours
  • day: minimum of 1 day, maximum of 1 month (depending on the month, this can range from 28 days to 31 days)
  • month: minimum of 1 month, maximum of 1 year
⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼

Possible Values

Metrics:

  • requests
  • requestsWithBid
  • impressions
  • publisherRevenue
  • fillRate
  • cpm

Dimensions:

  • auction - traffic generated from (e.g Header Bidding, Google OB, Amazon TAM, Waterfall, ORTB)
  • zoneId - Unique ID associated to a Sovrn ad tag
  • zoneSize - Size of that zone (e.g 728x90)
  • zoneName - Unique name given to that ID within the account (ex. RON_728x90)
  • country - country of generated traffic (e.g. us, ca, de)
  • demandPartnerId - DSP (e.g TradeDesk)
  • seatId - DSP seat, its an identifier for the Advertiser/advertiser group that is placing creatives
  • dealId - Deal info, used to identify deals and their performance
  • advertiser - The url of the advertiser (e.g Nike.com)
  • adType - format in which an ad was served (e.g video, display)
  • device - type of device where an ad was served (e.g smartphone, tablet, desktop)
  • browser - browser in which an ad was served (e.g Chrome, Firefox, Safari)
  • domain - domain in which the ad was served on (e.g www.sovrn.com). (If domain is included in the query, all reporting data will be for the provided domain. If not included, all domains will be included.)