# 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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-piaofang-maoyan-com-api-37868c3b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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/parse-piaofang-maoyan-com-api-37868c3b/get_alltime_box_office_rankings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-piaofang-maoyan-com-api-37868c3b/get_movie_scheduling \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-piaofang-maoyan-com-api-37868c3b/get_online_streaming_heat_rankings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-piaofang-maoyan-com-api-37868c3b/get_realtime_box_office \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-piaofang-maoyan-com-api-37868c3b/get_release_calendar \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-piaofang-maoyan-com-api-37868c3b/get_theater_rankings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-piaofang-maoyan-com-api-37868c3b/search_movies_and_shows \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```