# TikTok Trending Hashtags by Country (`adaptable_wheelhouse/tiktok-trending-hashtags`) Actor

- **URL**: https://apify.com/adaptable_wheelhouse/tiktok-trending-hashtags.md
- **Developed by:** [Mr T](https://apify.com/adaptable_wheelhouse) (community)
- **Categories:** Social media
- **Security:** Limited permissions
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### TikTok Trending Hashtags by Country

Trending TikTok hashtags for **any country**, plus TikTok's top videos. No TikTok login.

- **27 countries** (AE, AR, AU, BR, CA, CO, DE, EG, ES, FR, GB, ID, IL, IT, JP, KR, MX, MY, PH, SA, SG, TH, TR, TW, US, VN, ZA) come from TikTok Creative Center's chart: rank, posts, video views, industry, a daily popularity curve and top creators.
- **Every other country** (NG, KE, PL, NL, SE, LU, IS, PK, QA...) has no logged-out Creative Center chart. For these, the actor reads 500 videos of the country's Explore feed through residential IPs in the country, then ranks the hashtags by how many creators and videos use them. Each row also gets the hashtag's worldwide posts and views.

```json
{ "trendType": "hashtags", "countryCode": "NG", "maxItems": 20 }
```

#### Hashtag rows

| Field | Creative Center | Explore sample |
|---|---|---|
| `Rank`, `Hashtag`, `Hashtag ID`, `TikTok URL`, `Country`, `Country Code` | yes | yes |
| `Posts`, `Video Views` | in the country, over the period | worldwide totals |
| `Industries`, `Trend Direction`, `Trend Stats`, `Trend Data` | yes | empty |
| `Top Creators` | top creators with followers | up to 5 creators from the sample |
| `Videos In Sample`, `Creators In Sample`, `Sample Size`, `Sample Plays`, `Top Video URL`, `Top Video Plays` | — | yes |
| `Source` | `creative-center` | `explore-sample` |

Logged-out Creative Center returns at most 3 hashtags per filter. With industry left on All, the actor requests every industry and keeps unique hashtags until **Maximum items**. In default mode, `Rank` is sequential collection order across these lists, not a national chart position.

The Explore ranking leaves out tags added to reach the For You feed (#fyp, #foryou, #viral and the like) and TikTok's own program tags (#capcutpioneer, #creatorsearchinsights). It also leaves out tags used by only one creator. Small countries see much of the same European or global feed, so their lists mix local tags with international ones.

Set **Hashtag source** to "Explore sample for every country" to rank the 27 Creative Center countries from their feed too.

#### Opt-in Trend Radar signals

```json
{"trendType":"hashtags","countryCode":"AE","hashtagPeriod":"7","maxItems":50,"signalMode":"trend-radar"}
```

Omit `signalMode` or use `"default"` to retain the output described above. The opt-in mode applies only to hashtags:

- Creative Center rows use the same generic/program-tag filter as Explore. Filtered rows do not count toward `maxItems`; industry requests can fill the remaining places.
- Every accepted row includes `Signal Mode: "trend-radar-v1"` and `Rank Scope`. Country-chart rows have scope `country` and retain a valid native upstream rank, including gaps after filtering. Industry candidates have scope `industry` and `Rank: null`; they are not nationally ranked. Explore keeps its sample ranking with scope `sample`.
- Chart direction uses valid, distinct, chronologically ordered curve timestamps. Fewer than two observations means unknown (`null`), not flat. Missing/invalid posts and views stay `null`; measured zero remains zero.
- Explore skips worldwide-total lookups, including fallback-country lookup sessions. `Posts` and `Video Views` stay `null`; sample counts, creators, plays and top-video evidence remain. Sampling, result charging and proxy requirements are unchanged.

This mode improves signal semantics, not geographic representativeness or completeness. Fewer generic tags and unranked industry candidates can change downstream seed selection. Skipping enrichment removes work but does not reduce the configured per-result or sampling prices. Downstream clip/campaign quality and live latency gains have not been measured.

These mode changes are local and offline-tested; the previously tested published build `0.1.4` does not contain them. Publishing and validating a compatible build must precede deploying a consumer that requires `trend-radar-v1`. No publication is part of this change.

#### Videos

`trendType: "videos"`. Each row has rank, title, author, weekly and lifetime views, organic views, engagement, and the video URL. Logged-out TikTok returns 4 videos per category. The US chart is the one that responds.

#### Pricing

| Event | Price |
|---|---|
| Hashtag or video saved | $0.002 |
| 100 Explore videos sampled (only countries without a Creative Center chart) | $0.015 |

A Creative Center country with 20 hashtags costs $0.04. A sampled country with 500 videos and 20 hashtags costs $0.115.

# Actor input Schema

## `trendType` (type: `string`):

Trend type

## `maxItems` (type: `integer`):

Maximum items

## `signalMode` (type: `string`):

Trend Radar filters generic chart tags, preserves country ranks (industry extras are unranked), leaves missing measurements unknown, and skips worldwide totals for Explore. Adds versioned Signal Mode and Rank Scope fields. Default output is unchanged. Applies only to hashtags.

## `countryCode` (type: `string`):

Two-letter country code. Any country: Creative Center charts for AE, AR, AU, BR, CA, CO, DE, EG, ES, FR, GB, ID, IL, IT, JP, KR, MX, MY, PH, SA, SG, TH, TR, TW, US, VN and ZA; every other country (NG, PL, KE, LU, IS...) is ranked from a sample of its Explore feed.

## `hashtagSource` (type: `string`):

Creative Center's chart has posts, views and a 7/30/90-day curve. The Explore sample ranks the hashtags of videos TikTok shows in the country right now, by how many videos and creators use them.

## `exploreSampleVideos` (type: `integer`):

Explore videos read for a country without a Creative Center chart. Charged per 100 videos read.

## `hashtagPeriod` (type: `string`):

Hashtag period

## `industryId` (type: `string`):

Hashtag industry

## `videoCountry` (type: `string`):

Logged-out TikTok currently returns top videos for the US. Other countries come back empty.

## `videoPeriod` (type: `string`):

Video period

## `videoContentTag` (type: `string`):

Video category

## `videoOrderBy` (type: `string`):

Video sort

## `videoOrganicOnly` (type: `boolean`):

Organic views only

## `saveMedia` (type: `boolean`):

Accepted for compatibility. Image URLs are the TikTok CDN links from the response.

## `proxyConfiguration` (type: `object`):

Proxy

## `debugLog` (type: `boolean`):

Log every refused request.

## Actor input object example

```json
{
  "trendType": "hashtags",
  "maxItems": 20,
  "signalMode": "default",
  "countryCode": "US",
  "hashtagSource": "auto",
  "exploreSampleVideos": 500,
  "hashtagPeriod": "7",
  "industryId": "",
  "videoCountry": "US",
  "videoPeriod": "7",
  "videoContentTag": "",
  "videoOrderBy": "1",
  "videoOrganicOnly": false,
  "saveMedia": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "debugLog": false
}
```

# Actor output Schema

## `results` (type: `string`):

Rows saved to the dataset.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "trendType": "hashtags",
    "maxItems": 20,
    "countryCode": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("adaptable_wheelhouse/tiktok-trending-hashtags").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "trendType": "hashtags",
    "maxItems": 20,
    "countryCode": "US",
}

# Run the Actor and wait for it to finish
run = client.actor("adaptable_wheelhouse/tiktok-trending-hashtags").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "trendType": "hashtags",
  "maxItems": 20,
  "countryCode": "US"
}' |
apify call adaptable_wheelhouse/tiktok-trending-hashtags --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,adaptable_wheelhouse/tiktok-trending-hashtags"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/kisehvoAv8DfybRGw/builds/xBsImUltCJQAGaNcc/openapi.json