# Top Baidu — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access real-time trending search data from Baidu's Top platform. Retrieve ranked hot search terms, novels, movies, and TV dramas, with support for genre and category filtering across all board tabs.

**Category:** News & Media | **Website:** [top.baidu.com/](https://top.baidu.com/) | **Docs:** [parse.bot/marketplace/edf60d0d-bac9-4dce-9908-b09a79a50857/top-baidu-com-api](https://parse.bot/marketplace/edf60d0d-bac9-4dce-9908-b09a79a50857/top-baidu-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/top-baidu/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get board by tab

General-purpose endpoint to retrieve any board tab (realtime, novel, movie, teleplay) with optional tag filtering. Returns ranked items and available filter tags.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tab` | string | Yes | Board tab name: realtime, novel, movie, teleplay. |
| `tag` | string | No | Optional category/genre filter tag. Available tags are returned in the tags_available field of any board response. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/top-baidu/get-board-by-tab \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tab":"<string>","tag":"<string>"}'
```

### Get homepage summary

Fetch the main home/board overview page summary with cloud trending topics and top items for all categories (realtime, novel, movie, teleplay). Each card contains a preview of that board's top items. The cloud array contains trending keywords with hotScores.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/top-baidu/get-homepage-summary \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get movie rankings

Fetch the hot movie rankings from the Baidu Top board. Returns ranked movies with scores and available filter tags for genre and region.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/top-baidu/get-movie-rankings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get novel rankings

Fetch the hot novel rankings from the Baidu Top board. Returns all novels currently ranked with their scores, along with available genre filter tags that can be used with get_novel_rankings_by_genre or get_board_by_tab.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/top-baidu/get-novel-rankings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get novel rankings by genre

Fetch novel rankings filtered by genre type. Returns novels matching the specified genre along with available tags. Equivalent to get_board_by_tab with tab=novel and the genre as tag.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `genre` | string | Yes | Novel genre filter. Available genres can be discovered from the tags_available field of get_novel_rankings. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/top-baidu/get-novel-rankings-by-genre \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"genre":"<string>"}'
```

### Get realtime hot search

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.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/top-baidu/get-realtime-hot-search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get search results for keyword

Construct a Baidu search URL for a specific hot search keyword to view related news and discussions. Does not fetch search results; only builds and returns the URL.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `keyword` | string | Yes | The trending keyword to generate a Baidu search URL for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/top-baidu/get-search-results-for-keyword \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"<string>"}'
```

### Get tv drama rankings

Fetch the hot TV drama rankings from the Baidu Top board. Returns ranked TV dramas with scores and available filter tags for genre and region.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/top-baidu/get-tv-drama-rankings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.