Global Statistics API

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

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 two 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 See 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 [”browser_id”, “carrier_id”, “category_id”, “country_iso”, “date_from”, “date_to”, “device_id”, “hour”, “language_id”, “operating_system_id”, “region_id”, “site_hostname”, “site_id”, “zone_id”, “campaign_id”, “campaign_group_id”, “exclude_deleted”, “offer_id”, “offer_landing_page_id”, “variation_id”]
Available option for Publishers [”browser_id”, “carrier_id”, “category_id”, “country_iso”, “date_from”, “date_to”, “device_id”, “hour”, “language_id”, “operating_system_id”, “region_id”, “site_hostname”, “site_id”, “zone_id”, “adblock”, “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_fromand 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 campaign_id, campaign_group_id, browser_id, carrier_id, category_id, device_id, language_id, offer_id, offer_landing_page_id, operating_system_id, hour, region_id, site_id, sub, variation_id, zone_id

Property campaign_id, campaign_group_id, browser_id, carrier_id, category_id, device_id, language_id, offer_id, offer_landing_page_id, operating_system_id, hour, region_id, site_id, sub, variation_id, zone_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 array
Items type string
Default Value “all”
Available values “adblock”, “all”, “standard”
Description Whether 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"]
        }
    }

Parameter group_by

Property group_by
Type mandatory
Variable type array
Items type string
Default Value -
Available values for Advertisers [“browser_id”, “carrier_id”, “category_id”, “country_iso”, “device_id”, “language_id”, “operating_system_id”, “region_id”, “site_id”, “zone_id”, “date”, “hour”, “week”, “month”, “quarter”, “year”, “campaign_id”, “campaign_group_id”, “offer_id”, “offer_landing_page_id”, “site_hostname”, “variation_id”]
Available values for Publishers [“browser_id”, “carrier_id”, “category_id”, “country_iso”, “device_id”, “language_id”, “operating_system_id”, “region_id”, “site_id”, “zone_id”, “date”, “hour”, “week”, “month”, “quarter”, “year”, “adblock”, “sub”]
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 field values [“cpc”, “cpc”, “cpm”, “cpv”, “ctr”, “clicks”, “impressions”, “operating_system_id”, “video_impressions”, “video_views”, “vtr”, “date”, “hour”, “week”, “month”, “quarter”, “year”]
Available field values dependent on `group_by’ for Advertisers [“browser_id”, “carrier_id”, “category_id”, “country_iso”, “device_id”, “language_id”, “region_id”, “site_id”, “zone_id”, “campaign_id”, “campaign_group_id”, “offer_id”, “offer_landing_page_id”, “site_hostname”, “variation_id”, “g1”, “ecpa1”]
Available field values dependent on `group_by’ for Publishers [“browser_id”, “carrier_id”, “category_id”, “country_iso”, “device_id”, “language_id”, “region_id”, “site_id”, “zone_id”, “adblock”, “sub”]
Available order values [“asc”, “desc”]
Description A list of available order by options

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"
        }
      ]
    }

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 array
Items type string
Default Value all options, see below
Available field values for Advertisers [“rtb”, “video”, “goals”]
Available field values for Publishers [“rtb”, “video”, “wpn”]

Example:

    {
      "projection": [
        "video"
      ]
    }

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

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-03"
            }
          },
          "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-04"
            }
          },
          "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"
        }
      ],
      "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": ["wpn", "video", "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
          }
        }
      ]
    }