概述
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 天前更新