# Weibo Hot Search Scraper (China Trending Topics API) (`praguedatalab/weibo-trends-scraper`) Actor

Weibo hot search (微博热搜) in one call: realtime, entertainment, news and hot-topic boards with rank, heat, category, label (hot/new/boom), ads flagged, topic link. Optional top posts from verified accounts. $4 per 1,000.

- **URL**: https://apify.com/praguedatalab/weibo-trends-scraper.md
- **Developed by:** [Prague Data Lab](https://apify.com/praguedatalab) (community)
- **Categories:** Social media, News, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 trending topics

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

## Weibo Hot Search Scraper (微博热搜 trending topics API)

**Get every Weibo hot-search board (realtime 热搜榜, entertainment 文娱榜, news 要闻榜) as clean rows (rank, topic, heat score, category, label such as new/hot/boom, first-seen time and topic link), plus the top posts of verified accounts for each trending topic. No login, no cookies to paste, $4 per 1,000 results.**

```json
{ "mode": "hotSearch", "maxItems": 60 }
```

One output row (realtime board, rank 1):

```json
{
    "type": "trend",
    "board": "realtime",
    "boardName": "热搜榜",
    "rank": 1,
    "word": "身披旭日旗中国留学生或被开除遣返",
    "heat": 1171091,
    "category": "民生新闻",
    "label": null,
    "isAd": false,
    "isPinned": false,
    "topicUrl": "https://s.weibo.com/weibo?q=%23%E8%BA%AB%E6%8A%AB%E6%97%AD%E6%97%A5%E6%97%97%E4%B8%AD%E5%9B%BD%E7%95%99%E5%AD%A6%E7%94%9F%E6%88%96%E8%A2%AB%E5%BC%80%E9%99%A4%E9%81%A3%E8%BF%94%23",
    "firstSeenAt": "2026-10-19T10:22:22.000Z",
    "minutesOnBoard": 176,
    "snapshotAt": "2026-10-19T13:18:01.174Z",
    "mode": "hotSearch"
}
```

### Compatible with the input of zhorex/weibo-scraper

Switching takes one change: the Actor ID. This Actor accepts the same input fields with the same values: `mode`, `searchQuery`, `userIds`, `postIds`, `maxResults`, `adFilter` (`all`, `organic_only`, `promo_only`), `deltaMode` and `deltaStateKey`. It also writes the same output field names next to its own (`title`, `hotValue`, `labelName`, `iconDesc`, `isHot`, `isNew`, `isPromoted`, `url`, `snapshotAt`, `firstSeenAt`, `status`, `rankDelta`, `previousRank`, `hotValueDelta`, `peakRank`, `peakHotValue`, `minutesOnBoard`; for posts `postId`, `mid`, `text`, `isTruncated`, `createdAtIso`, `repostsCount`, `commentsCount`, `attitudesCount`, `authorName`, `authorVerified`, `postUrl`).

| Leader mode | Here |
|---|---|
| `hot_search` | Same as `hotSearch`: every board, not only the realtime one. |
| `hot_search_delta` | Same as `hotSearch` with `deltaMode: true` (new / rising / falling / steady / dropped). |
| `search` | Posts for `searchQuery`, **from verified accounts only**, up to `maxResults` (Weibo shows anonymous visitors about 20 posts per query). |
| `hot_timeline` | Posts of Weibo's hot feed, **from verified accounts only**. |
| `post_comments`, `post_details`, `user_posts`, `user_profile`, `complaints` | Not offered. The run ends at once with a status message explaining why, and charges nothing. |

Two differences to know: ads are **dropped by default** (`adFilter: "drop"`; pass `"all"` to keep them flagged), and `createdAt` is ISO 8601 with Weibo's +08:00 offset (the same value as `createdAtIso`).

### What you get

| Board | Weibo name | Rows | Extra fields |
|---|---|---|---|
| `realtime` | 热搜榜 | the pinned topic + 50 topics | category, label, Weibo's own first-seen time, paid slot flagged |
| `entertainment` | 文娱榜 | 50 topics | category, label |
| `news` | 要闻榜 | 50 topics | label |

Everything comes from Weibo's public pages and their JSON endpoints, the same ones weibo.com shows to a visitor who is not signed in. A full snapshot of the three boards takes about 10 seconds.

### Use cases

- **Brands and agencies selling in China:** see within the hour when your brand, a competitor or a product category hits the hot search; track how long it stays and how high it climbs.
- **Media and newsrooms:** monitor what China talks about right now (news, entertainment, society), with the posts of official media accounts on each topic.
- **Analysts and researchers:** build an hourly time series of Chinese public attention (rank, heat, category) for sentiment, consumer-trend or political-communication studies.
- **AI agents:** one cheap call returns a structured, deduplicated snapshot of China's trending topics.

### Modes

#### `hotSearch` (default): trending topics

```json
{ "mode": "hotSearch", "boards": ["realtime", "entertainment", "news"], "maxItems": 60 }
```

`maxItems` keeps the top of every board first: 60 rows over 3 boards = the top 20 of each. Leave it empty to get everything (about 150 rows).

#### `topicPosts`: what verified accounts post about each trend

```json
{ "mode": "topicPosts", "topTrends": 5, "postsPerTopic": 10 }
```

Without `topics`, the Actor takes the current top 5 realtime trends. With `topics` (e.g. `["#李小冉离婚#", "新能源汽车"]`) it searches those. Each post row has the topic, text (full text of long posts), publish time, reposts, comments, likes, author name, verification type (`organization` = blue V, `individual` = verified public figure) and link. Set `authorFilter: "organizations"` to keep media, government and company accounts only.

Only verified accounts are returned, never posts of private individuals. Weibo shows anonymous visitors the first page of results of each search (about 20 posts, hot first); deeper pages need a login, so the Actor stops there.

#### `hot_timeline`: Weibo's hot feed

```json
{ "mode": "hot_timeline", "maxItems": 50 }
```

### Build a time series with an hourly schedule

The Actor returns snapshots. To build history, schedule it:

1. Create a task with `{ "mode": "hotSearch", "deltaMode": true, "deltaStateKey": "hourly" }`.
2. In Apify Console go to **Schedules → Create new**, cron `0 * * * *` (every hour), and add the task.
3. Every run stores a full snapshot stamped with `snapshotAt`. Collect the runs with an integration (Google Sheets, webhook, Make, Zapier) or the API (`GET /v2/actor-tasks/{taskId}/runs`, then each run's `defaultDatasetId` items), and group by `word` and `snapshotAt` to chart rank and heat over time.
4. With `deltaMode`, each row also says how it moved since the previous hour: `status` (`new`, `rising`, `falling`, `steady`, `dropped`), `previousRank`, `rankDelta`, `hotValueDelta`, `peakRank`, `peakHotValue`. The first run of a delta key is the baseline (every topic `new`). Use one `deltaStateKey` per schedule.

Cost of an hourly snapshot of the three boards: about 150 rows × $0.004 = $0.60 per run; the realtime board alone (`"boards": ["realtime"]`) is about $0.20 per run.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `hotSearch` | `hotSearch`, `topicPosts`, `hot_timeline`, or the leader's `hot_search`, `hot_search_delta`, `search`. |
| `boards` | array | all | `realtime`, `entertainment`, `news`. |
| `maxItems` | integer | everything | Maximum rows (charged events) in the run. `maxResults` is an alias. |
| `adFilter` | string | `drop` | `drop`, `keep`, `only` (or `organic_only`, `all`, `promo_only`). |
| `deltaMode` | boolean | `false` | Compare with the previous run (boards) or skip already delivered posts. |
| `deltaStateKey` | string | `default` | Name of the delta stream, stored in your key-value store `weibo-trends-state`. |
| `topics` | array | top trends | topicPosts: topics or keywords to search. |
| `topTrends` | integer | `5` | topicPosts without topics: how many current top trends. |
| `postsPerTopic` | integer | `10` | Maximum posts per topic (in `search` mode `maxResults` is used when this is empty). |
| `authorFilter` | string | `verified` | `verified` or `organizations`. |
| `fetchFullText` | boolean | `true` | Fetch the full text of long posts (no extra charge). |
| `searchQuery` | string | | Leader field: query for `search` mode. |
| `userIds`, `postIds` | array | | Leader fields, accepted; their modes are not offered. |
| `proxyConfiguration` | object | none | Optional Apify Proxy. Not needed today. |

### Output fields

| Field | Rows | Description |
|---|---|---|
| `type` | all | `trend` or `post` (also the charged event). |
| `mode` | all | Mode of the run as given in the input. |
| `board`, `boardName` | trend | `realtime` 热搜榜, `entertainment` 文娱榜, `news` 要闻榜. |
| `rank` | trend | Position on the board, 1 = top; `null` for the pinned topic, the paid slot and dropped topics. |
| `word`, `title` | trend | Topic text without `#` marks. |
| `note` | trend | Topic label as Weibo shows it. |
| `isHashtag` | trend | `true` for a `#hashtag#` topic page. |
| `heat`, `hotValue` | trend | Weibo heat score (热度). |
| `category`, `categories` | trend | Weibo category (民生新闻, 艺人, 剧集, 体育…), as text and as a list. |
| `label` | trend | `new`, `hot`, `boiling`, `boom`, `warm`, `recommended`, `sponsored`, `first`, `exclusive`, `other` or `null`. |
| `labelName`, `iconDesc` | trend | Badge as shown (新, 热, 沸, 爆…). |
| `isHot`, `isNew` | trend | Badge is 热/沸/爆, badge is 新. |
| `isAd`, `isPromoted`, `adType` | trend | Paid slot (with `adFilter` keep/only) and Weibo's ad type. |
| `isPinned` | trend | Topic pinned above the realtime board. |
| `topicUrl`, `url` | trend | Weibo search page of the topic. |
| `firstSeenAt`, `minutesOnBoard` | trend | When the topic entered the board (Weibo's own time on the realtime board) and minutes since. |
| `snapshotAt` | trend | Time of the snapshot (UTC). |
| `status`, `previousRank`, `rankDelta`, `hotValueDelta`, `peakRank`, `peakHotValue` | trend | `deltaMode` only: movement since the previous run. |
| `topic`, `topicBoard`, `topicRank` | post | Topic or query the post was found for, and where that topic ranked. |
| `postId`, `mid`, `bid` | post | Weibo post ID and short code. |
| `text`, `isTruncated` | post | Plain text; `isTruncated` when only the preview was available. |
| `createdAt`, `createdAtIso` | post | Publish time, ISO 8601 with +08:00. |
| `reposts`, `comments`, `likes` | post | Counts (also as `repostsCount`, `commentsCount`, `attitudesCount`). |
| `authorName`, `authorId`, `authorVerified`, `authorVerifiedType`, `authorVerifiedReason`, `authorFollowers` | post | Verified author: name, ID, `organization` or `individual`, verification text, followers. |
| `images` | post | Image URLs. |
| `postUrl` | post | Link to the post on weibo.com. |
| `scrapedAt` | all | Time of the run (UTC). |

### Pricing

Pay per result, nothing else: **$0.004 per trend row and $0.004 per post row ($4 per 1,000)**. No platform usage on top, no monthly fee. Rows removed by `adFilter` or `deltaMode` are not charged, and unsupported modes charge nothing. Set a maximum cost per run in Apify Console and the Actor stops cleanly when it is reached.

### Notes

- No login and no cookie from you: the Actor uses the anonymous visitor session Weibo gives to every browser.
- Weibo's own "topic board" (话题榜) API has not been updated since 2024, so it is left out.
- Times: `snapshotAt`, `firstSeenAt` and `scrapedAt` are UTC; post `createdAt` keeps Beijing time (+08:00).
- Questions or a missing field? Open an issue on the Actor page; we answer within 24 hours.

# Actor input Schema

## `mode` (type: `string`):

<b>hotSearch</b>: snapshot of the hot-search boards (one <code>trend</code> event per topic). <b>topicPosts</b>: top public posts of verified accounts for your topics, or for the current top trends (one <code>post</code> event per post). <b>hot_timeline</b>: posts of verified accounts from Weibo's hot feed. The leader's names <code>hot_search</code>, <code>hot_search_delta</code> and <code>search</code> work too; its other modes are answered with a status message and charge nothing.

## `boards` (type: `array`):

Hot-search boards to read in hotSearch mode: <b>realtime</b> (热搜榜, the main 50-topic board with category and first-seen time), <b>entertainment</b> (文娱榜) and <b>news</b> (要闻榜). All three by default.

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

Stop after this many rows in total (each row is one charged event). With several boards the top of every board is kept first: 60 rows over 3 boards = the top 20 of each. Leave empty for everything (about 150 topics, or 100 posts).

## `adFilter` (type: `string`):

Weibo sells one slot on the realtime board. <b>drop</b> (default) removes it before billing; <b>keep</b> returns it flagged <code>isAd: true</code>; <b>only</b> returns just the paid slots. The leader's values <code>organic_only</code>, <code>all</code> and <code>promo_only</code> work the same way.

## `deltaMode` (type: `boolean`):

hotSearch: tag every topic <code>new</code>, <code>rising</code>, <code>falling</code>, <code>steady</code> or <code>dropped</code> versus the previous run with the same delta key, with rank and heat changes and running peaks. topicPosts / hot_timeline: return only posts no earlier run delivered. The first run sets the baseline.

## `deltaStateKey` (type: `string`):

Name of an independent tracking stream for deltaMode (e.g. <code>hourly</code>, <code>brand-x</code>). State is kept in your key-value store <code>weibo-trends-state</code>.

## `topics` (type: `array`):

topicPosts mode: topics or keywords to search, e.g. <code>#李小冉离婚#</code> or <code>新能源汽车</code>. Leave empty to use the current top trends of the realtime board.

## `topTrends` (type: `integer`):

topicPosts mode without topics: how many of the current top realtime trends to fetch posts for.

## `postsPerTopic` (type: `integer`):

Maximum posts per topic (10 when empty; in <code>search</code> mode Maximum results is used instead). Weibo shows anonymous visitors about 20 posts per topic (hot first).

## `authorFilter` (type: `string`):

Posts are only taken from verified accounts, never from private individuals. <b>verified</b>: organisations (blue V: media, government, companies, schools) and verified public figures (orange V). <b>organizations</b>: blue V only.

## `fetchFullText` (type: `boolean`):

Weibo cuts long posts at about 140 characters in lists. When on, each cut post is fetched in full at no extra charge.

## `searchQuery` (type: `string`):

Leader field. In <code>search</code> / <code>topicPosts</code> mode it is searched like a topic (verified-account posts only).

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

Leader field, same meaning as <b>Maximum results</b>. Used when Maximum results is empty.

## `userIds` (type: `array`):

Leader field, accepted so its inputs validate. User-based modes are not offered; the run says so in its status message.

## `postIds` (type: `array`):

Leader field, accepted so its inputs validate. Post-based modes are not offered; the run says so in its status message.

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

Optional. Weibo answers datacenter IPs without a proxy today; enable Apify Proxy only if runs start failing.

## Actor input object example

```json
{
  "mode": "hotSearch",
  "boards": [
    "realtime",
    "entertainment",
    "news"
  ],
  "maxItems": 60,
  "adFilter": "drop",
  "deltaMode": false,
  "deltaStateKey": "default",
  "topTrends": 5,
  "postsPerTopic": 10,
  "authorFilter": "verified",
  "fetchFullText": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

No description

# 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 = {
    "mode": "hotSearch",
    "boards": [
        "realtime",
        "entertainment",
        "news"
    ],
    "maxItems": 60,
    "postsPerTopic": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("praguedatalab/weibo-trends-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 = {
    "mode": "hotSearch",
    "boards": [
        "realtime",
        "entertainment",
        "news",
    ],
    "maxItems": 60,
    "postsPerTopic": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("praguedatalab/weibo-trends-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 '{
  "mode": "hotSearch",
  "boards": [
    "realtime",
    "entertainment",
    "news"
  ],
  "maxItems": 60,
  "postsPerTopic": 10
}' |
apify call praguedatalab/weibo-trends-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,praguedatalab/weibo-trends-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/mQ1Z2EiRKmF5pz8OD/builds/NEdz23v8hsMo553bS/openapi.json