开发者中心

查询 API（Query API）

概述

Query API是HTTP API，可用于以编程方式查询预先聚合的分析。它可用于获取Branch仪表板中显示的相同数据，而无需访问仪表板本身。

自归因网络点击/展示数据不可用

查询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 ：true
location ：主体
restrictions ：不能早于2017-10-14
format ：符合ISO-8601的日期时间字符串。例如： " 2020-01-20 "

end_date
description：要为其返回数据的最后一个时间戳（不包括）。在end_date之后触发的事件不会计入查询结果中。
required ：true
location ：正文
restrictions ：在start_date之后不能超过7天
format ：符合ISO-8601的日期时间字符串。例如： " 2020-01-20 "

data_source
description：类型事件查询的，与源前缀（例如' eo_ ' + '开放'拉科应用打开）
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个用户分别触发了三次事件：

total_count = 30
unique_count = 10

当使用"eo_commerce_event"的数据源进行查询时，聚合也可以指定为"revenue" ，在这种情况下，返回的计数是匹配事件的收益之和，而不是事件本身的数目。
required ：正确
location ：主体
format ：字符串
possible values ：

[
  "unique_count",
  "total_count",
  "revenue",
  "cost"
]

dimensions
description：事件字段列表，用作查询的拆分。返回结果计数，并与其他事件分组，这些事件具有在"维"提供的每个键的匹配值。
required ：真
location ：体
format ：阵列<string>
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"
]

上次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：一个对象，其中每个键都是有效的"维" ，每个值都是字符串值的数组。如果键以'为前缀！ ' ，则排除任何具有包含在该键的值中的维度值的事件。否则，将仅对维度值与过滤器匹配的事件进行计数。
required ：错误
location ：主体
format ：对象<字符串，数组 

{
  "filters": {
    "last_attributed_touch_data_plus_current_feature": [
      "MOBILE_DEEPVIEWS",
      "DESKTOP_DEEPVIEWS"
    ],
    "!user_data_os": [ "iOS" ]
  }
}

将只计算其中的事件

  • last_attributed_touch_data_plus_current_feature等于" MOBILE_DEEPVIEWS "或" DESKTOP_DEEPVIEWS "
    and

  • user_data_os是而不是等于" iOS "
    possible keys ：有关有效键值，请参见"维"定义。任何键也可以与"一起使用！ "前缀

设定结果格式

granularity
description：将多个事件汇总为单个结果计数的时间范围。例如，值为" day " ，每天的计数将独立返回，其中"中的" "将在整个时间范围内返回一个计数。
required ：假
location ：主体
default value ： "所有"
format ：串
possible values ：

[
  "all",
  "day"
]

ordered_by
description：要对结果进行排序的键。仅支持1个排序键
required ：否
location ：主体
default value ：查询的值"聚合"属性，或者" 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 ：false
location ：URL
default value ：0
format ：整数

query_id
description：作为"分页"对象next_url和previous_url上的查询参数返回。锁定要为查询计数的最后一个事件，因此不会将查询之间发生的新事件添加到结果中（防止计数随时间变化）
required ：错误
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个请求

3个月前更新

查询 API（Query API）

建议的编辑仅限于API参考页

您只能建议对Markdown正文内容进行修改，而不能建议对API规范进行修改。