Ads (Publisher)

Use /reports/ads to get ad publishing data from every supported ad network linked to your account.

Getting Ads Totals

Request

GET /reports/ads?group_by={group_by}&start_date={start_date}&end_date={end_date}&products={products}&countries={countries}&networks={networks}&format={format}

Arguments

Argument	Type	Description
start_date	Date	(yyyy-MM-dd) First date to report on, inclusive. With a granularity other than daily, we round it down to the nearest period. Default: the earliest data available.
end_date	Date	(yyyy-MM-dd) Last date to report on, inclusive. With a granularity other than daily, we round it up to the nearest period. Default: the latest data available.
group_by	List	One or more pivots, separated by commas. Available pivots: product, country, date, store, and network. Note: For the store and storefront options to work, you’ll also need to set combine=true.
products	List	(productId \| productId1, productId2, …) Products to include in the response. Default: all active products in your account.
countries	List	(isoCode \| isoCode1;isoCode2;isoCodeN) Countries to limit the report to. Get country codes from /data/countries. Default: all countries.
networks	List	Only include data from these ad networks. Separate multiple networks with commas. Default: all. Get network names from the /data/stores route.
format	String	Output format: JSON or CSV. Defaults to JSON. Note: With `format=csv`, we don’t fully serialize sub-objects (like the product in /ads/products/…), only their reference, to avoid repetition.

Response

Field	Type	Description
requests	Number	The total number of requests made to the ad network. Only some networks report it. Where they don’t, requests is 0.
requests_filled	Number	The total number of requests filled by the network. For most ad networks this equals impressions. The main exception is Unity, which counts impressions differently.
impressions	Number	The total number of times a request resulted in an ad impression.
fillrate	Number	A number between 0 and 1 representing the percent of filled requests, calculated by dividing requests_filled by requests. If a network doesn’t provide requests, fillrate is 0. If it doesn’t provide requests but does provide a fill rate, we pass on its fill rate instead of calculating one.
ecpm	Number	The effective cost per thousand impressions, as reported by the ad network.
clicks	Number	The total number of times an ad was clicked.
ctr	Number	A number between 0 and 1 representing the click-through rate. We use the network’s CTR when it provides one. Otherwise, we calculate it by dividing clicks by impressions.
revenue	Number	The total revenue from ads, in the authenticated user’s currency.

Example Response for AdMob and Chartboost Totals for the Last 30 Days

// /reports/ads?networks=admob,chartboost&start_date=-30

{
  "revenue": "27219.15",
  "requests": 609865,
  "impressions": 599204,
  "requests_filled": 599204,
  "ecpm": "0.25",
  "fillrate": "0.96",
  "ctr": "0.03",
  "clicks": 1771
}

Getting Ad Details

Request

GET /reports/ads?group_by={group_by}&start_date={start_date}&end_date={end_date}&products={products}&countries={countries}&format=csv

Arguments

Argument	Type	Description
start_date	Date	(yyyy-MM-dd) First date to report on, inclusive. With a granularity other than daily, we round it down to the nearest period. Default: the earliest data available.
end_date	Date	(yyyy-MM-dd) Last date to report on, inclusive. With a granularity other than daily, we round it up to the nearest period. Default: the latest data available.
group_by	List	One or more pivots, separated by commas. Available pivots: product, country, date, store, and network. Note: For the store and storefront options to work, you’ll also need to set combine=true.
products	List	(productId \| productId1, productId2, …) Products to include in the response. Default: all active products in your account.
countries	List	(isoCode \| isoCode1;isoCode2;isoCodeN) Countries to limit the report to. Get country codes from /data/countries. Default: all countries.
networks	List	Only include data from these ad networks. Separate multiple networks with commas. Default: all. Get network names from the /data/stores route.
format	String	Output format: JSON or CSV. Defaults to JSON. Note: With `format=csv`, we don’t fully serialize sub-objects (like the product in /ads/products/…), only their reference, to avoid repetition.

Response

The leaves use the same format as above, plus one or more group_by fields that match your request.

Field	Type	Description
product_id	Number	The ID of the product this leaf is for. Returned when `group_by` includes “product”.
product	Product	The full product object. Returned when `group_by` includes “product”.
country	String	The full name of the country this leaf is for. Returned when `group_by` includes “countries”.
iso	String	The ISO code of the country this leaf is for. Returned when `group_by` includes “countries”.
date	String	The date this leaf is for, in yyyy-mm-dd format. Returned when `group_by` includes “dates”.

Example Response for by Day

// GET /reports/ads/?group_by=dates&start_date=-30

{
  "2016-12-25": {
    "revenue": "2034.05",
    "requests": 50768,
    "impressions": 49881,
    "requests_filled": 49881,
    "ecpm": "1.31",
    "fillrate": "0.98",
    "ctr": "0.05",
    "clicks": 250,
    "date": "2016-12-25"
  },
  ...
}

Example Response for by Country

// GET /reports/ads/?group_by=country&start_date=-30

{
  "US": {
    "revenue": "10456.11",
    "requests": 12537212,
    "impressions": 10187114,
    "requests_filled": 10187114,
    "ecpm": "0.45",
    "fillrate": "0.81",
    "ctr": "0.03",
    "clicks": 308761,
    "country": "United States",
    "iso": "US"
  },
  "IL": {
    "revenue": "2034.05",
    "requests": 50768,
    "impressions": 49881,
    "requests_filled": 49881,
    "ecpm": "1.31",
    "fillrate": "0.98",
    "ctr": "0.05",
    "clicks": 250,
    "country": "Israel",
    "iso": "IL"
  },
  ...
}

Example Response for by Day + Country

// GET /reports/ads/?group_by=dates,countries&start_date=-30

{
  "2016-12-25": {
    "US": {
      "revenue": "10456.11",
      "requests": 12537212,
      "impressions": 10187114,
      "requests_filled": 10187114,
      "ecpm": "0.45",
      "fillrate": "0.81",
      "ctr": "0.03",
      "clicks": 308761,
      "country": "United States",
      "iso": "US"
    },
    "IL": {
      "revenue": "2034.05",
      "requests": 50768,
      "impressions": 49881,
      "requests_filled": 49881,
      "ecpm": "1.31",
      "fillrate": "0.98",
      "ctr": "0.05",
      "clicks": 250,
      "country": "Israel",
      "iso": "IL"
    },
    ...
  },
  ...
}