# Weibo (/docs/weibo)

Read public Weibo accounts, posts, comments, search results and the hot-search list as structured JSON

Weibo is China's largest public microblog. These endpoints return accounts, posts, comments, replies, keyword search and the live hot-search list (热搜) in the same `Author`, `Post` and `Comment` shapes as every other platform, with the province or country each post and comment came from.

Base URL: `/v1/weibo/...`

Weibo exposes 8 routes here. Account routes take exactly one of `handle`, `id` or `url`, and post routes take a Weibo post link.

  Search is not a census. `/v1/weibo/search` returns the posts Weibo's own search shows for a term, so a search can miss posts that exist. Chinese terms match far more posts than English ones, so search in Chinese for Chinese topics.

## Quickstart

### Look up an account

Use the account's numeric `id`, its custom `handle`, or a profile `url`. This returns exact follower, following and post counts.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/weibo/profile?id=2803301701" \
  -H "x-api-key: YOUR_API_KEY"
```

### List its posts

Posts come newest first, up to 50 a page. Pass the returned `cursor` for older posts, back through roughly the newest 2,000.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/weibo/profile/posts?id=2803301701&limit=50" \
  -H "x-api-key: YOUR_API_KEY"
```

### Read the comments on a post

Sort by `hot` (most liked first) or `latest`. Each comment carries the province it was posted from in `comment.ext.ip_location`.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/weibo/post/comments?url=https://weibo.com/2803301701/Rq0Gp5523&sort=hot" \
  -H "x-api-key: YOUR_API_KEY"
```

## Search a topic over time

`search` reads a keyword or a `#topic#`, newest first. `since` and `until` read a fixed period, back for years, and the `tab` parameter switches between `latest`, `all`, `original`, `verified`, `top`, `hot`, `videos`, `media` and `images`. The `latest`, `all`, `original` and `verified` tabs continue with the returned cursor. `top`, `hot` and `videos` are ranked and give one page per time window. `media` and `images` give one page and take no time window.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/weibo/search?query=%E5%8D%8E%E4%B8%BA&tab=latest&since=2024-01-01&until=2024-01-31" \
  -H "x-api-key: YOUR_API_KEY"
```

## All endpoints

## Platform notes

**Long posts are shortened in lists.** Post lists and search flag a shortened post with `post.ext.text_truncated`. `GET /v1/weibo/post` returns the full text and the read count.

**Follower counts are rounded in account search.** `author.followers` is null on `GET /v1/weibo/search/users`. Call `GET /v1/weibo/profile` for the exact figure.

**Very large comment threads stop at a few hundred comments.** That is Weibo's own limit. `GET /v1/weibo/comment/replies` reads the replies under one comment, using the `comment.id` from the comments route.

**Dates and time zones.** A date passed to `since` or `until` is read as that day in China time. An ISO 8601 date-time is read as given.

## Next steps

- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [Pagination](/docs/pagination.md): How cursors work across list endpoints.
- [Errors](/docs/errors.md): Status codes and what to do about each one.