Ads (Advertiser)

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

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, …) specific products to include in the response, default: all active 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

installs Int The total number of installs generated by ad campaigns.
clicks Int The number of times an ad from your campaign was clicked/tapped.
impressions Int The number of times one of the ads in your campaign was seen.
cost Float The total amount of money spent on campaigns.
cpc Float The average amount a single click cost.
cpa Float The average amount of money a single acquisition (install) cost.
ctr Float 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 ad details

Request

GET /reports/adspend?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, …) specific products to include in the response, default: all active 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

{
  "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"
  },
  ...
}