获取顶级 TTO 达人排名
你可以使用本接口获取 TikTok One（TTO）达人排行榜中，某排名标签下最多 100 名排名最高的美国达人列表。
使用前需知
先使用接口 /tto/tcm/category/label/，并将 label_type 设置为 RANKING，以获取 TTO 达人排名标签。
请求
地址 https://business-api.tiktok.com/open_api/v1.3/tto/tcm/rank/
方法 GET
Header
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|由 TTO Creator Marketplace 账户授权的访问令牌。 <br>详情参见[从 TTO Creator Marketplace 账户获取授权和访问令牌](https://business-api.tiktok.com/portal/docs/obtain-authorization-and-authentication-from-a-tto-creator-marketplace-account/v1.3)。。|
参数
|字段{30%}|类型{15%}|描述{55%}|
|--- |--- |--- |
| tto_tcm_account_id {必填} | string | TikTok One Creator Marketplace 账户的 ID。<br><br>要获取您通过访问令牌 `Access-Token` 可访问的账户 ID，使用接口 [/tto/oauth2/tcm/](1815693478150146.html)。 |
| ranking_type {必填} | string | 排名类型。<br><br>枚举值：<ul><li>`BRANDED_CONTENT`：品牌内容排名。</li><li>`ORGANIC_CONTENT`：原生内容排名。</li></ul> |
| time_period {必填} | string | 排名时间周期。<br><br>枚举值：<ul><li>`WEEK`：一周。</li><li>`MONTH`：一个月。</li></ul> |
| time_period_lookback {必填} | string | 排名的具体回溯周期。<br><br>枚举值：<ul><li>`ONE`：最近一个时间周期。</li><li>`TWO`：倒数第二个时间周期。</li><li>`THREE`：倒数第三个时间周期。</li></ul><br>例如，如果最近一个月度周期是十月，且您将 `time_period` 设置为 `MONTH`，`time_period_lookback` 设置为 `TWO`，系统将返回九月的排名数据。 |
| label_id {必填} | string | 达人标签 ID。<br><br><ul><li>当 `ranking_type` 为 `BRANDED_CONTENT` 时，通过此字段指定达人行业标签。<ul><li>要获取达人行业标签，请使用接口 [/tto/tcm/category/label/](1816372654109698.html)，返回结果中的 `industry_labels` 即为可用标签。</li></ul></li><li>当 `ranking_type` 为 `ORGANIC_CONTENT` 时，通过此字段指定视频内容标签。<ul><li>要获取视频内容标签，请使用接口 [/tto/tcm/category/label/](1816372654109698.html)，返回结果中的 `content_labels` 即为可用标签。</li></ul></li></ul> |
| country_code {必填} | string | 达人排名所属国家或地区代码。<br><br>目前仅支持 `US` 枚举值，因为达人排名数据仅包含美国地区。 |
| page | integer | 当前页数。<br><br>取值范围：≥ 1。默认值：1。 |
| page_size | integer | 分页大小。<br><br>取值范围：1-100。默认值：20。 |
示例
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/tto/tcm/rank/?tto_tcm_account_id={{tto_tcm_account_id}}&ranking_type=ORGANIC_CONTENT&time_period=WEEK&time_period_lookback=ONE&label_id=11014001&country_code=US' \
--header 'Access-Token: {{Access-Token}}'
(/code)
返回
|Field{30%}|Type{15%}|Description{55%}|
|---|---|---|
|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|返回数据。|
#| creators | object[] | 按排名排序的最多 前 100 名达人列表。<br><br><p><span style="color:darkred"><b>注意</b></span>：实际返回的达人数量可能少于 100，具体取决于查询时可用的数据。|
##| ranking_change | string | 达人相较于上一个时间周期排名的变化。<br><br><ul><li>正数的 `rank_change` 表示排名上升。例如，排名从 5 上升到 1，`rank_change` 为 `+4`。</li><li>负数的 `rank_change` 表示排名下降。例如，排名从 1 下降到 5，`rank_change` 为 `-4`。</li><li>`rank_change` 为 `0` 表示排名无变化。</li><li>`rank_change` 标记为 `N/A` 表示达人在上一个时间周期的排名列表中不存在。</li></ul>|
##| profile_image | string | 达人头像的临时 URL，过期后需重新获取。URL 中 `x-expires` 参数后包含过期时间，格式为以秒为单位的 Epoch/Unix 时间戳。<br><br>示例： `https://p16-sign.tiktokcdn-us.com/obj/tos-useast5-avt-0123-tx/ab123456789d1234567ab54de76f0d3b?lk3s=429d27ce&nonce=42773&refresh_token=123a4ab1234567a1aa1a11a1aa11aa1a&x-expires=1732046400&x-signature=aa1Q11aa1Da1a1aVZO%1Fa1oADaL1%1D&shp=111d11ce&shcp=-`。 |
##| country | string | 达人所在国家或地区代码。<br><br>目前仅支持 `US` 枚举值，因为达人排名数据仅包含美国地区。|
##| handle | string | 达人账号名称。|
##| display_name | string | 达人显示名称。|
##| industry_labels | object[] | 与达人关联的行业标签列表。<br>达人行业标签基于其制作的商业内容（包括广告创意和其 TikTok 账号上的品牌内容），代表其在特定行业的商业经验。<br><br><p><span style="color:darkred"><b>注意</b></span>：即使达人不再拥有您查询的标签，仍可能出现在结果中，因为标签是在排名生成时关联的。但这些标签可能随时间变化，达人可能在排名生成后失去某个标签。|
###| label_id | string | 达人行业标签的 ID。|
###| label_name | string | 达人行业标签名称。|
##| content_labels | object[] | 与达人关联的内容标签列表。<br>内容标签根据达人 TikTok 账号的主要内容方向分配，代表达人的自然内容方向。<br><br><p><span style="color:darkred"><b>注意</b></span>：即使达人不再拥有您查询的标签，仍可能出现在结果中，因为标签是在排名生成时关联的。但这些标签可能随时间变化，达人可能在排名生成后失去某个标签。|
###| label_name | string | 内容标签的 ID。|
###| label_id | string | 内容标签名称。|
##| score | float | <ul><li>当 `ranking_type` 为 `BRANDED_CONTENT` 时，此字段表示商业评分，基于达人的商业内容经验及其过往商业内容表现计算。</li><li>当 `ranking_type` 为 `ORGANIC_CONTENT` 时，此字段表示粉丝增长评分（反映达人粉丝增长速度），基于指定时间段内达人粉丝增长和视频表现计算。</li></ul><br>示例：81.56906666666666。|
##| number_of_followers | integer | 粉丝数。<br>达人当前的粉丝数量。<br><br>示例：242703。|
##| branded_content_video_views | integer | 品牌内容视频观看次数。<br>指定时间段内，达人所有开启品牌内容开关的视频的总观看次数。<br><br>示例：528377。<br><br><p><span style="color:darkred"><b>注意</b></span>：仅当请求中的 `ranking_type` 为 `BRANDED_CONTENT` 时，该字段返回非 null 值。|
##| branded_content_engagement_rate | float | 品牌内容互动率。<br>指定时间段内品牌内容的互动率，计算公式为（品牌内容的评论数、点赞数和分享数总和）/（视频观看总数）。<br><br>例如，值为 3.02 表示品牌内容互动率为 3.02%。<br><br><p><span style="color:darkred"><b>注意</b></span>：仅当请求中的 `ranking_type` 为 `BRANDED_CONTENT` 时，该字段返回非 null 值。|
##| total_video_views | integer | 视频总观看次数。<br>指定时间段内，达人所有视频的总观看次数。<br><br>示例：633516。|
##| engagement_rate | float | 互动率。<br>指定时间段内，达人所有视频的综合互动率，计算公式为：（评论数、点赞数和分享数总和）/（视频观看总数）。<br><br>例如，值为 2.97 表示互动率为 2.97%。|
##| starting_price | integer | 达人的起始基础价格。<br><br>示例：30000。<br><br><p><span style="color:darkred"><b>注意</b></span>：如果达人未设置起始基础价格，该字段值为 null。|
##| starting_price_currency | string | 达人起始基础价格的币种。<br><br>示例：`USD`。<br><br><p><span style="color:darkred"><b>注意</b></span>：如果达人未设置起始基础价格，该字段值为空字符串（`""`）。|
##| follower_growth | integer | 指定时间段内新增的粉丝数。<br><br>示例：180476。<br><br><p><span style="color:darkred"><b>注意</b></span>：仅当请求中的 `ranking_type` 为 `ORGANIC_CONTENT` 时，该字段返回非 null 值。|
#| last_updated_at | string | 排名数据最后更新时间，UTC+0 时区，[ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) 格式。<br><br>示例：`2024-11-19T14:14:22Z`。|
#| page_info | object | 分页信息。|
##| page | number | 当前页数。|
##| page_size | number | 当页大小。|
##| total_number| number | 总结果数。|
##| total_page | number | 总页数。|
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"creators": [
{
"branded_content_engagement_rate": null,
"branded_content_video_views": null,
"content_labels": [
{
"label_id": "11014001",
"label_name": "Automobiles"
}
],
"country": "US",
"display_name": "{{display_name}}",
"engagement_rate": 1.95,
"follower_growth": 180476,
"handle": "{{handle}}",
"industry_labels": [
{
"label_id": "14100000000",
"label_name": "Oral Care"
}
],
"number_of_followers": 10711990,
"profile_image": "{{profile_image}}",
"ranking_change": "+1",
"score": 91.476275,
"starting_price": 30000,
"starting_price_currency": "USD",
"total_video_views": 329546252
},
...,
{
"branded_content_engagement_rate": null,
"branded_content_video_views": null,
"content_labels": [
{
"label_id": "11014001",
"label_name": "Automobiles"
}
],
"country": "US",
"display_name": "{{display_name}}",
"engagement_rate": 1.94,
"follower_growth": 6083,
"handle": "{{handle}}",
"industry_labels": null,
"number_of_followers": 132742,
"profile_image": "{{profile_image}}",
"ranking_change": "N/A",
"score": 82.74355,
"starting_price": null,
"starting_price_currency": "",
"total_video_views": 3213298
}
],
"last_updated_at": "2024-11-19T14:14:22Z",
"page_info": {
"page": 1,
"page_size": 20,
"total_number": 100,
"total_page": 5
}
}
}
(/code)