Maoyan APImaoyan.com ↗
Access Maoyan movie data via API: now-showing and coming-soon listings, detailed movie info, cinema availability, and filter options for Chinese theaters.
What is the Maoyan API?
This API exposes 4 endpoints covering Maoyan's Chinese movie ecosystem, returning now-showing and coming-soon film listings, full movie details, and cinema availability data. The list_movies endpoint alone returns up to 12 fields per movie object including score, cast, poster URL, release date, and show info. Together, the endpoints let you query across cities, filter cinemas by district, and retrieve trailers and photo galleries for specific titles.
curl -X GET 'https://api.parse.bot/scraper/e9bfd954-21ee-4c0c-8ba9-f8fe2c8276d5/list_movies?limit=5&offset=0&city_id=1&show_type=1' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace maoyan-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Maoyan Movie SDK — browse movies, drill into details, find cinemas."""
from parse_apis.maoyan_movie_api import Maoyan, ShowType, MovieNotFound
client = Maoyan()
# List now-showing movies in Beijing; limit caps total items fetched.
for movie in client.moviesummaries.list(show_type=ShowType.NOW_SHOWING, city_id="1", limit=5):
print(movie.name, movie.score, movie.release_date)
# Drill into one movie's full details via .first() then navigation.
summary = client.moviesummaries.list(show_type=ShowType.COMING_SOON, limit=1).first()
if summary:
detail = summary.details()
print(detail.name, detail.director, detail.duration, detail.category)
# Fetch a movie directly by ID and explore its sub-resources.
movie = client.movies.get(id="1516982")
print(movie.name, movie.score, movie.watched_count)
# List cinemas showing this movie, capped at 3.
for cinema in movie.cinemas.list(city_id="1", limit=3):
print(cinema.name, cinema.address, cinema.sell_price)
# Get filter options (districts, brands, hall types) for cinema search.
filters = movie.filters.get(city_id="1")
if filters.district:
for opt in filters.district.options[:3]:
print(opt.name, opt.count)
# Typed error handling for a non-existent movie.
try:
client.movies.get(id="9999999999")
except MovieNotFound as exc:
print(f"Movie not found: {exc.movie_id}")
print("exercised: moviesummaries.list / details / movies.get / cinemas.list / filters.get")
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.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of movies to return. |
| offset | integer | Pagination offset for now-showing movies (applies to show_type=1 only). Each page returns up to 12 movies. |
| city_id | string | City ID (e.g. 1 for Beijing, 59 for Chengdu). |
| show_type | string | Show type filter. |
{
"type": "object",
"fields": {
"count": "integer number of movies returned in this response",
"total": "integer total number of movies available",
"movies": "array of movie summary objects with id, name, poster, score, wish_count, stars, release_date, show_info",
"offset": "integer current offset (now_showing only)",
"movie_ids": "array of all movie IDs (now_showing only)",
"show_type": "string indicating 'now_showing' or 'coming_soon'"
}
}About the Maoyan API
Movie Listings
The list_movies endpoint returns paginated movie data for either now-showing (show_type=1) or coming-soon (show_type=2) films. Each movie object includes id, name, poster, score, stars, release_date, and show_info. Results can be scoped to a specific city using city_id (e.g. 1 for Beijing, 59 for Chengdu). For now-showing titles, the response also includes a movie_ids array covering all available film IDs in the city. Pagination is controlled via offset and limit, with up to 12 results per page for now-showing queries.
Movie Details
get_movie_detail accepts a movie_id from list results and returns an expanded record: director, category (genre tags), duration in minutes, wish_count, video_url for the trailer, and a photos array of image URLs. Score and cast fields (stars) are also present, giving enough data to build a full movie profile page without additional requests.
Cinema Listings and Filters
list_cinemas returns up to 20 cinemas per request showing a given movie_id in a city. Each cinema object includes name, address, sell_price, distance, allow_refund, has_snack, vip_tag, and show_times. Use district_id — obtained from get_cinema_filters — to narrow results to a specific urban district. Pagination via offset is supported, though the upstream source caps results at 20 per page.
get_cinema_filters provides the full set of filterable dimensions for a movie/city combination: brand, district, hallType, service, subway, and timeRanges. Each filter category carries a name and an options array, which feeds directly into district_id values for list_cinemas.
The Maoyan API is a managed, monitored endpoint for maoyan.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when maoyan.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official maoyan.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a city-specific now-showing listings page using list_movies with city_id and show_type=1
- Display a movie detail page with trailer, cast, director, genre, and photo gallery from get_movie_detail
- Find cinemas near a district screening a given film using list_cinemas with district_id from get_cinema_filters
- Track wish_count across coming-soon titles over time to gauge pre-release audience interest
- Aggregate sell_price data from list_cinemas to compare ticket pricing across theaters in a city
- Surface refund policy and snack availability per cinema using allow_refund and has_snack fields
- Populate a movie search UI with poster images, scores, and release dates from list_movies
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.