# Dianying Taobao — 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.

> Search for movies currently playing on Taobao's movie platform and discover nearby cinemas showing your chosen film with available showtimes in your city on your preferred date. Get real-time access to movie listings and cinema schedules to easily plan your movie outing.

**Category:** Entertainment | **Website:** [dianying.taobao.com/](https://dianying.taobao.com/) | **Docs:** [parse.bot/marketplace/49c851d4-3f83-4fa3-8744-6ec463fd3e08/dianying-taobao-com-api](https://parse.bot/marketplace/49c851d4-3f83-4fa3-8744-6ec463fd3e08/dianying-taobao-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/dianying-taobao/`
**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 cinemas by movie

Get the list of cinemas showing a specific movie in a given city on a given date. Returns cinema names and IDs for all cinemas, with the address available for the first listed cinema. Showtimes may be empty when not pre-loaded in the upstream response. Makes 2-3 requests internally: a page navigation to establish session trust, a city code lookup, and the cinema schedule request.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | Yes | Chinese city name (e.g. '上海', '温州'). Must match a city in the Taopiaopiao supported city list. |
| `date` | string | Yes | Date in YYYY-MM-DD format for which to check cinema schedules. |
| `movie_id` | string | Yes | Movie ID from search_movies results (e.g. '1525003'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/dianying-taobao/get-cinemas-by-movie \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","date":"<string>","movie_id":"<string>"}'
```

### Search movies

Search movies currently showing or upcoming on Taopiaopiao by keyword. Returns matching movies with their ID, name, showing status, and release date when available. The movie list is nationwide; the city parameter is accepted for context but does not filter which movies are returned. Release dates are available for upcoming movies but may be absent for currently-showing movies whose release date has already passed.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | Chinese city name (e.g. '温州', '上海'). Accepted for context but does not filter the movie results since movies are nationwide. |
| `keyword` | string | Yes | Search keyword to match against movie names (e.g. '八仙'). Case-insensitive substring match. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/dianying-taobao/search-movies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","keyword":"<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.