获取潜在受众详情

使用该接口获取您的潜在受众详情。

注意
该接口使用POST方法。

请求

地址 https://business-api.tiktok.com/open_api/v1.3/audience/insight/info/

方法 POST

Header

|Field|Data Type|Description|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型。<br>允许格式：`"application/json"`。|

参数

|字段|类型|描述|
|---|---|---|
|advertiser_id {必填}|string|广告主ID。|
|custom_audience_id {+条件必填}|string|当请求中未指定`locations`时必填。 <br>自定义受众ID。<br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>当指定了`custom_audience_id`时，不能使用`selected_audience`或`locations`。否则会报错。</li><li>您输入的受众ID必须属于您指定的广告商。</li></ul>|
|locations {+条件必填}|object[]| 当请求中未指定`custom_audience_id`时必填。 <br>地域。 <br>最大数量：5。<br><p><span style="color:darkred"><b>注意</b></span>：当指定了`locations`，不能使用`custom_audience_id`。否则会报错。|
#|country_code {必填}|string| 国家代码。查看[附录-地域定向](1739311040498689.html)获取详情。|
#|location_ids|string[]|地域ID。<br>默认情况下，将选择指定国家代码下的所有地域ID。您输入的地域ID必须在指定的国家代码范围内。|
|dimensions{必填}|string[]|使用该字段控制返回响应的维度。<br>枚举值：`age`，`gender`，`country`，`top_regions`，`operating_system`，`operating_system_version`，`device_price`， `top_interests`，`bottom_interests`，`engagement`，`ad_interest_categories`，`top_hashtags`。<br><p><span style="color:darkred"><b>注意</b></span>：目前，每次API调用只能输入一个维度。|
|selected_audience|object|您想筛选的受众。|
#|top_regions_country_code {+条件必填}|string|若您在`dimensions`字段中选择了`top_regions`并指定了`locations`，则该字段为必填。 当您在`dimensions`字段中选择了`top_regions`时，相应的返回字段将包含您在`locations`中指定国家的子区域。|
#|languages|string[]|您想定向的语言代码。<br>语言代码列表详见 [枚举值-受众语言](1737174886619138.html)。您也可以通过[/tool/language/](https://ads.tiktok.com/marketing_api/docs?id=1737188554152962)获取语言代码。|
#|age_groups|string[]|您想定向的年龄区间。<br>枚举值详见[枚举值-受众年龄区间](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Age%20Group)。|
#|gender|string[]|您想定向的性别。<br>枚举值：`GENDER_FEMALE`，`GENDER_MALE`。如果您不传入任何内容，则表示您希望将男性和女性都作为目标受众。 |
#|device_price_ranges|integer[]|您想定向的设备价格范围。<br>10000表示1000以上。这些数字必须是50的倍数。|
#|min_ios_version|string|最低iOS版本。<br>枚举值详见：[枚举值-最低iOS版本](1737174886619138.html)。|
#|min_android_version|string|最低Android版本。<br>枚举值详见：[枚举值-最低Android版本](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
#|operating_systems{+条件必填}|string[]|当指定`min_ios_version`或 `min_android_version`时必填。<br>您想定向的设备操作系统。<br>枚举值：`ANDROID`，`IOS`。只允许填入一个值。如果您不传入任何内容，则表示您希望同时定向Android和iOS系统。|
#|interest_category_ids|string[]|兴趣分类。<br>您可以使用[/tool/interest_category/](https://ads.tiktok.com/marketing_api/docs?id=1737174348712961)获取可用兴趣类别列表。<br>您可以使用[/tool/target_recommend_tags/](https://ads.tiktok.com/marketing_api/docs?id=1736275204260866)获取推荐兴趣类别列表。|
#|video_action_category_ids|string[]|视频动作类别ID。<br>您可以使用[/tool/action_category/](https://ads.tiktok.com/marketing_api/docs?id=1737166752522241)获取可用的视频互动类别列表（响应中的`action_scene` = `VIDEO_RELATED`）。<br>您可以使用[/tool/targeting_category/recommend/](https://ads.tiktok.com/marketing_api/docs?id=1736275204260866)获取推荐的视频互动类别列表（响应中的`scene` = `VIDEO_RELATED`）。|
#|creator_action_category_ids|string[]|创作者动作类别ID。<br>您可以使用[/tool/action_category/](https://ads.tiktok.com/marketing_api/docs?id=1737166752522241)获取可用的创作者互动类别列表（响应中的`action_scene` = `CREATOR_RELATED`）。您可以使用[/tool/targeting_category/recommend/](https://ads.tiktok.com/marketing_api/docs?id=1736275204260866)获取推荐的创作者互动类别列表（响应中的`scene` = `CREATOR_RELATED`）。|
#|hashtag_action_category_ids|string[]|话题ID。<br>您可以使用[/tool/hashtag/recommend/](1736271339521025.html)获取推荐的话题ID列表。您也可以使用[/tool/hashtag/get/](1736280889167874.html)通过ID获取话题。|

示例

当您指定 locations和selected_audience时

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/audience/insight/info/' \
--header 'Content-Type: application/json' \
--header 'Access-Token: {{Access-Token}}' \
--data '{
    "advertiser_id": "{{advertiser_id}}",
    "dimensions": [
        "age"
    ],
    "locations": [
        {
            "country_code": "US",
            "location_ids": []
        },
        {
            "country_code": "AU",
            "location_ids": [
                "{{location_ids}}"
            ]
        }
    ],
    "selected_audience": {

        "gender": [
            "GENDER_MALE"
        ],
        "age_groups": [
            "AGE_25_34",
            "AGE_35_44",
            "AGE_45_54",
            "AGE_55_100"
        ],
        "languages": [
            "fr",
            "en"
        ],
        "operating_systems": [
            "IOS"
        ],

        "device_price_ranges": [
            100,
            950
        ],
        "interest_category_ids": [
            "{{interest_category_ids}}",
            "{{interest_category_ids}}"
        ],
        "video_action_category_ids": [
            "{{video_action_category_ids}}",
            "{{video_action_category_ids}}"
        ],
        "creator_action_category_ids": [
            "{{creator_action_category_ids}}",
            "{{creator_action_category_ids}}"
        ],
        "hashtag_action_category_ids": [
            "{{hashtag_action_category_ids}}"
        ]
    }

}'
(/code)

当您指定custom_audience_id时

(code curl http)
curl --location 'https://business-api.tiktok.com/open_api/v1.3/audience/insight/info/' \
--header 'Content-Type: application/json' \
--header 'Access-Token: {{Access-Token}}' \
--data '{
    "advertiser_id": "{{advertiser_id}}",
    "dimensions": [
        "age"
    ],
  "custom_audience_id": "{{custom_audience_id}}"   
}'
(/code)

响应

|字段|类型|描述|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|request_id |string|请求的日志ID，唯一标识一个请求。|
|data |object|返回数据。|
#|age|object|年龄。如果您在请求中的`dimensions`里输入了`age`，则会返回此字段。<br>在下面列出的`all`和`selected`对象中，有两个字段传达了具体信息。详情见下方的代码示例。<ul><li>`label`：年龄组标签。它的数据类型是string。</li><li>`rate`：标签所占百分比。它的数据类型是number。</li><ul>|
##|all|object[]|所有受众（即定向地域受众）的年龄数据。<br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的年龄数据。|
#|gender|object|性别。如果您在请求中的`dimensions`里输入了`gender`，则会返回此字段。 <br>在下面列出的`all`和`selected`对象中，有两个字段传达了具体信息。<ul><li>`label`：性别标签。它的数据类型是string。</li><li>`rate`：标签所占百分比。它的数据类型是number。</li><ul>|
##|all|object[]|所有受众（即定向地域受众）的性别数据。 <br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的性别数据。|
#|country|object|国家。如果您在请求中的`dimensions`里输入了`country`，则会返回此字段。<br>在下面列出的`all`和`selected`对象中，有两个字段传达了具体信息。<ul><li>`label`：国家名。它的数据类型是string。</li><li>`rate`：国家所占百分比。它的数据类型是number。</li><ul>|
##|all|object[]|所有受众（即定向地域受众）的所在国家数据。<br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的所在国家数据。|
#|top_regions|object|国家。如果您在请求中的`dimensions`里输入了`country`，则会返回此字段。 <br>在下面列出的`all`和`selected`对象中，有几个字段传达了具体信息。<ul><li>`label`：地区名。它的数据类型是string。</li><li>`rate`：地区所占百分比。它的数据类型是number。</li><li>`region_id`：地区ID。它的数据类型是string。</li><li>`country_code`：国家代码。它的数据类型是string。</li><ul>|
##|all|object[]|所有受众（即定向地域受众）的所在地区数据。<br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的所在地区数据。|
#|operating_system|object|操作系统。如果您在请求中的`dimensions`里输入了`operating_system`，则会返回此字段。 <br>在下面列出的`all`和`selected`对象中，有两个字段传达了具体信息。<ul><li>`label`：操作系统。它的数据类型是string。</li><li>`rate`：操作系统所占百分比。它的数据类型是number。</li><ul>|
##|all|object[]|所有受众（即定向地域受众）的操作系统数据。<br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的操作系统数据。|
#|operating_system_version|object|操作系统版本。如果您在请求中的`dimensions`里输入了`operating_system_version`，则会返回此字段。 <br>在下面列出的`all`和`selected`对象中，有两个字段传达了具体信息。<ul><li>`label`：操作系统版本。它的数据类型是string。</li><li>`rate`：操作系统版本所占百分比。它的数据类型是number。</li><ul>|
##|all|object[]|所有受众（即定向地域受众）的操作系统版本数据。<br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的操作系统版本数据。|
#|device_price|object|设备价格。如果您在请求中的`dimensions`里输入了`device_price`，则会返回此字段。 <br>在下面列出的`all`和`selected`对象中，有两个字段传达了具体信息。<ul><li>`label`：设备价格。它的数据类型是string。</li><li>`rate`：设备价格所占百分比。它的数据类型是number。</li><ul>|
##|all|object[]|所有受众（即定向地域受众）的设备价格数据。<br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的设备价格数据。|
#|top_interests|object|排名靠前的兴趣。如果您在请求中的`dimensions`里输入了`top_interests`，则会返回此字段。 <br>在下面列出的`all`和`selected`对象中，有几个字段传达了具体信息。<ul><li>`label`：兴趣类别标签。它的数据类型是string。</li><li>`rate`：兴趣类别标签所占百分比。它的数据类型是number。</li><li>`ad_interest_category`：一级兴趣类别。它的数据类型是string。</li><ul>|
##|all|object[]|所有受众（即定向地域受众）的兴趣类别数据。<br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的兴趣类别数据。|
#|bottom_interests|object|排名靠后的兴趣。如果您在请求中的`dimensions`里输入了`bottom_interests`，则会返回此字段。<br>在下面列出的`all`和`selected`对象中，有几个字段传达了具体信息。<ul><li>`label`：兴趣类别标签。它的数据类型是string。</li><li>`rate`：兴趣类别标签所占百分比。它的数据类型是number。</li><li>`ad_interest_category`：一级兴趣类别。它的数据类型是string。</li><ul>|
##|all|object[]|所有受众（即定向地域受众）的兴趣类别数据。<br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的兴趣类别数据。|
#|ad_interest_categories|object|兴趣类别。如果您在请求中的`dimensions`里输入了`ad_interest_categories`，则会返回此字段。<br>在下面列出的all和selected对象中，有几个字段传达了具体信息。 <ul><li>`label`：兴趣类别标签。它的数据类型是string。</li><li>`rate`：兴趣类别标签所占百分比。它的数据类型是number。</li><li>`type`：兴趣类别层级。它的数据类型是string。例如：“first”。</li><ul>|
##|all|object[]|所有受众（即定向地域受众）的兴趣类别数据。<br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的兴趣类别数据。|
#|top_hashtags|object|热门话题。如果您在请求中的`dimensions`里输入了`top_hashtags`，则会返回此字段。|
##|hashtag_id|string|话题ID。|
##|hashtag_name|string|话题名称。|
##|count|number|该话题被引用的次数。|
#|engagement|object|互动数据指标。如果您在请求中的dimensions里输入了engagement，则会返回此字段。<br>在下面列出的`all`和`selected`对象中，有几个字段传达了具体信息。 <ul><li>`daily_sessions`：用户每天平均打开应用的次数。它的数据类型是number。</li><li>`daily_session_duration_in_minutes`：用户每天平均使用应用的分钟数。它的数据类型是number。</li><li> `daily_video_views`：用户每天平均观看视频的次数。它的数据类型是number。</li><li>`daily_comments`： 用户每天平均评论数量。它的数据类型是number。</li><li>`daily_likes`：用户每天平均点赞数量。它的数据类型是number。</li><li>`daily_shares`：用户每天平均分享数量。它的数据类型是number。</li><li>`total_video_uploads`：选定/所有用户每天平均上传视频的次数。它的数据类型是number。</li></ul>|
##|all|object[]|所有受众（即定向地域受众）的互动数据。<br>在如下情况中，`all`将返回空值：<ul><li>当您的受众规模少于1,000人时。</li><li>当您在请求中指定了`custom_audience_id`时。</li></ul>|
##|selected|object[]|您筛选的受众的互动数据。|

示例

当您在请求中指定了locations和selected_audience，响应内容如下：

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "age": {
            "all": [
                {
                    "label": "18-24",
                    "rate": 0.2258
                },
                {
                    "label": "25-34",
                    "rate": 0.3304
                },
                {
                    "label": "35-44",
                    "rate": 0.201
                },
                {
                    "label": "45-54",
                    "rate": 0.1327
                },
                {
                    "label": "≥55",
                    "rate": 0.1102
                }
            ],
            "selected": [
                {
                    "label": "25-34",
                    "rate": 0.5264
                },
                {
                    "label": "35-44",
                    "rate": 0.2073
                },
                {
                    "label": "45-54",
                    "rate": 0.136
                },
                {
                    "label": "≥55",
                    "rate": 0.1302
                }
            ]
        }
    }
}
(/code);

当您在请求中指定了custom_audience_id，响应内容如下：

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "age": {
            "all": [],
            "selected": [
                {
                    "label": "18-24",
                    "rate": 0.3896
                },
                {
                    "label": "25-34",
                    "rate": 0.3775
                },
                {
                    "label": "35-44",
                    "rate": 0.1485
                },
                {
                    "label": "45-54",
                    "rate": 0.0485
                },
                {
                    "label": "≥55",
                    "rate": 0.0359
                }
            ]
        }
    }
}
(/code)