Ads (Publisher)

The /reports/ads resource provides access to detailed ad publishing data from all supported ad networks which are linked to the account.

Scope: All of the resources in this route require read access in the private scope (private:read).

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) Date, inclusive, to start reporting from. If you specify a granularity other than daily this will be rounded down to the nearest period. default: a long, long time ago.
end_date Date (yyyy-MM-dd) Date, inclusive, to stop reporting. If you specify a granularity other than daily this will be rounded up to the nearset period. default: distant future.
group_by List One or more pivots separated by a comma (,). Available pivots: product, country, date, store, and network.

Note: for the store and storefront options to work you’ll need to also set combine=true.

products List (productId | productId1, productId2, …) specific products to include in the response, default: all active products in account
countries List (isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries)
networks List Select only data from the given ad networks. Separate multiple networks with a comma. Default: all. Network names can be found using the /data/stores route.
format String Output format: JSON or CSV. Defaults to JSON.

Note: To prevent excessive repetition, when format is set to csv sub-objects (like the product in /ads/products/…) will not be fully serialized but only their reference will be.

Response

Field Type Description
requests Number The total number of requests made to the ad network. This metric is available for some networks. Where not available, requests will be set to 0.
requests_filled Number The total number of requests filled by the network. This metric is equivalent to impressions for most ad networks with the main exception being Unity, which counts impressions a bit 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. Some networks don’t provide requests, in which case this metric will be set to 0. Some networks don’t provide requests but do provide a fill rate, in which case we’ll pass on the fill rate instead of calculating it.
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. This is provided by the networks directly, when not, it is calculated by dividing clicks by impressions.
revenue Number The total revenue generated by ads, provided in the currency of the authenticated user.

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) Date, inclusive, to start reporting from. If you specify a granularity other than daily this will be rounded down to the nearest period. default: a long, long time ago.
end_date Date (yyyy-MM-dd) Date, inclusive, to stop reporting. If you specify a granularity other than daily this will be rounded up to the nearset period. default: distant future.
group_by List One or more pivots separated by a comma (,). Available pivots: product, country, date, store, and network.

Note: for the store and storefront options to work you’ll need to also set combine=true.

products List (productId | productId1, productId2, …) specific products to include in the response, default: all active products in account
countries List (isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries)
networks List Select only data from the given ad networks. Separate multiple networks with a comma. Default: all. Network names can be found using the /data/stores route.
format String Output format: JSON or CSV. Defaults to JSON.

Note: To prevent excessive repetition, when format is set to csv sub-objects (like the product in /ads/products/…) will not be fully serialized but only their reference will be.

Response

The leaves of the response follow the same value format as above, along with one or more group_by fields, corresponding to the request.

Field Type Description
product_id Number The id of the product this leaf is for. Returned when group_by includes “product”.
product Product A full product representation. 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 the date 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"
    },
    ...
  },
  ...
}