Baidu APItop.baidu.com ↗
Fetch real-time hot search rankings, novel, movie, and TV drama charts from Baidu Top. 8 endpoints, genre filtering, hot scores, and cloud trending words.
What is the Baidu API?
The Baidu Top API exposes 8 endpoints covering real-time hot search rankings, novel charts, movie rankings, and TV drama boards from top.baidu.com. Each response includes per-item fields like hot_score, hot_change, labels, and rank, plus tags_available for genre and region filtering. The get_realtime_hot_search endpoint returns the current trending search terms with scores and metadata, while get_homepage_summary delivers a cross-category overview including cloud trending words.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/1c4f754a-689d-4bde-9ce0-8c483778c3f3/get_realtime_hot_search' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace top-baidu-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: BaiduTop SDK — bounded, re-runnable; every call capped."""
from parse_apis.baidu_hot_search_api import BaiduTop, BoardTab, InvalidGenre
client = BaiduTop()
# List real-time trending searches directly from the boards collection
for item in client.boards.list_realtime(limit=5):
print(item.rank, item.title, item.hot_score)
# Fetch a specific board by tab using the enum, then drill into items
novel_board = client.boards.get(tab=BoardTab.NOVEL)
for item in novel_board.list_items(tag="xuanhuan", limit=3):
print(item.title, item.hot_score, item.description)
# Filter novels by genre via collection-level convenience method
for novel in client.boards.list_novels_by_genre(genre="xuanhuan", limit=3):
print(novel.rank, novel.title, novel.hot_score)
# Fetch the homepage summary — trending cloud words and category cards
homepage = client.homepages.get()
for card in homepage.cards[:2]:
print(card.title, card.type)
for word in homepage.cloud[:3]:
print(word.word, word.hot_score, word.word_type)
# Build a search URL for a trending keyword
search = client.searchurls.get(keyword="Python")
print(search.keyword, search.search_url)
# Typed error handling
try:
for item in client.boards.list_novels_by_genre(genre="", limit=1):
print(item.title)
except InvalidGenre as exc:
print(f"Invalid genre: {exc}")
print("exercised: boards.list_realtime / boards.get / list_items / list_novels_by_genre / homepages.get / searchurls.get")
Fetch the real-time hot search rankings from the Baidu Top board. Returns the current top trending search terms with scores and metadata. Items are ordered by descending hot_score. No filtering is available; the full ranked list is returned in a single page.
No input parameters required.
{
"type": "object",
"fields": {
"items": "array of ranked trending search objects",
"update_time": "string or null, Unix timestamp of last update"
},
"sample": {
"data": {
"items": [
{
"url": "https://www.baidu.com/s?wd=example",
"rank": 1,
"image": "https://fyb-2.cdn.bcebos.com/hotboard_image/example.jpg",
"query": "Example trending topic",
"title": "Example trending topic",
"labels": [],
"raw_url": "https://www.baidu.com/s?wd=example",
"hot_score": 7809369,
"hot_change": "same",
"description": "Description of the trending topic"
}
],
"update_time": null
},
"status": "success"
}
}About the Baidu API
Trending Search and Rankings Coverage
The get_realtime_hot_search endpoint returns the current 热搜榜 (hot search board) as an array of ranked items. Each item carries rank, title, query, hot_score, hot_change, description, labels, image, and both url and raw_url fields. The update_time field is a Unix timestamp string indicating when the board was last refreshed, or null if unavailable. No input parameters are required — the endpoint always returns the live snapshot.
Content-Specific Boards with Tag Filtering
Three dedicated endpoints — get_novel_rankings, get_movie_rankings, and get_tv_drama_rankings — mirror the structure of the hot search board but scope results to their respective content types. All three return a tags_available array of tag group objects (each with typeName, text, content, and curIndex), which expose the available genre and region filters for that board. The get_board_by_tab endpoint generalises this: pass a tab parameter (realtime, novel, movie, or teleplay) and an optional tag string (e.g. 都市, 玄幻, 爱情, 喜剧) to retrieve any board with filtering applied in a single call. The get_novel_rankings_by_genre endpoint further specialises this for novels, accepting a genre string and returning filtered novel items alongside tags_available.
Homepage Summary and Cloud Trending Topics
The get_homepage_summary endpoint returns a cards array covering all category boards, each with a title, type, and nested items and optional top_items arrays. It also returns a cloud array of trending word objects, each containing word, hotScore, wordType, and url. This endpoint is suited for dashboards that need a cross-category snapshot in a single request.
URL Construction Utility
The get_search_results_for_keyword endpoint does not return search results. It accepts a keyword string and returns the corresponding Baidu search URL (search_url). This is useful for building links that redirect users to live Baidu search pages for any trending term surfaced by the other endpoints.
The Baidu API is a managed, monitored endpoint for top.baidu.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when top.baidu.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official top.baidu.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track daily shifts in Chinese public interest by monitoring
hot_scoreandhot_changefields fromget_realtime_hot_search. - Build a content recommendation dashboard that aggregates top novels, movies, and TV dramas using the three dedicated ranking endpoints.
- Filter novel rankings by genre (e.g. 玄幻 or 现代言情) using
get_novel_rankings_by_genreto identify trending titles in a specific category. - Populate a trending-topics widget using the
cloudarray fromget_homepage_summary, which exposesword,hotScore, andwordTypefor each cloud term. - Generate direct Baidu search deep-links for trending keywords using
get_search_results_for_keywordto route users to live news and discussions. - Monitor entertainment trends in the Chinese market by comparing
hot_scorevalues across movie and TV drama boards over time. - Discover available genre and region filters for any board tab without a separate metadata call by reading
tags_availablefrom any ranking endpoint response.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Baidu Top have an official developer API?+
What does `hot_change` represent in ranking responses?+
hot_change field appears on every ranked item across all board endpoints and indicates the directional movement of a term or title in the rankings — for example, whether it has risen, fallen, or is newly entered. The exact numeric or categorical value reflects what Baidu Top reports for that item at the time of the snapshot.Does the API support historical or time-series ranking data?+
Can the API filter movies by region (e.g. Chinese vs. foreign films)?+
get_movie_rankings endpoint returns a tags_available array that includes region-based tag groups alongside genre tags, exposing what filters Baidu Top supports. However, applying a specific region filter requires using get_board_by_tab with the tab set to movie and passing the relevant tag string. If the region tag you need is not listed in tags_available, it is not currently exposed. You can fork this API on Parse and revise it to surface additional tag-filtering combinations.