Get popular hashtags

Use this endpoint to get a list of the top 200 popular hashtags on TikTok.

Request

Endpoint https://business-api.tiktok.com/open_api/v1.3/discovery/trending_list/

Method GET

Header

|Field{30%}|Data Type{15%}|Description{55%}|
|---|---|---|
|Access-Token {Required}|string|Authorized access token. For details, see [Authentication](1738373164380162.html).|

Parameters

|Field{30%}|Data Type{15%}|Description{55%}|
|--- |--- |--- |
|advertiser_id {Required}|string|Advertiser ID.<br><br>Pass one of the advertiser IDs returned via `advertiser_ids` from [/oauth2/access_token/](1738373164380162.html).|
|discovery_type {Required}|string|The type of discovery item.<br><br>Currently, we only support `HASHTAG`.|
|country_code|string|Location code.<br><br>Default value: `US`. <br><br>See [Location code](1737585867307010.html) for the supported values.|
|category_name|string|The name of the hashtag industry category.<br><br>To learn about the enum values, see <a href="#item-link-Hashtag industry category names">Hashtag industry category names</a>. You can pass either a level-1 category name or a level-2 category name.<br><br>Default value: `ALL`.<br><br>Example: `FOOD_AND_BEVERAGE`.<br><br>If you pass `category_name` and `industry_id` at the same time, `industry_id` will be ignored.|
|date_range|string|The timeframe in which the items have been popular.<br><br>Enum values:<ul><li>`1DAY`: last 1 day.</li><li>`7DAY`: last 7 days.</li><li>`30DAY`: last 30 days.</li><li>`120DAY`: last 120 days.</li></ul><br>Default value: `7DAY`. |

Hashtag industry category names

The following table lists the level-1 and level-2 hashtag industry category names that you can pass to category_name.

Example

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/discovery/trending_list/?advertiser_id={{advertiser_id}}&discovery_type=HASHTAG&category_name=ALL&country_code=US&date_range=7DAY' \
--header 'Access-Token: {{Access-Token}}' \
(/code)

Response

|Field{30%}|Type{15%}|Description{55%}|
|---|---|---|
|code |number|Response code. For the complete list of response codes and descriptions, see [Appendix-Return Code](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). |
|message|string|Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097).|
|request_id |string|The log ID of a request, which uniquely identifies the request.  |
|data |object|Returned data.|
#|filter_info|object|Filtering information that is specified in your request.<br><br>If you don't include the following parameters in the request, we will return the default values for them, which are `date_range = 7DAY`, `country_code = US`, `industry_id = ALL`, and `category_name = ALL`.|
##|date_range|string|The timeframe in which the items have been popular.<br><br>Enum values:<ul><li>`1DAY`: last 1 day.</li><li>`7DAY`: last 7 days.</li><li>`30DAY`: last 30 days.</li><li>`120DAY`: last 120 days.</li></ul>|
##|country_code|string|Location code.<br><br>See [Location code](1737585867307010.html) for the enum values.<br><br>Example: `DE`.|
##|category_name|string|The name of the hashtag industry category.<br><br>To learn about the enum values, see <a href="#item-link-Hashtag industry category names">Hashtag industry category names</a>.<br><br>Example: `FOOD_AND_BEVERAGE`.|
#|list|object[]|The list of popular hashtags.|
##|hashtag_id|string|Hashtag ID.<br><br>Example: `4268426520694`.|
##|hashtag_name|string|Hashtag name.<br><br>Example: `yummy`.|
##|rank_position|string|Current rank position of the hashtag among hashtags within the same category (`category_name`) or industry (`industry_id`) in the selected region (`country_code`).<br><br>Example: `100`.|
##|rank_change|string|The change in rank position compared to the rank in the last time period.<br><br><ul><li>A positive `rank_change` indicates an increase in rank. For example, if the rank position shifts from 5 to 1, `rank_change` will be `4`.</li><li>A negative `rank_change` indicates a decrease in rank. For example, if the rank position shifts from 1 to 5, `rank_change` will be `-4`.</li><li>A `rank_change` of `0` indicates no changes in rank.</li><li>A `rank_change` marked as `NEW` indicates that the hashtag was not present in the top 200 ranking list in the last time period.</li></ul> |
##|views|integer|The number of views for related videos that feature this hashtag in the selected region and timeframe.<br><br><p><span style="color:darkred"><b>Note</b></span>: If you fail to specify `country_code` or `date_range` in your request, we will return data based on the default values for these two parameters, which are `date_range = 7DAY` or `country_code = US`.<br><br>Example: 134333716.|
##|views_global_lifetime|integer|The number of views for related videos that feature this hashtag, globally and across their whole lifetime.<br><br>Example: 91639649280.|
##|posts|integer|The number of posts for related videos that feature this hashtag in the selected region and timeframe.<br><br><p><span style="color:darkred"><b>Note</b></span>: If you fail to specify `country_code` or `date_range` in your request, we will return data based on the default values for these two parameters, which are `date_range = 7DAY` or `country_code = US`.<br><br>Example: 21856.|
##|posts_global_lifetime|integer|The number of posts for related videos that feature this hashtag, globally and across their whole lifetime.<br><br>Example: 7846729.|
##|top_country_list|string[]|The location codes of the top five locations in the world where this hashtag is most popular.<br><br>To learn about the location that a location code represents, see [Location code](1737585867307010.html).<br><br>Example: `["US", "GB", "PH", "CA", "DE"]`.|
##|trending_history|object[]|The historical ranking data for the hashtag, spanning up to the past 30 days..|
###|date|string|Date, in the format of `YYYY-MM-DD`.<br><br>Example: `2024-01-01`.|
###|rank_position_daily|string|The rank position of the hashtag among hashtags across all categories or industries in the selected region (`country_code`) on the date.<br><br>Example: `73`.<br><br><p><span style="color:darkred"><b>Note</b></span>: If the hashtag does not perform well compared to the last time period, the hashtag will not be considered a trending hashtag and the value of this field will be null.|
###|views_daily|integer|The number of views for related videos that feature this hashtag in the selected region (`country_code`) on the date.<br><br>Example: 21215985.<br><br><p><span style="color:darkred"><b>Note</b></span>: If the daily views are less than 1,000, the value of this field will be null.|

Example

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "list": [
            {
                "posts": 44585,
                "rank_change": "0",
                "hashtag_id": "{{hashtag_id}}",
                "hashtag_name": "{{hashtag_name}}",
                "views_global_lifetime": 136840398711,
                "posts_global_lifetime": 26055679,
                "rank_position": "1",
                "views": 836896026,
                "top_country_list": [
                    "US",
                    "TH",
                    "ID",
                    "VN",
                    "PH"
                ],
                 "trending_history": [
                {
                "date": "2024-03-09",
                "rank_position_daily": "121",
                "views_daily": 39181186
                },
                ...
                {
                "date": "2024-04-06",
                "rank_position_daily": "85",
                "views_daily": 49419265
                },
                {
                "date": "2024-04-07",
                "rank_position_daily": "128",
                "views_daily": 45524768
                }
             ]
            },
            {
                "posts": 148372,
                "rank_change": "0",
                "hashtag_id": "{{hashtag_id}}",
                "hashtag_name": "fashion",
                "views_global_lifetime": 303784465772,
                "posts_global_lifetime": 39054276,
                "rank_position": "2",
                "views": 508388428,
                "top_country_list": [
                    "US",
                    "VN",
                    "ID",
                    "MX",
                    "GB"
                ],
                "trending_history": [
                {
                "date": "2024-03-09",
                "rank_position_daily": "121",
                "views_daily": 39181186
                },
                ...
                {
                "date": "2024-04-06",
                "rank_position_daily": "85",
                "views_daily": 49419265
                },
                {
                "date": "2024-04-07",
                "rank_position_daily": "128",
                "views_daily": 45524768
                }
             ]
            },
            {
            ...
            }
        ],
        "filter_info": {
            "country_code": "US",
            "date_range": "7DAY",
            "category_name": "ALL"
        }
    }
}
(/code)