开发者中心

查询 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：要为其返回数据的最后一个时间戳（不包括）。查询结果中不计入结束日期之后触发的事件。
_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个用户分别触发了三次事件：

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

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

[
  "all",
  "day"
]

ordered_by
description：要对结果进行排序的键。仅支持1个排序键
required ：false
location ：主体
default value ：查询“ aggregation”属性的值，如果未定义，则为“ total count”
_format ：字符串
possible values ：查询“ dimensions”或查询中“聚合”的值

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：作为“分页”对象下一个 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个请求

6个月前更新

查询 API（Query API）

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

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