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