概述
Query API是一个HTTP API，可用于以编程方式查询预聚合的分析。它可用于获取分支仪表板中显示的相同数据，而无需访问仪表板本身。
自我归因网络点击/展示数据不可用
查询API不返回与SAN相关的点击/展示数据；即Google Ads，Snap，Twitter，Facebook Ads和Apple Search Ads。
单个查询由三种类型的参数构成：
- 验证参数，用于控制对数据的访问
- 数据选择键，用于定义哪些事件可以在结果中计数（例如，过滤器）
- 结果格式说明符，用于定义HTTP响应中包括哪些结果以及如何返回结果（例如，排序）
入门指南
对于对此API的新手，我们强烈建议您查看我们的查询食谱书。它具有Dashboard可视化效果的屏幕截图，以及需要进行哪些查询才能提取相同的数据。这是快速启动并使用此API的方法。
端点定义
POST /v1/query/analytics
Content-Type: application/json
Host: api2.branch.io
参量
认证方式
branch_key
description：正在提取应用程序分析信息的Branch键。
required ：是
location ：身体
format ：字符串
位置：身体
格式：字符串
branch_secret
description：应用程序的分支机密，用于身份验证。
required ：是
location ：身体
format ：字符串
数据选择
start_date
description：表示要返回其数据的最早日期的时间戳。
required ：是
location ：身体
restrictions ：不能早于2017-10-14
format ：符合ISO-8601的日期时间字符串。例如：“ 2020-01-20”
end_date
description：要为其返回数据的最后一个时间戳（不包括）。查询结果中不计入结束日期之后触发的事件。
_required ：是
location ：主体
restrictions ：从开始日期开始不能超过7天
_format ：符合ISO-8601的日期时间字符串。例如：“ 2020-01-20”
data_source
description：要查询的事件类型，带有源名称（例如'eo '+'open'拉分支应用程序打开）
_required ：是
location ：身体
valid values ：
分支数据源
[
"eo_impression",
"eo_click",
"eo_web_to_app_auto_redirect",
"eo_branch_cta_view",
"eo_sms_sent",
"eo_open",
"eo_install",
"eo_reinstall",
"eo_web_session_start",
"eo_pageview",
"eo_commerce_event",
"eo_custom_event",
"eo_content_event",
"eo_user_lifecycle_event",
"cost"
]
aggregation
description：如何将事件计入最终结果数。使用unique_count时，仅当尚未看到该用户的事件时才对每个事件进行计数。例如，如果每个触发器有10个用户，则打开3个触发器：
total_count = 30
unique_count = 10
当使用数据源"eocommerce_event"查询时，聚合也可以指定为"revenue" ，在这种情况下，返回的计数是匹配事件的收益之和，而不是事件本身的数目。
_required ：是
location ：身体
format ：字符串
possible values ：
[
"unique_count",
"total_count",
"revenue",
"cost"
]
dimensions
description：事件字段列表，用作查询的拆分。返回的结果计数将与“尺寸”中提供的每个键具有匹配值的其他事件分组。
required ：是
location ：身体
format ：数组
possible element values ：
基本信息：
[
"name",
"origin",
"timestamp",
"deep_linked",
"from_desktop",
]
用户信息：
[
"user_data_os",
"user_data_language",
"user_data_platform",
"user_data_environment",
"user_data_geo_dma_code",
"user_data_geo_country_code",
]
最后归因于的触摸：
[
"last_attributed_touch_type",
"last_attributed_touch_data_tilde_tags",
"last_attributed_touch_data_tilde_secondary_publisher",
"last_attributed_touch_data_plus_current_feature",
"last_attributed_touch_data_plus_via_features",
"last_attributed_touch_data_tilde_campaign",
"last_attributed_touch_data_tilde_advertising_partner_name",
"last_attributed_touch_data_tilde_feature",
"last_attributed_touch_data_tilde_creative_name",
"last_attributed_touch_data_plus_web_format",
"last_attributed_touch_data_tilde_creative_id",
"last_attributed_touch_data_tilde_ad_name",
"last_attributed_touch_data_tilde_ad_id",
"last_attributed_touch_data_tilde_campaign_id",
"last_attributed_touch_data_tilde_stage",
"last_attributed_touch_data_tilde_channel",
"last_attributed_touch_data_tilde_ad_set_name",
"last_attributed_touch_data_tilde_ad_set_id",
"last_attributed_touch_data_tilde_keyword",
"last_attributed_touch_data_tilde_journey_id",
"last_attributed_touch_data_tilde_view_name",
"last_attributed_touch_data_tilde_view_id"
]
上次CTA查看信息：
[
"last_cta_view_data_tilde_ad_name",
"last_cta_view_data_tilde_secondary_publisher",
"last_cta_view_data_tilde_campaign",
"last_cta_view_data_tilde_advertising_partner_name",
"last_cta_view_data_tilde_feature",
"last_cta_view_data_tilde_ad_set_name",
"last_cta_view_data_tilde_ad_set_id",
"last_cta_view_data_tilde_campaign_id",
"last_cta_view_data_tilde_creative_name",
"last_cta_view_data_tilde_creative_id",
"last_cta_view_data_plus_via_features",
"last_cta_view_data_dollar_3p",
"last_cta_view_data_tilde_tags",
"last_cta_view_data_plus_web_format",
"last_cta_view_data_tilde_channel",
"last_cta_view_data_tilde_ad_id",
"last_cta_view_data_tilde_stage"
]
其他：
[
"days_from_last_attributed_touch_to_event",
"days_from_last_cta_view_to_event",
"event_data_product_categories",
"first_event_for_user",
]
filters
description: An object where each key is a valid "dimension", and each value is an array of string values. If a key is prefixed with a '!', then any event with a dimension value contained in the value of that key is excluded. Otherwise, only events with dimension values matching the filter will be counted.
required: false
location: body
format: Object<String, Array>，例如，查询的过滤器指定为：
{
"filters": {
"last_attributed_touch_data_plus_current_feature": [
"MOBILE_DEEPVIEWS",
"DESKTOP_DEEPVIEWS"
],
"!user_data_os": [ "iOS" ]
}
}
将只计算其中的事件
-
最后的attributed_touch_data_plus_current_feature等于“ MOBILE_DEEPVIEWS”或“ DESKTOP_DEEPVIEWS”
_and -
用户data_os不等于“ iOS”
_possible keys ：有关有效键值，请参见“尺寸”定义。任何键也可以与“！”一起使用。字首
结果格式
granularity
description：将多个事件汇总为单个结果计数的时间范围。例如，值为“天”时，每天的计数将独立返回，其中“全部”将在整个时间范围内返回单个计数。
required ：错误
location ：身体
default value ：“全部”
format ：字符串
possible values ：
[
"all",
"day"
]
ordered_by
description：要对结果进行排序的键。仅支持1个排序键
required ：错误
location ：身体
default value ：查询“ aggregation”属性的值，或者“ total count”（如果未定义）
_format ：字符串
possible values ：查询中“查询”的任何元素或查询中“聚合”的值
ordered
description：订购结果的方向
required ：错误
location ：身体
default value ：“下降”
format ：字符串
possible values ：
[
"ascending",
"descending"
]
关于sorts和ordered_by参数的注释：
无法为查询提供明确的排序方法，因此将根据"ordered_by"的值自动选择排序类型。相等值比较的行为未定义，因此，对于相同值，排序不视为顺序稳定。
ordered_by值的排序选择：
- unique_count，total_count，收益->数字排序
- 时间戳->按时间顺序
- 其他所有内容->按字典顺序排序
zero_fill
description：是否返回结果计数为0的结果对象。如果设置为false，则将从响应中忽略count = 0的结果。
required ：错误
location ：身体
default value ：错误
format ：布尔值
limit
description：要在响应中返回的最大结果数。如果将粒度设置为“天”，则“分支机构”会将结果提高到每天的限制。因此，如果将limit设置为1000，并且查询了5天的数据（粒度=天），那么此API将最多返回5000个结果。
required ：错误
location ：URL查询
default value ：100
max value ：1000
format ：整数
after
description：分页参数，指示响应中要返回的第一个结果的索引。例如，返回100个结果，将“之后”设置为50将返回元素51-100
required ：错误
location ：URL
default value ：0
format ：整数
query_id
description：作为“分页”对象的下一个 url和previous_url的查询参数返回。锁定要为查询计数的最后一个事件，因此不会将查询之间发生的新事件添加到结果中（防止计数随时间变化）
_required ：false
location ：URL
default value ：null
format ：字符串
注意：查询ID应该视为短暂的，并且仅应在检索现有分页URL已将query_id设置为查询参数的查询的页面时使用。您不应该尝试在请求之间更改ID或将查询ID包含在其他查询请求中。
用法示例
每个操作系统每天安装
每天提取安装的基本查询，按用户所安装设备的操作系统划分，最多5个结果：
curl -X POST -H "Content-Type: application/json" -d '{
"branch_key":"<YOUR_BRANCH_KEY>",
"branch_secret":"<YOUR_BRANCH_SECRET>",
"start_date": "2017-12-12",
"end_date": "2017-12-18",
"data_source": "eo_install",
"dimensions": [
"user_data_os"
],
"granularity": "day",
"aggregation": "total_count"
}' "http://api2.branch.io/v1/query/analytics?limit=5"
结果示例：
{
"results": [
{
"result": {
"user_data_os": "ANDROID",
"total_count": 144
},
"timestamp": "2017-12-18T00:00:00.000Z"
},
{
"result": {
"user_data_os": "IOS",
"total_count": 142
},
"timestamp": "2017-12-18T00:00:00.000Z"
},
{
"result": {
"user_data_os": "IOS",
"total_count": 191
},
"timestamp": "2017-12-17T00:00:00.000Z"
},
{
"result": {
"user_data_os": "ANDROID",
"total_count": 194
},
"timestamp": "2017-12-17T00:00:00.000Z"
},
{
"result": {
"user_data_os": "ANDROID",
"total_count": 246
},
"timestamp": "2017-12-16T00:00:00.000Z"
}
],
"paging": {
"next_url": "/v1/query/analytics?query_id=CqdBOb&limit=5&after=5",
"total_count": 14
}
}
每个渠道/广告系列/功能的唯一点击计数
用于获取唯一点击次数的更复杂的查询，按上次触摸渠道，广告系列，功能和+ via_current_features值划分。
指定了一个过滤器，以过滤掉last_attributed_touch_data_plus_current_feature为MOBILE_DEEPVIEWS或DESKTOP_DEEPVIEWS的所有点击。
最多应返回5个结果（以unique_count降序排列），其中返回的天数包含0次点击（未过滤掉）：
curl -X POST -H "Content-Type: application/json" -d '{
"branch_key":"<YOUR_BRANCH_KEY>",
"branch_secret":"<YOUR_BRANCH_SECRET>",
"start_date": "2017-12-12",
"end_date": "2017-12-18",
"data_source": "eo_click",
"dimensions": [
"last_attributed_touch_data_tilde_feature",
"last_attributed_touch_data_tilde_channel",
"last_attributed_touch_data_tilde_campaign",
"last_attributed_touch_data_plus_current_feature"
],
"filters": {
"!last_attributed_touch_data_plus_current_feature": [
"MOBILE_DEEPVIEWS",
"DESKTOP_DEEPVIEWS"
]
},
"ordered": "descending",
"ordered_by": "unique_count",
"aggregation": "unique_count",
"zero_fill": true
}' "http://api2.branch.io/v1/query/analytics?limit=5"
结果示例：
{
"results": [
{
"timestamp": "2017-12-12T00:00:00.000Z",
"result": {
"last_attributed_touch_data_tilde_channel": "ads",
"last_attributed_touch_data_tilde_campaign": "Xmas",
"last_attributed_touch_data_tilde_feature": "paid advertising",
"last_attributed_touch_data_plus_current_feature": "ADS",
"unique_count": 750
}
},
{
"timestamp": "2017-12-12T00:00:00.000Z",
"result": {
"last_attributed_touch_data_tilde_channel": "taptica#1",
"last_attributed_touch_data_tilde_campaign": "taptica#1",
"last_attributed_touch_data_tilde_feature": "paid advertising",
"last_attributed_touch_data_plus_current_feature": "ADS",
"unique_count": 723
}
},
{
"timestamp": "2017-12-12T00:00:00.000Z",
"result": {
"last_attributed_touch_data_tilde_channel": "Journeys",
"last_attributed_touch_data_tilde_campaign": "Default Banner",
"last_attributed_touch_data_tilde_feature": "journeys",
"last_attributed_touch_data_plus_current_feature": "MOBILE_JOURNEYS",
"unique_count": 553
}
},
{
"timestamp": "2017-12-12T00:00:00.000Z",
"result": {
"last_attributed_touch_data_tilde_channel": "Apple App Store",
"last_attributed_touch_data_tilde_campaign": null,
"last_attributed_touch_data_tilde_feature": "paid advertising",
"last_attributed_touch_data_plus_current_feature": "ADS",
"unique_count": 432
}
},
{
"timestamp": "2017-12-12T00:00:00.000Z",
"result": {
"last_attributed_touch_data_tilde_channel": null,
"last_attributed_touch_data_tilde_campaign": null,
"last_attributed_touch_data_tilde_feature": "marketing",
"last_attributed_touch_data_plus_current_feature": "QUICK_LINKS",
"unique_count": 201
}
}
],
"paging": {
"next_url": "/v1/query/analytics?query_id=EDdBOb&limit=5&after=5",
"total_count": 143
}
}
速率限制
- 每秒5个请求
- 每分钟20个请求
- 每小时150个请求
25 天前更新