全局统计 API

本节描述 Global Statistics API 的请求参数和结果数据。

统计 API 路由已重命名：

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

Global Statistics API 仅显示 Date、Sites、Zones、Countries、Regions 和 Sub IDs 的已跳过 RTB 查询。

参数	描述	备注	类型
计数	仅返回结果总数。	整数	可选
详细	如有可能，获取更多详细信息。	整数	可选
时区	用于 'hour' 过滤器和 'group_by' 的时区设置	字符串	可选
总计	指示是否在响应中添加总计。	整数	可选
过滤	用于限制统计查询返回值的过滤器	对象	可选
group_by	要应用于数据中的 group by 值列表。最多允许四个。	数组	必填
order_by	按特定字段对结果排序。最多允许两个。	数组	可选
projection	用户希望在响应中返回的单个子结构。	数组	可选
limit	此响应中要返回的记录数。	整数	可选
offset	获取记录的起始位置。	整数	可选

参数 count

属性	计数
类型	可选
变量类型	整数
默认值	0
可用值	[0, 1]
描述	仅返回结果总数。

示例：

{
    "count": 1
}

参数 detailed

属性	详细
类型	可选
变量类型	整数
默认值	0
可用值	[0, 1]
描述	是否返回详细信息。

示例：

{
    "detailed": 1
}

参数 timezone

用于 hour 过滤器和 group_by.

属性	时区
类型	可选
变量类型	字符串
默认值	America/New_york
可用值	设置 /collections/timezones 的时区字段
描述	注意：仅在按小时数据查询时，时区才相关；对于非小时数据，这不会产生作用。

示例：

{
    "timezone": "Europe/Dublin"
}

参数 totals

属性	总计
类型	可选
变量类型	整数
默认值	0
可用值	[0,1]
描述	指示是否在响应中添加总计。

示例：

{
    "totals": 1
}

参数 filter

属性	过滤
类型	可选
变量类型	对象
广告主可用选项	[”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”]
发布者可用选项	[”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”]
描述	按特定参数过滤。

过滤： country_iso

属性	country_iso
类型	可选
变量类型	字符串
默认值	-
可用值	参见 /collections/countries 端点的 iso3 属性
描述	ISO 3 代码列表

示例：

{
    "filter": {
        "country_iso": ["ESP", "IRL"]
    }
}

过滤 date_from, date_to

该 date_from 和 date_to 这些参数控制你想要获取统计信息的时间窗口。

• date_from：统计的起始日期，（默认月初），
• date_to：统计的结束日期，（默认今天）

属性	date_from, date_to
类型	可选
变量类型	字符串
默认值	日期默认为当前月份。
可用值	YYYY-mm-dd
描述	统计的起止日期范围。格式 YYYY-mm-dd

示例：

{
    "filter": {
        "date_from": "2019-02-25",
        "date_to": "2019-02-28"
    }
}

仅在按小时数据查询时，时区才相关；对于非小时数据，这不会产生作用。

过滤：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

属性	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
类型	可选
变量类型	数组
项目类型	整数
默认值	-
可用值	相关属性或集合
描述	实体 ID 列表

示例：

{
    "filter": {
        "campaign_id": [123, 456],
        "browser_id": [789]
    }
}

过滤： exclude_deleted

属性	exclude_deleted
类型	可选
变量类型	整数
默认值	0
可用值	[0, 1]
描述	是否排除已删除的活动。

示例：

{
    "filter": {
        "exclude_deleted": 1
    }
}

过滤： adblock

属性	adblock
类型	可选
变量类型	字符串
默认值	"all"
可用值	"adblock", "all", "standard"
描述	是否包含 adblock 区域。

示例：

{
    "filter": {
        "adblock": "standard"
    }
}

过滤： site_hostname

属性	site_hostname
类型	可选
变量类型	字符串
默认值	-
可用值	主机名的有效字符为 a 到 z 的字母、0 到 9 的数字、连字符和点。
描述	按站点主机名过滤。

示例：

{
    "filter": {
        "site_hostname": ["www.example.com", "www.example-site.org"]
    }
}

过滤： size

属性	size
类型	可选
变量类型	字符串
默认值	-
可用值	size 的有效字符为 0 到 9 的数字和 x 字符。示例 300x100
描述	按 size 过滤

示例：

{
    "filter": {
        "size": ["300x100"]
    }
}

参数 group_by

属性	group_by
类型	必填
变量类型	数组
项目类型	字符串
默认值	-
广告主可用值	[”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”]
发布者可用值	[“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”]
描述	要在响应中包含额外数据的子请求列表。

示例：

{
  "group_by": [
    "browser",
    "date"
  ]
}

参数 order_by

属性	order_by
类型	可选
变量类型	数组
项目类型	字符串
默认值	-
可用的指标字段值	[“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”]
依赖于 `group_by’ 的广告主可用字段值	[”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”]
依赖于 `group_by’ 的发布者可用字段值	[“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”]
可用的排序值	[“asc”, “desc”]
描述	可用排序选项列表

提示:

• 指标字段始终可用，可作为 order by 字段。
• 若要按特定值排序（例如按 “browser_id”），需要将其包含在 “group_by” 参数中。

“g1”、“ecpa1” 值仅在用户启用转化跟踪（Goals）时可用。所有目标均与序号对应（g1、g2、…gx）。eCPA 值相应为 ecpa1、ecpa2、…ecpax。

示例：

{
  "order_by": [
    {
      "field": "impressions",
      "order": "desc"
    }
  ]
}

要按时间顺序整理活动结果，需将 “date” 同时包含在 “group_by” 和 “order_by” 中：

{
  "group_by": [
    "campaign_id",
    "date"
  ],
  "order_by": [
    {
      "field": "date",
      "order": "asc"
    }
  ]
}

参数 projection

projection 参数反映最终载荷中将返回的内容。如果未指定，将返回所有子结构。

属性	projection
类型	可选
变量类型	对象
项目类型	数组
默认值	所有选项，见下文
广告主可用字段值	[“base”, “rtb”, “video”, “goals*”]
发布者可用字段值	[“base”, “rtb”, “video”, “wpn”]

*某些 "goal" 字段，如 "profit" 和 "roi"，是根据活动成本计算的，因此如果你想获得正确的 "goals" 指标，也必须使用 "base" 字段。

示例：

作为广告主，如需获取所有可能的指标，请使用：

{
    "projection": {
      "base": ["*"],
      "video": ["*"],
      "goals": ["*"],
      "rtb": ["*"]
    }
}

作为发布者，如需获取所有可能的指标，请使用：

{
    "projection": {
      "base": ["*"],
      "video": ["*"],
      "wpn": ["*"],
      "rtb": ["*"]
    }
}

你也可以在每个 projection 字段中指定指标：

{
    "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"],
      //仅适用于发布者
      "wpn": ["subscriptions","unsubscriptions","sent"]
    }
}

唯一不允许指定指标投影的字段是 "goals"

参数 limit

此响应中要返回的记录数。

属性	limit
类型	可选
变量类型	整数
默认值	50

示例：

{
    "limit": 25
}

参数 offset

获取记录的起始位置。

属性	offset
类型	可选
变量类型	整数
默认值	0

示例

{
    "offset": 150
}

示例 1

带过滤的广告主活动统计。

请求：

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

响应：

{
  "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": "弹窗后置广告",
          "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": "弹窗后置广告",
          "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
    }
  }
}

示例 2

按日期统计当前月的广告主统计，按 impressions 排序。

请求：

{
  "group_by": ["date"],
  "order_by": [
    {
      "field": "impressions",
      "order": "desc"
    }
  ]
  "projection": {
      "base": ["*"],
      "video": ["*"],
      "rtb": ["*"]
    }
}

响应：

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

示例 3

按日期和 region_id 分组、按展示次数排序的发布者统计。

请求：

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

响应：

{
  "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": "美利坚合众国",
          "country_short_name": "美国",
          "id": 5332921,
          "name": "加利福尼亚"
        }
      },
      "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": "美利坚合众国",
          "country_short_name": "美国",
          "id": 5332921,
          "name": "加利福尼亚"
        }
      },
      "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
      }
    }
  ]
}

示例 4

按 site_id 分组并带投影的发布者统计。

请求：

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

响应

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