# Douyin 抖音 Search Scraper: Videos by Keyword (`theshark/douyin-search-scraper`) Actor

Search Douyin (抖音) by keyword without a login and get the videos and photo posts in Douyin's order, with rank, likes, comments, shares, the author, music, hashtags, search suggestions and direct MP4 links. Many keywords per run. Pay only for results.

- **URL**: https://apify.com/theshark/douyin-search-scraper.md
- **Developed by:** [TheShark](https://apify.com/theshark) (community)
- **Categories:** Social media, Videos, Automation
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 1,000 search 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

## Douyin 抖音 Search Scraper: Videos by Keyword

Search [Douyin](https://www.douyin.com) (抖音, the Chinese TikTok) by keyword and get the matching videos and photo posts in Douyin's own order. Every result comes with its rank and full details: likes, comments, shares and saves, the author, music, hashtags and topic tags, search suggestions, every video quality with direct MP4 links, covers and more.

No Douyin account, login, cookies or proxies of your own are needed. You pay only for videos that were collected.

### What can you do with Douyin Search Scraper?

- **Research a market or trend:** what Douyin shows for your keywords and how well it performs.
- **Find creators:** authors of the top videos for a topic, with their followers.
- **Track rankings:** the position of videos for a keyword over time (`search_rank`).
- **Collect content:** captions, hashtags, music and direct MP4 links.
- **Use it as a Douyin API:** start runs and get results from your own code through the Apify API.

### What data can you get from Douyin search?

| Data | Fields |
|---|---|
| Search | keyword, rank |
| Post | ID, link, caption, date, duration, type (video or photo post) |
| Engagement | likes, comments, shares, saves |
| Author | nickname, Douyin ID, sec_uid, verification, avatar |
| Video | play, download, H.264 and H.265 links, every quality, covers, long-lived links |
| Music, tags | music with MP3 link, hashtags, mentions, Douyin's topic tags, search suggestions |

### How to search Douyin

1. Enter keywords, one per line. Chinese keywords match best (e.g. 猫咪, 露营装备).
2. Set **Max videos per keyword**.
3. Click **Start**. Rows appear in the dataset in Douyin's order, with `keyword` and `search_rank`.
4. Download the results as JSON, CSV, Excel or HTML, or get them through the API.

### Input

| Field | Description |
|---|---|
| Search keywords | What to search for, one keyword or phrase per line. |
| Max videos per keyword | Stop after this many videos for each keyword (up to 1,000). |

```json
{
  "keywords": ["猫咪", "露营装备"],
  "maxResults": 100
}
```

### Output

One row per video, in Douyin's search order. Nested objects are always present (empty values when Douyin has no data), so every row has the same columns.

#### Post

| Field | Description |
|---|---|
| `aweme_id` | Douyin post ID. |
| `keyword` | The keyword this result was found for. |
| `search_rank` | Position in Douyin's results for that keyword (1 = first). |
| `url` | Canonical link: `https://www.douyin.com/video/<id>` (or `/note/<id>` for photo posts). |
| `share_url` | Douyin's share link (tracking query removed). |
| `post_type` | `video` or `images` (photo/slideshow post). |
| `aweme_type` | Douyin's raw post type (0 = video, 68 = photo post, others exist). |
| `media_type` | Douyin's raw media type (4 = video, 2 = images). |
| `desc` | Full description, including hashtags. |
| `caption` | Caption text as Douyin stores it separately (may be empty). |
| `item_title` | Title (long videos usually have one; may be empty). |
| `create_time` | Publish time, unix seconds. |
| `create_time_iso` | Publish time, ISO 8601 UTC. |
| `region` | Region code Douyin attaches to the post (often empty). |
| `is_top` | Pinned on the author's profile. |
| `is_aigc` | Douyin labels the post (or one of its pictures) as generated content. |
| `is_ads` | The post is a paid ad. |
| `danmaku_count` | Bullet-comment (弹幕) count — `0` in search results (not in the search payload). |
| `duration` | Duration in milliseconds (0 for photo posts). |
| `ok` | `true` for a successful row. |

#### Statistics

| Field | Description |
|---|---|
| `statistics.digg_count` | Likes. |
| `statistics.comment_count` | Comments. |
| `statistics.share_count` | Shares. |
| `statistics.collect_count` | Favourites (收藏). |
| `statistics.recommend_count` | Recommendations (推荐). Usually `0` in search results (Douyin's search payload omits it). |
| `statistics.admire_count` | Douyin's "admire" (赞赏) counter. Usually `0` on the web. |
| `statistics.play_count` | Views. **Usually `0`**: Douyin hides view counts on the web (they are app-only). A `0` does not mean nobody watched. |

#### Author

| Field | Description |
|---|---|
| `author_sec_uid` | Author's sec_uid (same as `author.sec_uid`). |
| `author.uid` | Numeric user ID. |
| `author.sec_uid` | Stable public user ID used in profile URLs. |
| `author.unique_id` | The @handle (Douyin ID); empty when the user never set one. |
| `author.short_id` | Legacy numeric Douyin ID (empty when not set). |
| `author.nickname` | Display name. |
| `author.signature` | Bio. |
| `author.avatar_thumb` | Avatar image URL. |
| `author.follower_count` | Followers. Usually `0` in search results — use the Douyin Profile Scraper for real counts. |
| `author.following_count` | Following (Douyin often reports 0 here). |
| `author.total_favorited` | Total likes the author has received. Usually `0` in search results. |
| `author.favoriting_count` | Likes the author has given. |
| `author.custom_verify` | Verification text (e.g. a creator badge). |
| `author.enterprise_verify_reason` | Business verification text. |
| `author.verification_type` | Douyin verification type code. |
| `author.cover_url` | The author's profile banner image URL. |

#### Video file

| Field | Description |
|---|---|
| `video_play_addr` | Main playback MP4 URL (empty for photo posts). |
| `video.play_addr_h264` | H.264 MP4 URL. Empty when Douyin serves the video only as H.265; `video_play_addr` always works. |
| `video.play_addr_265` | H.265/HEVC MP4 URL (smaller files, when available). |
| `video.download_addr` | Douyin's "download" rendition (may carry a watermark). |
| `video.width` | Source width in pixels. |
| `video.height` | Source height in pixels. |
| `video.ratio` | Douyin's ratio/quality label. |
| `video.cover` | Cover image URL. |
| `video.origin_cover` | Original cover image URL. |
| `video.dynamic_cover` | Animated cover URL. |
| `video.cdn_url_expired` | Unix time when the video URLs above stop working. |
| `video.play_url_stable` | **Long-lived link** to the same video as `video_play_addr` (an `api.amemv.com/aweme/v1/play/`-style URL). It redirects to a fresh CDN copy, so it keeps working after the direct links expire (still served the video 15 hours after capture; Douyin does not publish its lifetime). No cookies or headers needed. Empty for photo posts. |
| `video.format` | Douyin's preferred web delivery format (e.g. `dash`). It does not describe `video_play_addr`, which is always a complete MP4 with sound. |
| `video.download_url_stable` | Long-lived link to `video.download_addr`, same behaviour as `video.play_url_stable`. |
| `video.has_watermark` | Douyin's flag that a watermarked rendition exists. |
| `video.is_long_video` | Douyin classifies the video as long-form. |
| `video.bit_rate[]` | Every available quality (both `mp4` and `dash` renditions), each with: |
| `video.bit_rate[].gear_name` | Quality name (e.g. `normal_1080_0`). |
| `video.bit_rate[].quality_type` | Douyin quality code. |
| `video.bit_rate[].format` | `mp4` = complete file with sound. `dash` = video-only stream for adaptive players (no audio track) — pick an `mp4` row to download a watchable file. |
| `video.bit_rate[].bit_rate` | Bitrate, bits per second. |
| `video.bit_rate[].is_h265` | H.265 encoded. |
| `video.bit_rate[].fps` | Frames per second. |
| `video.bit_rate[].width` | Width in pixels. |
| `video.bit_rate[].height` | Height in pixels. |
| `video.bit_rate[].data_size` | File size, bytes. |
| `video.bit_rate[].url` | Direct URL for this quality (expires with `video.cdn_url_expired`). |
| `video.bit_rate[].url_stable` | Long-lived link to this quality (redirects to a fresh CDN copy). |
| `video.bit_rate_audio[]` | Audio-only DASH streams (AAC in fragmented MP4). Pair one with a `dash` video quality to build a full file (e.g. `ffmpeg -i video -i audio -c copy out.mp4`). Each with: |
| `video.bit_rate_audio[].bitrate` | Bitrate, bits per second. |
| `video.bit_rate_audio[].format` | Delivery format (DASH). |
| `video.bit_rate_audio[].codec_type` | Codec label as Douyin sends it — not reliable for audio (it can read like a video codec while the stream is AAC). |
| `video.bit_rate_audio[].quality` | Douyin quality label. |
| `video.bit_rate_audio[].size` | Stream size, bytes. |
| `video.bit_rate_audio[].url` | Direct URL (expires like the other CDN links). |
| `video.bit_rate_audio[].url_stable` | Long-lived link to this audio stream. |

#### Photo posts

| Field | Description |
|---|---|
| `images[]` | The pictures of a photo post (empty for videos), each with: |
| `images[].url` | Image URL. |
| `images[].download_url` | Douyin's download rendition (watermarked). |
| `images[].width` | Width in pixels. |
| `images[].height` | Height in pixels. |
| `images[].is_aigc` | Douyin labels this picture as generated content. |

#### Music

| Field | Description |
|---|---|
| `music_title` | Music title (same as `music.title`). |
| `music.id` | Music ID. |
| `music.title` | Title. |
| `music.author` | Artist / creator name. |
| `music.owner_id` | User ID of the music's owner. |
| `music.owner_nickname` | Owner's display name. |
| `music.duration` | Duration in seconds. |
| `music.is_original_sound` | The track is the creator's original sound. |
| `music.play_url` | MP3 URL. |
| `music.cover_large` | Music cover URL. |
| `music.album` | Album name (often empty). |
| `music.owner_handle` | The @handle of the music's owner. |
| `music.is_commerce_music` | Licensed commercial music from Douyin's library. |
| `music.is_pgc` | Professionally produced music (label/PGC), not a user's original sound. |

#### Hashtags, mentions, tags

| Field | Description |
|---|---|
| `hashtags[]` | Creator-typed hashtags, each with: |
| `hashtags[].hashtag_id` | Hashtag (challenge) ID. |
| `hashtags[].hashtag_name` | Hashtag text without `#`. |
| `mentions[]` | @mentions in the description, each with: |
| `mentions[].text` | The mention as written (e.g. `@name`). |
| `mentions[].uid` | Mentioned user's numeric ID. |
| `mentions[].sec_uid` | Mentioned user's sec_uid. |
| `video_tags[]` | Douyin's own 3-level topic classification (e.g. 美食 → 美食探店 → 餐厅探店), each with: |
| `video_tags[].tag_id` | Tag ID. |
| `video_tags[].tag_name` | Tag name. |
| `video_tags[].level` | 1, 2 or 3. |

#### Collection and location

| Field | Description |
|---|---|
| `mix.mix_id` | Collection (合集 / series) ID, empty when the post is not in one. |
| `mix.mix_name` | Collection name. |
| `mix.current_episode` | This post's episode number in the collection. |
| `mix.updated_to_episode` | Episodes published so far. |
| `poi.poi_id` | Tagged location (POI) ID, empty when none. |
| `poi.poi_name` | Tagged location name. |

#### Products (小黄车 shopping cards)

| Field | Description |
|---|---|
| `products[]` | Products the creator attached to the post (empty when none). Each with: |
| `products[].product_id` | Douyin shop product ID (stable). |
| `products[].promotion_id` | Promotion ID the card links to. |
| `products[].title` | Full product title. |
| `products[].elastic_title` | Short title shown on the card. |
| `products[].sales` | Units sold, as shown on the card. |
| `products[].comment_count` | Product reviews. |
| `products[].cover` | Product image URL. |
| `products[].url` | Product page on Douyin's shop (ecom.douyin.com). |
| `products[].shop_id` | Seller's shop ID. |
| `products[].goods_source` | Where the product comes from (e.g. 来自小店 = a Douyin shop). |
| `products[].category_names[]` | Category path, top-down (e.g. 服装 → 女装 → 其他套装). |
| `products[].tags[]` | Card tags (shipping promise, review count…). |

#### Chapters, summary and search suggestions

| Field | Description |
|---|---|
| `chapters[]` | Video chapters — the creator's own, or Douyin's automatic ones (see `chapter_source`). Each with: |
| `chapters[].title` | Chapter title. |
| `chapters[].detail` | Chapter description (may be empty). |
| `chapters[].timestamp_ms` | Chapter start, milliseconds. |
| `chapters[].cover` | Chapter thumbnail URL (creator chapters only). |
| `chapter_source` | "creator", "auto" (chapters Douyin made itself) or empty when the video has none. |
| `chapter_abstract` | Douyin's own summary of the whole video, when there is one. |
| `suggest_words[]` | The "大家都在搜" (people also search) queries Douyin shows under the post — real search demand around the video. Each with: |
| `suggest_words[].word` | The search query. |
| `suggest_words[].word_id` | Douyin ID of the query. |
| `suggest_words[].scene` | Where Douyin shows it (e.g. above the comments). |

#### Paid series (短剧 / 付费合集)

| Field | Description |
|---|---|
| `series.series_id` | Series ID (empty when the post is not in a series; often the same as `mix.mix_id`). |
| `series.series_name` | Series name as Douyin shows it. |
| `series.episode` | This post's episode number. |
| `series.total_episode` | Episodes in the series. |
| `series.total_duration` | Whole series duration, seconds. |
| `series.item_price` | Price as Douyin reports it (`0` = free). |
| `series.is_paid` | The series is a paid one. |

#### Permissions and status

| Field | Description |
|---|---|
| `permissions.allow_download` | Viewers may download the video in the app. |
| `permissions.allow_duet` | Duets (合拍) allowed. |
| `permissions.allow_stitch` | Stitching allowed. |
| `permissions.allow_share` | Sharing allowed. |
| `permissions.allow_comment` | Comments open. |
| `permissions.allow_record` | "Use this sound / shoot the same" allowed. |
| `status.private_status` | `0` = public; other values = restricted visibility. |
| `status.in_reviewing` | Under Douyin review. |
| `status.is_prohibited` | Restricted by Douyin. |

#### Row statuses

| Row | Meaning | Charged? |
|---|---|---|
| `ok: true` | The keyword was collected. | Yes |
| `ok: false` | The keyword was not collected. `error` and `reason` say why: `BlockedOrGone` means Douyin did not return this keyword; for any other value, run it again later. | No |
| `error: "Skipped"` | The run did not get to this input. Run it again. | No |

Rows with `ok: false` carry the `keyword`. A keyword with no matches gets one free row with `keyword`, `results: 0` and `ok: true`. When only part of a keyword's results came through, the collected videos stay in the dataset and its `ok: false` row gives their number in `results`.

### How much does it cost to search Douyin?

The actor uses pay-per-event pricing: a flat price per collected video and a small fee per run start. The current prices are on the **Pricing** tab. There is no extra fee per keyword.

| Event | When it is charged |
|---|---|
| Result | One video or photo post collected (`ok: true`). |
| Actor start | Once per run. |

You pay only for what was delivered:

- Only rows with data are charged. Rows with `ok: false` are free.
- Set a maximum cost per run in Apify and the actor stops cleanly when it is reached, keeping everything collected so far.
- Nothing is charged twice in one run, even if Apify restarts or migrates the run.

### Good to know

- **About 100–160 videos per keyword** is what Douyin's search shows; set **Max videos per keyword** lower to save cost.
- **Douyin's order.** Results come in the order Douyin ranks them; there are no sort or date filters.
- **View counts.** Douyin does not show view counts on its website, so `statistics.play_count` is usually `0`. Use `statistics.recommend_count`, likes, comments, shares and saves to compare reach.
- **Links that keep working.** Media links are signed CDN links that expire (see `video.cdn_url_expired`). The `*_stable` links (`video.play_url_stable`, `video.download_url_stable`, `video.bit_rate[].url_stable`, `video.bit_rate_audio[].url_stable`) redirect to a fresh copy of the same file, so store those.
- **Qualities.** `dash` entries in `video.bit_rate[]` are video-only tracks; `mp4` entries and `video_play_addr` include sound.
- **Products.** `products[]` lists the shopping cards (小黄车) attached to a video, with title, sales, shop and category. Prices are not part of Douyin's public web data.
- **Location.** `poi.poi_id` and `poi.poi_name` are filled when Douyin includes the location in the post.
- **Photo posts** have `post_type: "images"`, the pictures in `images[]` and no video links; their background music is in `music.play_url`.
- **Data is in Chinese**, exactly as Douyin shows it.
- **Public data only.** The actor collects what anyone can see on douyin.com without an account.

### Integrations and API

- **API:** start runs and download results with the [Apify API](https://docs.apify.com/api/v2) or the Apify clients for Python and JavaScript.
- **Schedules:** run the actor every hour, day or week and keep the numbers fresh.
- **Integrations:** send results to Google Sheets, Slack, Make, Zapier, webhooks and other tools supported by Apify.

### FAQ

**Do I need a Douyin account or proxies?**
No. The actor does not log in and uses its own proxies.

**Which language should I search in?**
Chinese keywords give the best matches, as on Douyin itself. English and brand names work too.

**Is the output the same as Douyin Video Scraper?**
Yes. Rows have the same fields, plus `keyword` and `search_rank`.

**Do I pay for videos that were not collected?**
No. Only rows with data are charged.

# Actor input Schema

## `keywords` (type: `array`):

What to search for on Douyin, one keyword or phrase per line. Chinese keywords match best (e.g. 猫咪, 露营装备).

## `maxResults` (type: `integer`):

Stop after this many videos for each keyword. Douyin shows about 100-160 videos for a keyword.

## Actor input object example

```json
{
  "keywords": [
    "猫咪"
  ],
  "maxResults": 20
}
```

# Actor output Schema

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

One row per video or photo post found for each keyword, in Douyin's order: rank, statistics, author, music and MP4 links.

# 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 = {
    "keywords": [
        "猫咪"
    ],
    "maxResults": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("theshark/douyin-search-scraper").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 = {
    "keywords": ["猫咪"],
    "maxResults": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("theshark/douyin-search-scraper").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 '{
  "keywords": [
    "猫咪"
  ],
  "maxResults": 20
}' |
apify call theshark/douyin-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,theshark/douyin-search-scraper"
        }
    }
}
```

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/y3xMf3jpzoBLh1Gv4/builds/npt1m6dZvw71ju3I6/openapi.json
