# Piaofang Maoyan — 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.

> Track real-time movie box office performance, search films and shows, and monitor streaming popularity rankings across China's entertainment market. Discover theater rankings, upcoming release schedules, and movie showtimes to stay updated on cinema trends and audience engagement metrics.

**Category:** Entertainment | **Website:** [piaofang.maoyan.com/](https://piaofang.maoyan.com/) | **Docs:** [parse.bot/marketplace/37868c3b-bfde-4e52-8f28-62da00721583/piaofang-maoyan-com-api](https://parse.bot/marketplace/37868c3b-bfde-4e52-8f28-62da00721583/piaofang-maoyan-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/piaofang-maoyan/`
**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 alltime box office rankings

Returns the all-time China box office total rankings (影片票房总榜), listing the highest-grossing movies of all time in mainland China. Results ordered by total box office descending. No pagination — returns top 20.

**Estimated cost:** Metered

_No parameters required._

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

### Get movie scheduling

Returns today's national movie scheduling data (排片), showing the number of screenings and percentage share for each movie currently in theaters. Ordered by screening count descending.

**Estimated cost:** Metered

_No parameters required._

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

### Get online streaming heat rankings

Returns the ranked list of online streaming shows by heat score, including platform and play count information. Covers major Chinese streaming platforms (Tencent Video, iQiyi, Youku, Mango TV, etc.). No pagination — full ranking returned.

**Estimated cost:** Metered

_No parameters required._

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

### Get realtime box office

Returns historical single-day box office record rankings for the China national market. Each record represents one of the highest-grossing single days in history, ordered by revenue descending. No pagination — full list returned in one call.

**Estimated cost:** Metered

_No parameters required._

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

### Get release calendar

Returns the upcoming movie release calendar (上映日历) for China. Includes a calendar mapping dates to movie counts and detailed movie lists grouped by release date with film metadata (title, genre, director, stars, wishlist count).

**Estimated cost:** Metered

_No parameters required._

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

### Get theater rankings

Returns today's theater (cinema) box office rankings, listing individual theaters/cinemas across China ordered by daily revenue. Includes ticket price averages and viewer statistics.

**Estimated cost:** Metered

_No parameters required._

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

### Search movies and shows

Search for movies and shows by keyword. Returns matching results with box office and cast information. Results depend on Maoyan's fuzzy matching algorithm — partial titles and character names work. Returns all matches in a single page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword — Chinese movie or show title, partial title, or actor/director name. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/piaofang-maoyan/search-movies-and-shows \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## 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.