查询 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规范进行修改。