聚合报表 API

此API指南为使用Chartboost聚合的应用发布商提供了关于如何发送和接收请求以收集报告数据，如收入，示和其他指标的信息。

注意: 我们的报告API限制每10分钟最多请求40次。

身份验证 🔗

访问 Chartboost 聚合API浏览器以使用您的用户ID和用户签名进行身份验证。

要在您的设备上进行本地身份验证，而不是通过Chartboost聚合后台进行身份验证，以下是一个身份验证请求的示例：

                curl -X "POST" "https://helium-api.chartboost.com/v1/publisher/metrics" \
  -H 'Cookie: user_id=<YOUR_USER_ID>;user_signature=<YOUR_USER_SIGNATURE>;'

查找您的user ID 和 user signature（用户ID和用户签名） 🔗

登录到您的Chartboost平台。
点击 Mediation（聚合）。您将被重定向到 Helium 后台（https://helium.chartboost.com/）。
从左侧导航栏中，转到 Resources（资源）> API Explorer（API浏览器）。
您的 user ID（用户ID）和 user signature和用户签名）将显示在 Authentication（身份验证）下面。

注意: Chartboost正在努力重新设计，迁移和改进后台和平台服务。一些工具，功能和信息可能在奇怪的地方，请谅解。

请求正文 🔗

API路径 🔗

POST https://helium-api.chartboost.com/v1/publisher/metrics

参数	定义	默认值	预期值
dimensions	用于细分数据的字段列表	[“date”， “app”， “helium_placement_name”， “placement_type”， “demand_source”，”country”]	不能发送空列表 [] - 至少需要一个维度，否则将使用默认维度列表
metrics	数据汇总指标列表	[“requests”， “impressions”， “estimated_earnings”， “ecpm”， “fill_rate”]	不能发送空列表 [] - 至少需要一个指标，否则将使用默认指标列表
filters	按属性筛选数据的属性列表	[‘apps’， ‘placements’， ‘country’， ‘placement_type’， ‘demand_source’， ‘network_type’]	不能发送空列表过滤器 - 最小过滤器列表长度为1
date_min	检索数据的最早日期	按 YYYY-MM-DD 格式的今天的日期	日期范围限制为30天（最小 - 最大）
date_max	检索数据的最新日期	按 YYYY-MM-DD 格式的今天的日期	日期范围限制为30天（最小 - 最大）
timezone	日期值的时区	‘America/Los_Angeles’ (PST)	仅支持UTC和PST

支持的维度 🔗

使用聚合报告API时，您无需在请求正文中输入任何维度 - 此时我们使用默认值。然而，如果您选择输入维度值，列表不能是空的，您必须提供以下至少一个被接受的值，以确保查询成功。

维度	定义	数据类型
date	请求日期 (YYYY-MM-DD)	string
app	应用的App ID	string
helium_placement_name	聚合广告位的名称	string
placement_type	`interstitial` 或者 `rewarded`	string
demand_source	竞价或者瀑布流广告合作伙伴的名称	string**
country	ISO 3166-1 alpha-3 国家码***	string
helium_line_item_name	瀑布流层级名称 *	string
partner_placement_name	瀑布流需求合作伙伴广告位名称 *	string

* 表示在 Filters 部分的 network_type 值为 Mediation时，应填写此字段。

** 表示此字段的选项是以下合作伙伴：AdMob，Applovin，Chartboost，Facebook，ironSource，Unity，Vungle

*** 表示仅支持50个国家/地区代码，但如果所需国家/地区不在以下列表中，则会归集到'OTHER'中 ('ARE'， 'ARG'， 'AUT'， 'AUS'， 'BEL'， 'BRA'， 'CAN'， 'CHE'， 'CHL'， 'CHN'， 'COL'， 'CZE'， 'DEU'， 'DNK'， 'EGY'， 'ESP'， 'FRA'， 'GBR'， 'HKG'， 'IDN'， 'IRL'， 'ISR'， 'IND'， 'IRN'， 'ITA'， 'JPN'， 'KOR'， 'KAZ'， 'MEX'， 'MYS'， 'NLD'， 'NOR'， 'NZL'， 'PER'， 'PHL'， 'POL'， 'PRT'， 'ROU'， 'RUS'， 'SAU'， 'SWE'， 'SGP'， 'THA'， 'TUR'， 'TWN'， 'UKR'， 'USA'， 'VNM'， 'ZAF')

支持的指标 🔗

使用聚合报告API时，您无需在请求正文中输入任何指标 - 此时我们使用默认值。然而，如果您选择输入指标值，列表不能是空的。必须提供以下至少一个被接受的值，以确保查询成功。

指标	定义	预期值
requests	广告请求数
responses	广告返回数	仅当广告网络类型为“Mediation” 时*
valid_bids	有效竞价数	仅当广告网络类型为“Bidding” 时*
winning_bids	竞价成功数	仅当广告网络类型为“Bidding” 时
impressions	展示数
estimated_earnings	以美元计价的预估收入	四舍五入至小数点后两位
ecpm	以美元计价计算出来的eCPM	四舍五入至小数点后两位
bid_rate	有效竞价除以竞价请求数的比值	仅当广告网络类型为“Bidding” 时
win_rate	竞价胜出除以有效竞价的比值	仅当广告网络类型为“Bidding” 时
fill_rate	展示除以广告请求的比值
impression_show_rate	展示除以竞价胜出的比值	仅当广告网络类型为“Bidding” 时

* 此处的 Bidding 和 Mediation 术语是指在 Filters 部分的 network_type 字段值设置为 Bidding 或 Mediation。

支持的过滤器 🔗

使用聚合报告API时，您无需在请求正文中输入任何过滤器。然而，如果您选择设置过滤器，列表不能是空的。必须提供以下至少一个被接受的值，以确保查询成功。

过滤器	定义	预期值
apps	用于过滤的AppID 列表
placements	用于过滤的聚合广告位列表
country	用于筛选的国家/地区列表
placement_type	按广告位类型过滤	以下数组中一个或多个值: [“interstitial”, “rewarded”, “banner”, “rewarded_interstitial”, “adaptive_banner”]
demand_source	按需求来源过滤	以下数组中一个或多个值: [“admob”, “applovin”, “chartboost”, “facebook”, “fyber”, “google_googlebidding”, “hyprmx”, “inmobi”, “ironsource”, “mintegral”, “mobilefuse”, “unity”, “vungle”]
network_type	用于过滤的广告网络类型	只有以下三种类型: “all”， “bidding”， “mediation”

* 默认值是 all，包含后面两个值的组合.

参数兼容性 🔗

某些参数组合与彼此不兼容。以下表格显示了哪些字段可以与三个 network_type 选项一起使用。

参数名	`all`	`bidding`	`mediation`
requests	✅	✅	✅
responses	❌	❌	✅
valid_bids	❌	✅	❌
winning_bids	❌	✅	❌
impressions	✅	✅	✅
estimated_earnings	✅	✅	✅
ecpm	✅	✅	✅
bid_rate	❌	✅	❌
win_rate	❌	✅	❌
winning_bids	❌	✅	❌
fill_rate	✅	✅	✅
impression_show_rate	❌	✅	❌

示例JSON请求 🔗

以下是一个非常基本的请求示例，仅包含三个输入字段 - 其余字段为默认值。

                {
  "date_min": "2020-06-23"，
  "date_max": "2020-06-25"，
  "timezone": "UTC"
}

              

示例JSON响应 🔗

以下是一次成功的查询的响应示例。

                  "data": [
    {
      "app": "53721724c26ee432aa854f55"，
      "date": "2020-06-24"，
      "ecpm": 11.27，
      "estimated_earnings": 26.16，
      "fill_rate": 0.03，
      "impressions": 2321，
      "placement_type": "interstitial"，
      "requests": 79415，
      "responses": 25192
    }，
    {
      "app": "53721724c26ee432aa854f55"，
      "date": "2020-06-24"，
      "ecpm": 9.92，
      "estimated_earnings": 4.17，
      "fill_rate": 0.01，
      "impressions": 420，
      "placement_type": "rewarded"，
      "requests": 44260，
      "responses": 13152
    }，
    {
      "app": "537220541873da7ee366aee7"，
      "date": "2020-06-24"，
      "ecpm": 10.78，
      "estimated_earnings": 8.87，
      "fill_rate": 0.05，
      "impressions": 823，
      "placement_type": "interstitial"，
      "requests": 17920，
      "responses": 6433
    }，
    {
      "app": "537220541873da7ee366aee7"，
      "date": "2020-06-24"，
      "ecpm": 7.48，
      "estimated_earnings": 1.71，
      "fill_rate": 0.02，
      "impressions": 229，
      "placement_type": "rewarded"，
      "requests": 14243，
      "responses": 4815
    }
  ]，
  "process_time": 0.008205890655517578，
  "query_time": 0.23745250701904297，
  "row_count": 4
}

              

错误 🔗

无效的请求将返回400状态代码，附带相关的响应正文。

以下是一个错误响应的示例。

                {
  "code": 400，
  "name": "Bad Request"，
  "description": "ValidationError"，
  "errors": {
    "win_rate": "'win_rate' metric is for network_type 'bidding' only"
  }
}

              

广告聚合