Global Statistics API

This section describes the Global Statistics API request parameters and result data.

The statistics API routes have been renamed:

• /statistics/advertiser/... -> /statistics/a/...
• /statistics/publisher/... -> /statistics/p/...

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_group_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_group_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_group_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”, “idcampaign_group“, “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
      }
    }
  ]
}