Ad Spend (Advertiser Analytics)

The /reports/adspend resource provides access to detailed campaign data across all supported ad networks.

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

Getting spend totals

Request

GET /reports/adspend?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.
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
installs Number The total number of installs generated by ad campaigns.
clicks Number The number of times an ad from your campaign was clicked/tapped.
impressions Number The number of times one of the ads in your campaign was seen.
cost Money The total amount of money spent on campaigns.
cpc Money The average amount a single click cost.
cpa Money The average amount of money a single acquisition (install) cost.
ctr Percent A number between 0 and 1 representing the click-through rate for all ads in the campaign.

Example Response for totals for the last 30 days

GET /reports/ads?start_date=-30

{
  "installs": 1000,
  "clicks": 15000,
  "impressions": 239012,
  "cost": "12123.94",
  "cpc": "0.86",
  "cpa": "12.94",
  "ctr": "0.06",
  "date": "2018-05-08"
}

Getting spend details

Request

GET /reports/adspend?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.
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 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

{
  "2018-05-08": {
    "installs": 1000,
    "clicks": 15000,
    "impressions": 239012,
    "cost": "12123.94",
    "cpc": "0.86",
    "cpa": "12.94",
    "ctr": "0.06",
    "date": "2018-05-08"
  },
  ...
}