# Maoyan (maoyan.com) — 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.

> Find and browse now-showing and coming-soon movies with detailed information, then discover nearby cinemas and filter them by location and amenities. Get comprehensive movie details and search through Chinese movie theaters to plan your movie outings.

**Category:** Entertainment | **Website:** [www.maoyan.com/](https://www.maoyan.com/) | **Docs:** [parse.bot/marketplace/f07ec959-591a-4321-8d42-cdbcd711fdb0/maoyan-com-api](https://parse.bot/marketplace/f07ec959-591a-4321-8d42-cdbcd711fdb0/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-maoyan-com-api-f07ec959/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_cinema_filters

Retrieve available filter options for cinema search. Returns districts, brands, hall types, services, subway lines, and time ranges for a given movie and city. Use the returned district IDs with list_cinemas to narrow results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_id` | string | No | City ID. |
| `day` | string | No | Date in YYYY-MM-DD format. Omitting defaults to today. |
| `movie_id` | string | Yes | Movie ID to get filters for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maoyan-com-api-f07ec959/get_cinema_filters \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city_id":"<string>","day":"<string>","movie_id":"<string>"}'
```

### get_movie_detail

Fetch full details for a single movie by ID. Returns description, cast, score distribution, photos, trailer video URL, duration, category, director, and release metadata. The movie_id is obtained from list_movies results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `movie_id` | string | Yes | Movie ID from list_movies results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maoyan-com-api-f07ec959/get_movie_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"movie_id":"<string>"}'
```

### list_cinemas

List cinemas showing a specific movie in a given city. Returns cinema names, addresses, ticket prices, and service tags. The upstream API returns a maximum of 20 cinemas per offset page. Use district_id from get_cinema_filters to narrow results by district.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_id` | string | No | City ID (e.g. 1 for Beijing, 59 for Chengdu). |
| `day` | string | No | Date in YYYY-MM-DD format. Omitting defaults to today. |
| `district_id` | string | No | District ID from get_cinema_filters (-1 for all districts). |
| `limit` | integer | No | Number of cinemas per page (max 20). |
| `movie_id` | string | Yes | Movie ID to find cinemas for. |
| `offset` | integer | No | Pagination offset. Each page returns up to 20 cinemas. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maoyan-com-api-f07ec959/list_cinemas \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city_id":"<string>","day":"<string>","district_id":"<string>","limit":"<integer>","movie_id":"<string>","offset":"<integer>"}'
```

### list_movies

List movies currently showing in theaters or coming soon. Returns movie summaries with name, score, stars, release date, poster, and showing info. Now-showing (show_type=NOW_SHOWING) supports offset-based pagination in batches of up to 12. Coming-soon (show_type=COMING_SOON) returns upcoming movies up to the limit. Each MovieSummary exposes a .details() navigation to the full Movie resource.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_id` | string | No | City ID (e.g. 1 for Beijing, 59 for Chengdu). |
| `limit` | integer | No | Maximum number of movies to return. |
| `offset` | integer | No | Pagination offset for now-showing movies (applies to show_type=1 only). Each page returns up to 12 movies. |
| `show_type` | string | No | Show type filter. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-maoyan-com-api-f07ec959/list_movies \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city_id":"<string>","limit":"<integer>","offset":"<integer>","show_type":"<string>"}'
```