Ads

The /reports/ads resource provides access to detailed ads data across all supported ad networks.
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

start_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
(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
One or more pivots separated by a comma (,). Available pivots: product, country, date, store, and network.


products
(productId | productId1;productId2;productIdN) specific products to include in the response, default: all products in account


countries
(isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries)


networks
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
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

requests Int 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 Int 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 Int The total number of times a request resulted in an ad impression.
fillrate Float 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 Float The effective cost per thousand impressions, as reported by the ad network.
clicks Int The total number of times an ad was clicked.
ctr Float 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 Float 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

start_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
(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
One or more pivots separated by a comma (,). Available pivots: product, country, date, store, and network.


products
(productId | productId1;productId2;productIdN) specific products to include in the response, default: all products in account


countries
(isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries)


networks
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
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.

product_id Long 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"
    },
    ...
  },
  ...
}
  • Nikita Almakov

    Hello, I have a question about https://appfigures.com/ads/date reporting page. Looks like it’s possible to see a chart of requests for a specific application. Is it feasible for I haven’t been able to find Requests per Ad unit data in my Performance reports -> Ad units report?