# Douyin (/docs/douyin)

Scrape public Douyin (抖音) videos, creators, comments and trending topics

Douyin (抖音) is ByteDance's mainland-China app. It is a **different network from
TikTok**: different creators, a different catalogue and different trending
topics. A video you find here will not be on TikTok, and vice versa.

Base URL: `/v1/douyin/...`

## Getting started

### 1. Search for videos

```bash title="Keyword search"
curl "https://www.socialcrawl.dev/v1/douyin/search?query=美食&limit=5" \
  -H "x-api-key: YOUR_API_KEY"
```

Chinese, English and mixed queries all work, but Chinese keywords return a far
deeper result set because that is what the captions and hashtags are written in.

### 2. Resolve the creator behind a video

Search rows carry `post.ext.author_id`, and every row's `post.author` block
names the creator. To get their full record, pass their profile URL or bare
`sec_uid`:

```bash title="Creator profile"
curl "https://www.socialcrawl.dev/v1/douyin/profile?url=https://www.douyin.com/user/MS4wLjABAAAAtxsy7VmVkU3RN9oIX0vdkh_6-LlQAb0gwI-tDf-bYNg" \
  -H "x-api-key: YOUR_API_KEY"
```

This endpoint fetches no videos, which makes it the cheapest Douyin call and the
right one to poll on a schedule for follower tracking.

### 3. Read a comment thread

Comments come back top-level only. To open one conversation, take the `id` of a
comment whose `engagement.replies` is greater than zero and pass it to the
replies endpoint:

```bash title="Comments, then one thread"
curl "https://www.socialcrawl.dev/v1/douyin/post/comments?url=https://www.douyin.com/video/7681266289940544369&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://www.socialcrawl.dev/v1/douyin/comment/replies?url=https://www.douyin.com/video/7681266289940544369&comment_id=7682735175344833317" \
  -H "x-api-key: YOUR_API_KEY"
```

Every reply carries `comment.parent_id` set to the comment you asked about, so a
thread reassembles exactly rather than by guesswork.

## Douyin-specific behaviour

Four things about this platform differ from the rest of the catalogue. Each one
is a property of Douyin itself, not of how SocialCrawl reads it.

### `engagement.views` is always null

Douyin does not publish play counts anywhere outside its own app. Every source
returns zero for that field on every surface, including single-video lookups, so
returning `null` is the honest answer: a `0` would read as a video nobody
watched. `likes`, `comments`, `shares` and `saves` are all real numbers and are
what you should rank and track on.

### Creators are identified by `sec_uid`, not by a handle

A Douyin creator is addressed by `sec_uid`, the opaque `MS4wLjAB...` string in
their profile URL, or by their numeric user ID. Douyin auto-assigns a numeric
"Douyin ID" to anyone who never picks one, and a number is not a handle you could
mention, so `author.username` is often `null`. Join on `author.id`, which is
always present.

### Search always returns something

Douyin's ranker falls back to loosely related videos rather than reporting no
match, so a nonsense query still returns rows and still bills for them. Read the
captions rather than treating a non-empty list as proof of coverage. The
single-video and profile endpoints do **not** behave this way: an unknown video
ID or `sec_uid` returns not-found and refunds.

### The hot-search board is the whole board

`GET /v1/douyin/trending` returns 抖音热搜, the live ranked list of what mainland
China is searching right now. It takes no parameters and no `limit`: the upstream
ignores any row cap, so the endpoint charges one flat price and returns the
complete ranking rather than advertising a bound it cannot enforce.

```bash title="Hot-search board"
curl "https://www.socialcrawl.dev/v1/douyin/trending" \
  -H "x-api-key: YOUR_API_KEY"
```

Topics come back in Chinese, exactly as Douyin publishes them, with no lossy
translation applied.

## Endpoints

## Notes

- All endpoints use `GET` with query parameters
- Authentication via the `x-api-key` header
- No Chinese account, cookie or VPN is required
- Responses follow the unified SocialCrawl schema
- Metered endpoints charge only for rows actually returned