Global Statistics API
This section describes the Global Statistics API request parameters and result data.
Note: The statistics API routes have been renamed:
- /statistics/advertiser/... -> /statistics/a/...
- /statistics/publisher/... -> /statistics/p/...
Note: The Global Statistics API only shows skipped RTB queries for Date, Sites, Zones, Countries, Regions, and Sub IDs.
Parameter | Description | Notes | Type |
---|---|---|---|
count | Return only the total of results. | integer | optional |
detailed | Get more detail if possible. | integer | optional |
timezone | Timezone setting for 'hour' filter and 'group_by' | string | optional |
totals | Indicates whether add totals to response or not. | integer | optional |
filter | Filters to restrict the returned values of a statistics query | object | optional |
group_by | A list of group by values to be applied in the data. Maximum four are permitted. | array | mandatory |
order_by | Ordering of results by a specific field(s). A maximum of two are permitted. | array | optional |
projection | Individual sub-structures a user wants to have returned in the response. | array | optional |
limit | The number of records to return in this response. | integer | optional |
offset | The position to retrieve the records from. | integer | optional |
Parameter count
Property | count |
Type | optional |
Variable type | integer |
Default Value | 0 |
Available values | [0, 1] |
Description | Return only the total of results. |
Example:
{
"count": 1
}
Parameter detailed
Property | detailed |
Type | optional |
Variable type | integer |
Default Value | 0 |
Available values | [0, 1] |
Description | Whether to return detailed information or not. |
Example:
{
"detailed": 1
}
Parameter timezone
Timezone setting for hour
filter and group_by
.
Property | timezone |
Type | optional |
Variable type | string |
Default Value | America/New_york |
Available values | Set timezone field of / collections / timezones |
Description | NOTE: Timezones are only relevant when we are querying based on hourly data, for non-hourly data this is a no-op. |
Example:
{
"timezone": "Europe/Dublin"
}
Parameter totals
Property | totals |
Type | optional |
Variable type | integer |
Default Value | 0 |
Available values | [0,1] |
Description | Indicates whether add totals to response or not. |
Example:
{
"totals": 1
}
Parameter filter
Property | filter |
Type | optional |
Variable type | object |
Available option for Advertisers | [”adblock”, ”advertiser_ad_type_id”, “browser_id”, “carrier_id”, “category_id”, “country_iso”, “date_from”, “date_to”, “device_id”, “device_type_id”, hour”, “language_id”, “operating_system_id”, “region_id”, “site_hostname”, “site_id”, “size”, “sub”, “zone_id”, “campaign_id”, “exclude_deleted”, “offer_id”, “offer_landing_page_id”, “variation_id”] |
Available option for Publishers | [”adblock”, “browser_id”, “carrier_id”, “category_id”, “country_iso”, “date_from”, “date_to”, “device_id”, “device_type_id”, “hour”, “language_id”, “operating_system_id”, “region_id”, “site_hostname”, “site_id”, “zone_id”, “publisher_ad_type_id”, “size”, “sub”] |
Description | Filter by certain parameters. |
Filter: country_iso
Property | country_iso |
Type | optional |
Variable type | string |
Default Value | - |
Available values | See /collections/countries endpoint iso3 property |
Description | List of ISO 3 code |
Example:
{
"filter": {
"country_iso": ["ESP", "IRL"]
}
}
Filter date_from
, date_to
The date_from
and date_to
parameters control the window over which you want to fetch stats information.
- date_from: Date from range for statistics, (Default beginning of month),
- date_to: Date to range for statistics, (Default today)
Property | date_from, date_to |
Type | optional |
Variable type | string |
Default Value | The dates default to the current month. |
Available values | YYYY-mm-dd |
Description | Date from/to range for statistics. Format YYYY-mm-dd |
Example:
{
"filter": {
"date_from": "2019-02-25",
"date_to": "2019-02-28"
}
}
Timezones are only relevant when we are querying based on hourly data, for non-hourly data this is a no-op.
Filter: advertiser_ad_type_id, campaign_id, browser_id, carrier_id, category_id, device_id, device_type_id, language_id, offer_id, offer_landing_page_id, operating_system_id, hour, region_id, site_id, sub, variation_id, zone_id, publisher_ad_type_id
Property | advertiser_ad_type_id, campaign_id, browser_id, carrier_id, category_id, device_id, device_type_id, language_id, offer_id, offer_landing_page_id, operating_system_id, hour, region_id, site_id, sub, variation_id, zone_id, advertiser_ad_type_id, publisher_ad_type_id |
Type | optional |
Variable type | array |
Items type | integer |
Default Value | - |
Available values | Relative properties OR collections |
Description | List of entity Ids |
Example:
{
"filter": {
"campaign_id": [123, 456],
"browser_id": [789]
}
}
Filter: exclude_deleted
Property | exclude_deleted |
Type | optional |
Variable type | integer |
Default Value | 0 |
Available values | [0, 1] |
Description | Whether to exclude deleted campaigns or not. |
Example:
{
"filter": {
"exclude_deleted": 1
}
}
Filter: adblock
Property | adblock |
Type | optional |
Variable type | string |
Default Value | "all" |
Available values | "adblock", "all", "standard" |
Description | Whether to include adblock zones or not. |
Example:
{
"filter": {
"adblock": "standard"
}
}
Filter: site_hostname
Property | site_hostname |
Type | optional |
Variable type | string |
Default Value | - |
Available values | Valid characters for hostnames are letters from a to z, the digits from 0 to 9, hyphen and dot. |
Description | Filter by site hostname. |
Example:
{
"filter": {
"site_hostname": ["www.example.com", "www.example-site.org"]
}
}
Filter: size
Property | size |
Type | optional |
Variable type | string |
Default Value | - |
Available values | Valid characters for size are the digits from 0 to 9 and x character. Example 300x100 |
Description | Filter by size |
Example:
{
"filter": {
"size": ["300x100"]
}
}
Parameter group_by
Property | group_by |
Type | mandatory |
Variable type | array |
Items type | string |
Default Value | - |
Available values for Advertisers | [”adblock”, “advertiser_ad_type_id”, browser_id”, “campaign_id”, “carrier_id”, “category_id”, “country_iso”, “date”, “hour”, “device_id”, “device_type_id”, “language_id”, “operating_system_id”, “region_id”, “site_id”, “sub”, “zone_id”, “week”, “month”, “quarter”, “year”, “offer_id”, “offer_landing_page_id”, “site_hostname”, “size”, “variation_id”] |
Available values for Publishers | [“adblock”, “browser_id”, “carrier_id”, “category_id”, “country_iso”, “date”, “device_id”, “device_type_id”, “hour”, “language_id”, “operating_system_id”, “publisher_ad_type_id” “region_id”, “site_id”, “size”, “sub”, “zone_id”, “week”, “month”, “quarter”, “year”] |
Description | A list of sub-requests to include additional data in response. |
Example:
{
"group_by": [
"browser",
"date"
]
}
Parameter order_by
Property | order_by |
---|---|
Type | optional |
Variable type | array |
Items type | string |
Default Value | - |
Available metrics field values | [“cpc”, “cpc”, “cpm”, “cpv”, “ctr”, “clicks”, “impressions”, “video_impressions”, “video_views”, “vtr”, “rtb_win_ratio”, “rtb_avg_total_time”, “rtb_skipped”, “rtb_bid_response_ratio”, “rtb_avg_cpm”, “rtb_timeouts_ratio”, “rt_errors_ratio”, “rtb_no_bid_ratio”, “rtb_skipped_ratio”] |
Available field values dependent on `group_by’ for Advertisers | [”adblock”, “browser_id”, “campaign_id”, “carrier_id”, “category_id”, “country_iso”, “device_id”, “date”, “device_type_id”, “hour”, “ecpa1”, “g1”,“language_id”, “month”, “offer_id”, “offer_landing_page_id”, “operating_system_id”, “quarter”, “region_id”, “site_hostname”, “site_id”, “sub”, “variation_id”, “week”, “year” ,“zone_id”] |
Available field values dependent on `group_by’ for Publishers | [“adblock”, “browser_id”, “carrier_id”, “category_id”, “country_iso”, “device_id”, “date”, “device_type_id” , “hour”, “language_id”, “month”, “operating_system_id”, “quarter”, “region_id”, “site_id”, “sub”, “week”, “year”, “zone_id”] |
Available order values | [“asc”, “desc”] |
Description | A list of available order by options |
Hints:
- The metrics fields are available all the time to use as order by field.
- To order by specific value (for example by “browser_id”), you need to include it in “group_by” parameter.
The “g1”, “ecpa1” values are only available when user has Conversion Tracking (Goals). All goals associated with a serial number (g1, g2, …gx). The eCPA values are accordingly ecpa1, ecpa2, …ecpax.
Example:
{
"order_by": [
{
"field": "impressions",
"order": "desc"
}
]
}
Example to organize the campaign results chronologically, the “date” need to be included in both “group_by” and “order_by”:
{
"group_by": [
"campaign_id",
"date"
],
"order_by":[
{
"field": "date",
"order": "asc"
}
]
}
Parameter projection
The projection parameter reflects what will be returned in the resulting payload. If not specified all sub structures will be returned.
Property | projection |
---|---|
Type | optional |
Variable type | object |
Items type | array |
Default value | all options, see below |
Available field values for Advertisers | [“base”, “rtb”, “video”, “goals*”] |
Available field values for Publishers | [“base”, “rtb”, “video”, “wpn”] |
*Some "goal" fields, like "profit" and "roi", are calculated based on the cost of the campaign, so you must also use "base" field if you want to receive the correct "goals" metrics.
Examples:
In order to receive all possible metrics as an advertiser, use:
{
"projection": {
"base": ["*"],
"video": ["*"],
"goals": ["*"],
"rtb": ["*"]
}
}
In order to receive all possible metrics as a publisher, use:
{
"projection": {
"base": ["*"],
"video": ["*"],
"wpn": ["*"],
"rtb": ["*"]
}
}
You can also specify the metrics within each projection field:
{
"projection": {
"base": ["impressions","clicks","cost","revenue","cpc","cpm","ctr"],
"video": ["impressions","views","cpv","vtr"],
"rtb": ["total_time","queries","value","success","no_bid","skipped","errors","timeouts","wins","win_ratio"],
//only for Publishers
"wpn": ["subscriptions","unsubscriptions","sent"]
}
}
The only field that does not allow specific metric projection is "goals"
Parameter limit
The number of records to return in this response.
Property | limit |
Type | optional |
Variable type | integer |
Default Value | 50 |
Example:
{
"limit": 25
}
Parameter offset
The position to retrieve the records from.
Property | offset |
Type | optional |
Variable type | integer |
Default Value | 0 |
Example
{
"offset": 150
}
Example 1
Advertiser campaign statistic with filtering.
Request:
{
"detailed": true,
"totals": 1,
"filter": {
"date_from": "2019-03-10",
"date_to": "2019-03-11",
"country_iso": ["USA"]
},
"group_by": ["campaign_id"],
"order_by": [
{
"field": "campaign_id",
"order": "desc"
}
]
"projection": {
"base": ["*"],
"video": ["*"],
"rtb": ["*"]
},
"limit": 2,
"offset": 0
}
Response:
{
"request_metadata": {
"count": 4,
"limit": 2,
"offset": 0
},
"result": [
{
"clicks": 0,
"cost": 1.3302,
"cpc": 0,
"cpm": 0.45586017820425,
"ctr": 0,
"group_by": {
"campaign_id": {
"active": "1",
"campaign_ad_type_name": "Popunders",
"id": "1234567",
"name": "Ron Mainstream Campaign "
}
},
"impressions": 2918,
"rtb": {
"avg_cpm": 0.15582967823432,
"avg_total_time": 89.522714492492,
"errors": 112,
"errors_ratio": 0.011368411650186,
"no_bid": 870594,
"no_bid_ratio": 88.368490823053,
"queries": 985186,
"response_ratio": 11.57101298638,
"skipped": 0,
"skipped_ratio": 0,
"success": 984590,
"timeouts": 484,
"timeouts_ratio": 0.049127778916875,
"total_time": 88196525,
"value": 1776.396,
"win_ratio": 0.29842080581738,
"wins": 2940
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
},
{
"clicks": 0,
"cost": 18.1621655,
"cpc": 0,
"cpm": 1.8273634671496,
"ctr": 0,
"group_by": {
"campaign_id": {
"active": "1",
"campaign_ad_type_name": "Popunders",
"id": "7654321",
"name": "Ron Mainstream Campaign Test"
}
},
"impressions": 9939,
"rtb": {
"avg_cpm": 1.4753505300475,
"avg_total_time": 88.777190144965,
"errors": 46,
"errors_ratio": 0.0014192869995779,
"no_bid": 3209674,
"no_bid_ratio": 99.031490893114,
"queries": 3241064,
"response_ratio": 0.8964340105595,
"skipped": 0,
"skipped_ratio": 0,
"success": 3238728,
"timeouts": 2290,
"timeouts_ratio": 0.070655809326814,
"total_time": 287732555,
"value": 4286.48343,
"win_ratio": 0.30665855410445,
"wins": 9939
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
}
],
"result_total": {
"clicks": 0,
"cost": 74.0473595,
"cpc": 0,
"cpm": 2.0864288391096,
"ctr": 0,
"impressions": 35490,
"rtb": {
"avg_cpm": 0.23441613972984,
"avg_total_time": 87.995789332859,
"errors": 539,
"errors_ratio": 0.0049868154705264,
"no_bid": 9771471,
"no_bid_ratio": 90.405422546568,
"queries": 10808501,
"response_ratio": 9.5135301370653,
"skipped": 0,
"skipped_ratio": 0,
"success": 10799741,
"timeouts": 8221,
"timeouts_ratio": 0.07606050089647,
"total_time": 951102577,
"win_ratio": 0.32861171035651,
"wins": 35518
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
}
}
Example 2
Advertiser statistic by date for the current month ordered by impressions.
Request:
{
"group_by": ["date"],
"order_by": [
{
"field": "impressions",
"order": "desc"
}
]
"projection": {
"base": ["*"],
"video": ["*"],
"rtb": ["*"]
}
}
Response:
{
"request_metadata": {
"count": 3,
"limit": 50,
"offset": 0
},
"result": [
{
"clicks": 0,
"cost": 624.2439917,
"cpc": 0,
"cpm": 1.0978015474007,
"ctr": 0,
"group_by": {
"date": {
"date": "2019-03-02"
}
},
"impressions": 568631,
"rtb": {
"avg_cpm": 0.31273156270632,
"avg_total_time": 114.34705591799,
"errors": 4143,
"errors_ratio": 0.0076578188576312,
"no_bid": 48085697,
"no_bid_ratio": 88.8804144989,
"queries": 54101567,
"response_ratio": 10.971772776933,
"skipped": 0,
"skipped_ratio": 0,
"success": 54021598,
"timeouts": 75826,
"timeouts_ratio": 0.14015490530986,
"total_time": 6186354907,
"value": 185634.35958,
"win_ratio": 1.1633248996281,
"wins": 629377
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
},
{
"clicks": 0,
"cost": 622.1688691,
"cpc": 0,
"cpm": 1.1800128762878,
"ctr": 0,
"group_by": {
"date": {
"date": "2019-03-01"
}
},
"impressions": 527256,
"rtb": {
"avg_cpm": 0.27775587567531,
"avg_total_time": 118.91585420372,
"errors": 2954,
"errors_ratio": 0.0078196779097434,
"no_bid": 32641750,
"no_bid_ratio": 86.407573260111,
"queries": 37776492,
"response_ratio": 13.412992397494,
"skipped": 0,
"skipped_ratio": 0,
"success": 37708708,
"timeouts": 64830,
"timeouts_ratio": 0.17161466448499,
"total_time": 4492223815,
"value": 140737.73563,
"win_ratio": 1.4077723257099,
"wins": 531807
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
},
{
"clicks": 0,
"cost": 441.843491,
"cpc": 0,
"cpm": 0.96186339096399,
"ctr": 0,
"group_by": {
"date": {
"date": "2019-03-03"
}
},
"impressions": 459362,
"rtb": {
"avg_cpm": 0.26462497173837,
"avg_total_time": 116.9210100884,
"errors": 2183,
"errors_ratio": 0.0059889808787451,
"no_bid": 32174177,
"no_bid_ratio": 88.268681100486,
"queries": 36450275,
"response_ratio": 11.500815837466,
"skipped": 0,
"skipped_ratio": 0,
"success": 36366256,
"timeouts": 81836,
"timeouts_ratio": 0.22451408116948,
"total_time": 4261802971,
"value": 110932.87869,
"win_ratio": 1.2852029237091,
"wins": 468460
},
"video": {
"cpv": 0,
"impressions": 0,
"views": 0,
"vtr": 0
}
}
]
}
Example 3
Publisher statistic by date and region_id, ordered by impressions.
Request:
{
"detailed": true,
"filter": {
"date_from": "2019-03-10",
"date_to": "2019-03-11",
"country_iso": ["USA"]
},
"group_by": ["date", "region_id"],
"order_by": [
{
"field": "impressions",
"order": "desc"
}
],
"projection": {
"base": ["*"],
"video": ["*"],
"wpn": ["*"],
"rtb": ["*"]
}
"limit": 30,
"offset": 0
}
Response:
{
"request_metadata": {
"count": 2,
"limit": 30,
"offset": 0
},
"result": [
{
"clicks": 3087,
"cpc": 0.033842716164561,
"cpm": 0.069188574849649,
"ctr": 0.20444155402072,
"group_by": {
"date": {
"date": "2019-03-11"
},
"region_id": {
"country_iso": "USA",
"country_long_name": "United States of America",
"country_short_name": "United States",
"id": 5332921,
"name": "California"
}
},
"impressions": 1494954,
"revenue": 104.4724648,
"rtb": {
"avg_cpm": 0,
"avg_total_time": 0,
"bid_response_ratio": 0,
"errors": 0,
"errors_ratio": 0,
"no_bid": 0,
"no_bid_ratio": 0,
"queries": 0,
"skipped": 0,
"skipped_ratio": 0,
"success": 0,
"timeouts": 0,
"timeouts_ratio": 0,
"total_time": 0,
"value": 0,
"win_ratio": 0,
"wins": 0
},
"video": {
"cpv": 0.038451404048583,
"impressions": 15013,
"views": 2717,
"vtr": 18.097648704456
},
"wpn": {
"subscriptions": 0,
"unsubscriptions": 0
}
},
{
"clicks": 3071,
"cpc": 0.03151133555845,
"cpm": 0.066658890819906,
"ctr": 0.21153940205505,
"group_by": {
"date": {
"date": "2019-03-10"
},
"region_id": {
"country_iso": "USA",
"country_long_name": "United States of America",
"country_short_name": "United States",
"id": 5332921,
"name": "California"
}
},
"impressions": 1436818,
"revenue": 96.7713115,
"rtb": {
"avg_cpm": 0,
"avg_total_time": 0,
"bid_response_ratio": 0,
"errors": 0,
"errors_ratio": 0,
"no_bid": 0,
"no_bid_ratio": 0,
"queries": 0,
"skipped": 0,
"skipped_ratio": 0,
"success": 0,
"timeouts": 0,
"timeouts_ratio": 0,
"total_time": 0,
"value": 0,
"win_ratio": 0,
"wins": 0
},
"video": {
"cpv": 0.036216808196108,
"impressions": 14921,
"views": 2672,
"vtr": 17.907646940554
},
"wpn": {
"subscriptions": 0,
"unsubscriptions": 0
}
}
]
}
Example 4
Publisher statistic by site_id with projection.
Request:
{
"detailed": true,
"projection": {
"base": ["*"],
"video": ["*"],
"wpn": ["*"],
"rtb": ["*"]
},
"filter": {
"date_from": "2019-03-10",
"date_to": "2019-03-11",
"country_iso": ["USA"]
},
"group_by": ["site_id"],
"order_by": [
{
"field": "impressions",
"order": "desc"
}
],
"limit": 30,
"offset": 0
}
Response
{
"request_metadata": {
"count": 2,
"limit": 30,
"offset": 0
},
"result": [
{
"clicks": 14320,
"cpc": 0.028298959692737,
"cpm": 0.057945765404939,
"ctr": 0.20476288186597,
"group_by": {
"site_id": {
"id": "11223344",
"name": "nice-example.com"
}
},
"impressions": 6916414,
"revenue": 405.2411028,
"rtb": {
"avg_cpm": 0,
"avg_total_time": 0,
"bid_response_ratio": 0,
"errors": 0,
"errors_ratio": 0,
"no_bid": 0,
"no_bid_ratio": 0,
"queries": 0,
"skipped": 0,
"skipped_ratio": 0,
"success": 0,
"timeouts": 0,
"timeouts_ratio": 0,
"total_time": 0,
"value": 0,
"win_ratio": 0,
"wins": 0
},
"video": {
"cpv": 0.031519102652252,
"impressions": 77041,
"views": 12857,
"vtr": 16.688516504199
},
"wpn": {
"subscriptions": 0,
"unsubscriptions": 0
}
},
{
"clicks": 14148,
"cpc": 0.028769196296296,
"cpm": 0.063791981699323,
"ctr": 0.22173710048179,
"impressions": 6314909,
"revenue": 407.0265892,
"rtb": {
"avg_cpm": 0,
"avg_total_time": 0,
"bid_response_ratio": 0,
"errors": 0,
"errors_ratio": 0,
"no_bid": 0,
"no_bid_ratio": 0,
"queries": 0,
"skipped": 0,
"skipped_ratio": 0,
"success": 0,
"timeouts": 0,
"timeouts_ratio": 0,
"total_time": 0,
"value": 0,
"win_ratio": 0,
"wins": 0
},
"video": {
"cpv": 0.036406671663685,
"impressions": 65620,
"views": 11180,
"vtr": 17.037488570558
},
"wpn": {
"subscriptions": 0,
"unsubscriptions": 0
}
}
]
}