获取客户人群
全部接口
V1.1
loading
V1.1
loading
| 所属权限 | Audience Management |
| 请求地址 | custom_audiences/get |
| 请求方法 | get |
全局参数
全局参数是指每一个接口都需要使用到的参数。详情参考，代码案例参考。
| 参数名称 | 参数类型 |
|---|---|
| access_token | 授权令牌，完成 OAuth 2.0 授权后获得，参考授权认证章节 |
| timestamp |
当前的时间戳，单位为秒，允许客户端请求最大时间误差为 300 秒。 MarketingAPI 所使用的时间戳，若无特殊说明，均为秒级时间戳 MarketingAPI 所使用的时区为 GMT+8，例如当时间戳为 1494840119 时，表示 2017-05-15 17:21:59 |
| nonce | 随机字串标识，不超过 32 个字符，由调用方自行生成，需保证全局唯一性 |
| fields | get 接口增加 fields 字段，用于指定返回参数的字段列表，为选填字段。fields 取值范围为 get 接口返回的 list 中的字段。如不填写，则根据默认值进行返回 |
请求参数
标有*的参数为必填项
| 名称 | 类型 | 描述 |
|---|---|---|
|
account_id*
|
integer | 推广帐号 id，有操作权限的帐号 id，包括代理商和广告主帐号 id |
|
audience_id
|
integer | 人群 id，通过 [custom_audiences] 模块创建客户人群获得 |
|
page
|
integer | 当前页码，默认 1 最小值 1，最大值 2147483647 |
|
page_size
|
integer | 分页大小，默认 10 最小值 1，最大值 100 |
|
platform
|
enum | 数据应用，不填写默认为 DMP，[枚举详情] 枚举列表：{ DMP, TDC, TDP } |
请求示例
curl -G 'https://api.e.qq.com/v1.1/custom_audiences/get?access_token=<ACCESS_TOKEN>×tamp=<TIMESTAMP>&nonce=<NONCE>' \
-d 'account_id=<ACCOUNT_ID>' \
-d 'audience_id=<AUDIENCE_ID>' \
-d 'page=1' \
-d 'page_size=10'
应答字段
| 名称 | 类型 | 描述 |
|---|---|---|
|
list
|
struct[] | 返回数组列表 |
|
audience_id
|
integer | 人群 id |
|
account_id
|
integer | 人群归属的推广帐号 id |
|
name
|
string | 人群名称 |
|
external_audience_id
|
string | 广告主对人群在自己系统里的编码 |
|
description
|
string | 人群描述 |
|
cooperated
|
boolean | 深度数据合作：可将您的数据数据从 DMP 平台导出，平台将为您进行定制化的挖掘，进行深度数据合作 |
|
type
|
enum | 人群类型，[枚举详情] |
|
source
|
enum | 人群来源，[枚举详情] |
|
status
|
enum | 处理状态，[枚举详情] |
|
online_status
|
enum | 人群包在线状态，如果人群包一段时间不更新或者不使用于广告定向，人群包会被下线处理。下线后的人群无法用于广告定向，但是洞察等不受影响。该字段仅在人群包处理状态为成功可用返回和生效，[枚举详情] |
|
is_own
|
boolean | 是否是人群包 owner，一般人群包创建者为人群包 owner |
|
error_code
|
integer | 人群错误码, 1 表示系统错误； 101 表示种子人群活跃用户低于 2K ； 102 表示种子人群无共同特征； 201 表示人群上传的号码包文件格式错误； 202 表示解析人群上传的号码包文件失败； 203 表示号码包文件人群匹配失败。 |
|
user_count
|
integer | 用户覆盖数 |
|
created_time
|
string | 创建时间，格式为 yyyy-MM-dd HH:mm:ss，如 2016-11-01 10:42:56 |
|
last_modified_time
|
string | 最后更新时间，格式为 yyyy-MM-dd HH:mm:ss，如 2016-11-01 10:42:56 |
|
audience_spec
|
struct | 人群信息，和 type 相关 |
|
lookalike_spec
|
struct | Lookalike 人群信息，当 type=LOOKALIKE 时必填 |
|
seed_audience_id
|
integer | 种子人群 id，种子人群：覆盖人数 100-30000000, 状态必须是'成功可用', 不能是扩展人群 |
|
expand_user_count
|
integer | lookalike 目标人数，是 500000 的整数倍 |
|
user_action_spec
|
struct | UserAction 人群信息，当 type=USER_ACTION 时必填 |
|
user_action_set_id
|
integer | 用户行为源 id，通过 [user_action_sets 接口] 创建用户行为源时分配的唯一 id。请注意，当填写的用户行为数据源类型为 {WECHAT, WECHAT_MINI_PROGRAM, WECHAT_MINI_GAME} 时，必填 user_id 字段中的 wechat_openid (或 wechat_unionid) 及 wechat_app_id。 |
|
match_rule_type
|
enum | 匹配规则类型，当 user_action_set 为 Android/iOS APP 类型时只可选 ACTION，[枚举详情] |
|
extract_type
|
enum | 行为人群提取类型，当 match_rule_type=ACTION 时生效 |
|
time_window
|
integer | 时间窗，用来圈定最近多少天发生过某行为的人群，如今天是 1 月 14 日，则最近 14 天的范围是 1 月 1 日至 1 月 14 日。当 extractType = AGGREGATION 时，时间窗最大取值为 90 天 |
|
url_match_rule
|
struct | url 匹配规则，当 match_rule_type = URL 时必填 |
|
url_matcher_group
|
struct[] | 匹配规则组，如果为空表示全站浏览人群，多个组之间是 AND 关系 |
|
url_matcher
|
struct[] | 匹配规则，多个匹配规则之间是 OR 关系 |
|
param_value
|
string | 参数值 |
|
operator
|
enum | 运算符，operator 只允许 EQ、NE、CONTAIN、NOT_CONTAIN，[枚举详情] |
|
action_match_rule
|
struct | 行为和参数匹配规则，当 match_rule_type = ACTION，extractType 为空或者 extractType = FITLER 时必填 |
|
action_type
|
enum | 标准行为类型，当值为 'CUSTOM' 时表示自定义行为类型，[枚举详情] |
|
custom_action
|
string | 自定义行为类型，当 action_type=CUSTOM 时必填 |
|
param_matcher_group
|
struct[] | 匹配规则组，多个组之间是 AND 关系 |
|
param_matcher
|
struct[] | 匹配规则，多个匹配规则之间是 OR 关系 |
|
param_name
|
string | 参数名称 |
|
param_value
|
string | 参数值 |
|
operator
|
enum | 运算符，[枚举详情] |
|
action_aggregation_rule
|
struct | 行为和参数聚合规则，当 match_rule_type = ACTION，extractType = AGGREGATION 时必填 |
|
action_type
|
enum | 标准行为类型，当值为 'CUSTOM' 时表示自定义行为类型，[枚举详情] |
|
custom_action
|
string | 自定义行为类型，当 action_type=CUSTOM 时必填 |
|
aggregation_group
|
struct[] | 聚合规则数组，多个组之间是 AND 关系 |
|
aggregation_matcher
|
struct[] | 匹配规则组，多个组之间是 OR 关系 |
|
aggregation_type
|
enum | 聚合类型，[枚举详情] |
|
count_type
|
enum | 频次类型，aggregation_type = COUNT 时必填，[枚举详情] |
|
param_name
|
string | 参数名称，当 aggregation_type != COUNT 时必填 |
|
comparator
|
enum | 比较符，[枚举详情] |
|
comparison_value
|
integer | 参数值，当 comparator != COMPARATOR_BETWEEN 时必填 |
|
comparison_min_value
|
integer | 参数值，当 comparator = COMPARATOR_BETWEEN 时必填 |
|
comparison_max_value
|
integer | 参数值，当 comparator = COMPARATOR_BETWEEN 时必填 |
|
filter_group
|
struct[] | 匹配规则组，多个组之间是 AND 关系 |
|
param_matcher
|
struct[] | 匹配规则，多个匹配规则之间是 OR 关系 |
|
param_name
|
string | 参数名称 |
|
param_value
|
string | 参数值 |
|
operator
|
enum | 运算符，[枚举详情] |
|
lbs_spec
|
struct | LBS 人群信息，当 type=LBS 时必填 |
|
lbs_type
|
enum | LBS 类型，LBS 类型只允许 POI、CROSS_CITY、CUSTOM_LOCATION，[枚举详情] |
|
cross_city_rule
|
struct | 跨城市规则，当 lbs_type=CROSS_CITY 时必填； route 不能超过 10 个 |
|
route
|
string[] | 路线，出发地和目的地的组合，均使用地址的编码值，比如北京的编码为 1，上海的编码为 2 则北京到上海表示为"1~2"； 0 表示不限，出发的和目的地最多只能一个为 0，不能都为 0，不能填写"0~0"，路线不能为空 |
|
date_range
|
struct | 时间范围，日期格式，{"start_date":"2017-03-01","end_date":"2017-04-02"} |
|
start_date
|
string | 开始时间，大于等于 0，不能早于 1 年前，且小于 end_date |
|
end_date
|
string | 结束时间，小于等于今天，且大于 start_date |
|
frequency
|
integer | 行为次数，行为次数至少为 1 |
|
poi_rule
|
struct | POI 规则，当 lbs_type=POI 时必填； region_id 个数不能超过 50 个； poi_category_id 个数不能超过 10 个 |
|
region_id
|
integer[] | 地区编码 |
|
poi_category_id
|
integer[] | POI 分类编码 |
|
date_range
|
struct | 时间范围，日期格式，{"start_date":"2017-03-01","end_date":"2017-04-02"} |
|
start_date
|
string | 开始时间，大于等于 0，不能早于 1 年前，且小于 end_date |
|
end_date
|
string | 结束时间，小于等于今天，且大于 start_date |
|
day_of_week
|
enum[] | week 类型，week 类型只允许 MONDAY、TUESDAY、WEDNESDAY、THURSDAY、FRIDAY、SATURDAY、SUNDAY，[枚举详情] |
|
frequency
|
integer | 行为次数，行为次数至少为 1 |
|
custom_location_rule
|
struct | 自定义地理位置规则，当 lbs_type=CUSTOM_LOCATION 时必填 |
|
poi_type
|
enum | LBS 兴趣点类型，[枚举详情] |
|
date_range
|
struct | 时间范围，日期格式，{"start_date":"2017-03-01","end_date":"2017-04-02"}；时间范围需在最近一年内，最大时间跨度为 60 天 |
|
start_date
|
string | 开始时间，大于等于 0，不能早于 1 年前，且小于 end_date |
|
end_date
|
string | 结束时间，小于今天，且大于 start_date |
|
frequency_spec
|
struct | 频次定义 |
|
comparator
|
enum | LBS 频次比较操作符类型，目前仅支持 COMPARATOR_BETWEEN，[枚举详情] |
|
frequency_min_value
|
integer | 最小频次值，当 comparator 为 COMPARATOR_BETWEEN 时必填 |
|
frequency_max_value
|
integer | 最大频次值，当 comparator 为 COMPARATOR_BETWEEN 时必填 |
|
area_list
|
struct[] | 地理位置列表 |
|
area_type
|
enum | LBS 自定义区域类型，[枚举详情] |
|
circle_area
|
struct | 圆形区域定义，当 area_type 为 CIRCLE 是必填 |
|
longitude
|
float | 经度，单位度 |
|
latitude
|
float | 纬度，单位度 |
|
radius
|
integer | 自定义 lbs 打点半径，单位：米 |
|
keyword_spec
|
struct | Keyword 人群信息，当 type=KEYWORD 时必填 |
|
include_keyword
|
string[] | 包含关键词，最多 100 个，单个关键词字数不超过 10 |
|
exclude_keyword
|
string[] | 排除关键词，最多 20 个，单个关键词字数不超过 10 |
|
ad_rule_spec
|
struct | 广告人群信息，当 type=AD 时必填 |
|
rule_type
|
enum | 广告行为类型，其中 EXPOSURE 类型需要线下联系运营开通白名单方可使用，[枚举详情] |
|
conversion_type
|
enum[] | 广告转化类型，当 rule_type=CONVERSION 时该字段必填，否则该字段不能填写，[枚举详情] |
|
start_date
|
string | 数据起始日期，格式为 yyyy-MM-dd，必须在 90 天以内，且在今天（不包含）以前 |
|
end_date
|
string | 数据结束日期,格式为 yyyy-MM-dd，必须在 start_date（包含）之后，且在今天（不包含）以前。如果未填写，则人群数据会随源投放数据更新。 |
|
campaign_id_list
|
integer[] | 需要提取人群的 campaign id 列表,通过 [campaigns/get] 接口可获得账号下的推广计划列表，campaign_id_list 和 product_list 字段至多只能填写一个，二者都不填则表示提取该广告主 id 下的所有 campaign 的广告行为数据 |
|
promoted_object_list
|
struct[] | 需要提取人群的推广目标列表，通过 [products/get] 模块可获得账号下的推广目标列表，campaign_id_list 和 product_list 字段至多只能填写一个，二者都不填则表示提取该广告主 id 下的所有 campaign 的广告行为数据 |
|
promoted_object_type
|
enum | 推广目标类型，[枚举详情] |
|
product_refs_id
|
string | 推广目标 id |
|
adgroup_id_list
|
integer[] | 需要提取人群的 adgroup id 列表,通过 [adgroups/get] 接口可获得账号下的广告组列表，campaign_id_list,product_list 和 adgroup_id_list 字段至多只能填写一个，三者都不填则表示提取该广告主 id 下的所有广告行为数据 |
|
combine_spec
|
struct | 组合人群信息，当 type=COMBINE 时必填，最多允许用 500 个人群做组合 |
|
include
|
struct[] | 包含的人群，注意这是个二维数组，第一层数组元素之间为 AND 关系，第二层数组元素之间为 OR 关系 |
|
audience_id
|
integer | 人群 id 或标签 id，通过 [custom_audiences] 模块创建客户人群或[custom_tags] 模块创建客户标签获得，即此处支持填写"audience_id":"<AUDIENCE_ID>"，也支持填写"audience_id":"<TAG_ID>"，不支持 LOOKALIKE 和 COMBINE 人群的 id |
|
time_window
|
integer | 时间窗，仅对客户标签有效，目前仅支持以下几个时间窗选项：1、3、7、10、15、30、90、180、365 |
|
exclude
|
struct[] | 排除的人群，注意这是个二维数组，第一层数组元素之间为 AND 关系，第二层数组元素之间为 OR 关系 |
|
audience_id
|
integer | 人群 id 或标签 id，通过 [custom_audiences] 模块创建客户人群或[custom_tags] 模块创建客户标签获得，即此处支持填写"audience_id":"<AUDIENCE_ID>"，也支持填写"audience_id":"<TAG_ID>"，不支持 LOOKALIKE 和 COMBINE 人群的 id |
|
time_window
|
integer | 时间窗，仅对客户标签有效，目前仅支持以下几个时间窗选项：1、3、7、10、15、30、90、180、365 |
|
page_info
|
struct | 分页信息 |
|
page
|
integer | 当前页码 |
|
page_size
|
integer | 分页大小 |
|
total_number
|
integer | 总行数 |
|
total_page
|
integer | 总页数 |
应答示例
{
"code": 0,
"message": "",
"message_cn": "",
"data": {
"list": [
{
"audience_id": "<AUDIENCE_ID>",
"account_id": 111111111,
"name": "测试人群",
"outer_audience_id": "123",
"description": "",
"cooperated": true,
"type": "CUSTOMER_FILE",
"source": "TENCENT_DATA",
"status": "PENDING",
"error_code": 0,
"user_count": 0,
"is_own": true,
"created_time": "2016-11-01 10:42:56",
"last_modified_time": "2017-10-21 17:11:17"
},
{
"audience_id": "<AUDIENCE_ID>",
"account_id": 111111111,
"name": "website_demo",
"outer_audience_id": "124",
"description": "",
"cooperated": false,
"type": "USER_ACTION",
"source": "ADVERTISER_OWN_DATA",
"status": "PENDING",
"error_code": 0,
"user_count": 0,
"is_own": true,
"created_time": "2016-11-01 10:42:56",
"last_modified_time": "2017-10-21 17:11:17",
"audience_spec": {
"user_action_spec": {
"action_set_id": "<ACTION_SET_ID>",
"match_rule_type": "URL",
"url_match_rule": {
"url_matcher_group": [
{
"url_matcher": [
{
"param_value": "qq",
"operator": "CONTAIN"
}
]
}
]
},
"time_window": 30
}
}
}
],
"page_info": {
"page": 1,
"page_size": 10,
"total_number": 2,
"total_page": 1
}
}
}可视化调试工具
相关阅读
问题仍未解决？
请前往腾讯广告反馈中心在线提交问题，我们的人工客服将为你服务