一、分布分析查询
接口URL
/api/open_api/v1/analysis/distribution?token=xxx
请求方式
POST
Content-Type
application/json
请求Query参数
|
参数名
|
参数类型
|
是否必填
|
参数描述
|
|
token
|
String
|
是
|
查询token
|
请求Body参数
分布分析的请求参数由用户参与的事件参数（events）、分组项参数（eventsGroup）、时间粒度参数（eventsView）、时区参数（timeZoneOffset）和分析主体参数（entity），特殊地，在分布分析中如果使用"同时展示"功能，则会额外传入同时展示参数（alsoShow），如图所示
用户参与的事件参数
|
参数名
|
参数类型
|
是否必填
|
说明
|
|
events
|
Object
|
是
|
用户参与的事件参数 |
|
intervalType
|
String
|
是
|
分布区间支持以下类型 默认类型（default）会根据查询数据的最大值，最小值自动计算出一个合理的区间划分 离散类型（discretely）会根据查询的数据最大值，最小值加1递增划分区间 自定义类型（customized）会根据quotaIntervalArr参数传递的区间划分查询数据 |
|
quotaIntervalArr
|
List
|
否
|
intervalType参数为customized是需要传递划分查询数据的区间 |
|
其他字段
|
其他字段与事件分析模型API中关于分析指标参数（eventsSelect）一致，具体说明可翻阅事件分析模型API参考 | ||
同时展示参数
当您在分布分析中想要使用“同时展示”的功能时，还需要额外传入同时展示参数，从页面操作来看，同时展示是一个分析指标，故它的参数除了以下表格列出的intervalType， quotaIntervalArr两个参数以外，其他参数与事件分析模型API的分析指标是一致的。
如上图所示的同时展示计算方式，可用如下的示例表示
{
"alsoShow": {
"eventType": "default",
"relation": "and",
"filters": [],
"intervalType": "default",
"quotaIntervalArr": [
0
],
"analysis": [
"A100"
],
"displayName": "app安装（服务端）",
"eventName": "$app_install",
"eventDisplayName": "app安装（服务端）的总次数",
"presetEventDisplayName": "app安装（服务端）的总次数",
"eventID": 9213
}
}参数说明
|
参数名
|
参数类型
|
是否必填
|
说明
|
|
alsoShow
|
Object
|
否
|
用户参与的事件参数 |
|
intervalType
|
String
|
是
|
分布区间支持以下类型 默认类型（default）会根据查询的数据最大值，最小值自动计算出一个合理的区间划分 离散类型（discretely）会根据查询的数据最大值，最小值加1递增划分区间 自定义类型（customized）会根据quotaIntervalArr参数传递的区间划分查询数据 |
|
quotaIntervalArr
|
List
|
否
|
intervalType参数为customized是需要传递划分查询数据的区间 |
|
其他字段
|
其他字段与事件分析模型API中关于分析指标参数（eventsSelect）一致，具体说明可翻阅事件分析模型API参考 | ||
全局筛选、分组项与计算时间、分析主体参数
|
参数名
|
参数类型
|
是否必填
|
说明
|
|
eventsFilter
|
Object
|
否
|
通用参数，见"如何表示一个筛选项" |
|
eventsGroup
|
Object
|
否
|
通用参数，其中globalization为计算所使用的分组项构成的列表，每一项为一个分组，每一个分组项见"如何表示一个分组项" |
| globalization |
List[Object]
|
否
|
|
|
eventsView
|
Object
|
是
|
|
|
timeZoneOffset
|
Number
|
否
|
计算时区，如8，-8 若未填，表示0时区 |
|
entity
|
Object
|
是
|
分析主体，分布分析支持计算不同的分析主体，例如用户、国家等，一般我们以$uid作为分析主体计算，分析主体的表示见"如何表示分析主体" |
请求响应结果
示例
我们以下图所示的分析场景，进行API查询，那么最终返回结果如下示例
返回结果示例：
{
"union_groups_name": [],
"union_groups_col_name": [],
"event_name_desc": "#app_install的次数",
"axis_x": [
"2024-12-21",
"2024-12-22",
"2024-12-23",
"2024-12-24",
"2024-12-25",
"2024-12-26",
"2024-12-27"
],
"axis_y": {
"2024-12-21": [
{
"group_cols": [
"all"
],
"is_total": 1,
"total_user_num": 7736,
"values": [
7648,
79,
4,
3,
1,
1,
0
]
}
],
"2024-12-22": [
{
"group_cols": [
"all"
],
"is_total": 1,
"total_user_num": 9636,
"values": [
9511,
113,
5,
4,
2,
1,
0
]
}
],
"2024-12-23": [
{
"group_cols": [
"all"
],
"is_total": 1,
"total_user_num": 8351,
"values": [
8251,
86,
12,
1,
1,
0,
0
]
}
],
"2024-12-24": [
{
"group_cols": [
"all"
],
"is_total": 1,
"total_user_num": 4325,
"values": [
4233,
72,
15,
2,
1,
0,
2
]
}
],
"2024-12-25": [
{
"group_cols": [
"all"
],
"is_total": 1,
"total_user_num": 5295,
"values": [
5200,
78,
11,
3,
1,
1,
1
]
}
],
"2024-12-26": [
{
"group_cols": [
"all"
],
"is_total": 1,
"total_user_num": 4037,
"values": [
3942,
81,
7,
5,
1,
1,
0
]
}
],
"2024-12-27": [
{
"group_cols": [
"all"
],
"is_total": 1,
"total_user_num": 907,
"values": [
895,
10,
2,
0,
0,
0,
0
]
}
]
},
"axis_z": [
",3",
"3,6",
"6,9",
"9,12",
"12,15",
"15,18",
"18,"
],
"quota_unit": "times",
"particle": "day",
"entity": {
"id": 154,
"name": "用户ID1",
"entity_type": "PRIMARY",
"column_desc": "DataTower.ai 后台唯一 id，由服务端生成，区分唯一事件流",
"column_name": "$uid",
"column_type": "varchar",
"data_type": "string",
"display_name": "DT用户ID",
"table_type": "user",
"type": 1
},
"also_show_format": null,
"date_list": [
"2024-12-21",
"2024-12-27"
],
"is_cached": false
}响应结果说明
| 字段名 | 字段类型 | 字段说明 |
|
axis_x
|
List[String] |
由计算时间构成的字符串列表，时间表示的粒度取决于计算时传入的timeParticleSize 如果按天计算，列表长度则计算范围内的天数 |
|
axis_y
|
List[Object] |
各个分布区间内用户参与事件以及参与同时展示事件人数构成列表 |
|
also_show_values
|
List[Object] |
各个分布区间内用户同时参与同时展示事件人数构成的列表 |
|
group_cols
|
List[String] |
选择分组时的数据 |
|
is_total
|
Number
|
标识是否返回了所有数据，默认返回1000个分组数据 |
|
total_also_show_value
|
Number
|
参与同时展示事件总人数 |
|
total_user_num
|
Number
|
用户参与事件总人数 |
|
values
|
List[Number]
|
各个分布区间内用户参与事件以及参与同时展示事件具体人数 |
|
axis_z
|
List[String] |
不同分布区间构成的列表 |
|
date_list
|
List[String]
|
选择的时间范围 |
|
quota_unit
|
String
|
指明当前分布分析计算的属性分析角度 times： 次数
day： 天数
hours： 小时数
“”： 具体属性的分析角度，比如账号ID的去重数
|
|
event_name_desc
|
String |
用户参与的事件的显示名
|
|
union_groups_col_name
|
List[String] |
本次计算使用的分组项属性构成的数组，长度等于计算时用的分组项个数 |
|
union_groups_name
|
List[List[String]] |
分组值构成的二维列表，即使用请求参数中的分组，最终可以将结果分成哪些组，外层长度 = 分组结果的个数，内层列表的长度 = 计算时所用的分组项个数，在使用多个分组时，分组值的顺序与union_groups_name的顺序是一致的 |
二、分布分析用户列表查询
在分布分析中，我们可以看到不同分布区间人数
接口URL
/api/open_api/v1/analysis/distribution_user_list?token=xxx
请求方式
POST
Content-Type
application/json
请求Query参数
|
参数名
|
参数类型
|
是否必填
|
参数描述
|
|
token
|
String
|
是
|
查询token
|
请求Body参数
请求的body参数在对应完整使用的分布分析的参数外，额外增加一项details和properties字段，来指明是需要查看查看什么时间什么分组的在什么分布区间人数
|
参数名
|
参数类型
|
是否必填
|
参数描述
|
| details | Object | 是 | 查询详情 |
| eventModel | String | 是 | 分布分析固定为"distribution" |
|
interval
|
String | 否 |
查询的分布区间， 默认为参数intervalType与quotaIntervalArr确定的第一个分布区间
|
| sliceDate | String | 否 |
查询具体时间点，如"2024-01-01"，注意时间一定要在eventsView表示的时间范围内 若不传，则表示查询的是总计 |
| sliceGroup | List[Object] | 否 |
当计算用了分组时，需要指明最终查询的是哪个分组的列表详情，长度 = 分组项的个数 |
| groupName | String | 是 |
分组属性名 |
| groupValue | String | 是 |
具体分组值 |
| tableType | String | 是 |
分组属性类型 |
| sliceType | String | 是 | 固定传"user" |
| properties | List[Obejct] | 否 |
要查询的用户属性列表，即最终计算结果需要返回的属性 若未传，默认会查询"$uid"、"#dt_id"和"#acid" |
| column_name | String | 否 |
属性名
|
示例
下述示例，即表示在分布分析完成计算后，想要查看12-18这天，分组是"中国"、"ios"的当天分布区间在0到300之间的人数
{
"firstEvent": {...},
"returnEvent": {...},
"alsoShow": {...},
"eventsFilter":{...},
"eventsGroup":{...},
"eventsView": {...},
"entity":{...},
"timeZoneOffset": 8,
"details": {
"eventModel:"distribution",
"interval": "0,300"
"sliceType": "user",
"sliceDate": "2024-12-18",
"sliceGroup": [
{
"groupName": "国家",
"groupValue": "中国",
"tableType": "event",
},
{
"groupName": "操作系统",
"groupValue": "ios",
"tableType": "event",
}
]
},
"properties": [
{"column_name": "#acid"},
{"column_name": "#app_id"},
{"column_name": "#app_version"},
{"column_name": "#bundle_id"},
{"column_name": "#carrier"},
{"column_name": "#city"},
{"column_name": "#dt_id"},
{"column_name": "$uid"},
{"column_name": "#country"}]
}请求响应结果
| 字段名 | 字段类型 | 字段说明 |
|
columnMeta
|
Object |
所查询的properties的属性映射，键值对的个数 = 请求参数中properties的长度， 键名为属性名，值为属性显示名 |
|
data_list
|
List[Object] | 用户列表详情，长度 = 计算的结果数，对象中为属性名：属性值的键值对 |
|
total
|
Number | 总数，最多返回1000条 |
示例
{
"columnMeta": {
"#acid": "账号 ID",
"#app_id": "应用唯一标识",
"#app_version": "应用版本",
"#bundle_id": "应用包名",
"#carrier": "运营商",
"#city": "城市",
"#country": "国家",
"#dt_id": "访客ID",
"$uid": "DT 用户 ID"
},
"total": 1,
"data_list": [
{
"#acid": "0@5IZJI4YUWZcard_games",
"#app_id": "dt_xxxx",
"#app_version": "app2.0.1",
"#bundle_id": null,
"#carrier": "移动",
"#city": "纽约",
"#country": "中国",
"#dt_id": "dddddd",
"$uid": "123232455"
},
],
}