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