Maoyan APIpiaofang.maoyan.com ↗
Access China box office rankings, streaming heat scores, theater revenue, movie scheduling, and release calendars from Maoyan Piaofang via 7 structured endpoints.
What is the Maoyan API?
The Maoyan Piaofang API exposes 7 endpoints covering China's film and streaming market, including all-time box office totals, real-time scheduling share, theater-level daily revenue, and online streaming heat rankings. The get_alltime_box_office_rankings endpoint returns each film's boxInfo, movieId, movieName, and releaseInfo, while get_theater_rankings breaks down individual cinemas by ticket price, viewer count, and screening average.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/9a941e3a-e0c9-4d10-9e95-29e709fcaea5/get_realtime_box_office' \ -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 piaofang-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.
"""Maoyan Pro API — China box office, streaming, and theater intelligence."""
from parse_apis.maoyan_pro_api import MaoyanPro, MovieNotFound
client = MaoyanPro()
# All-time box office rankings — top grossing films in China history
for movie in client.movies.list_rankings(limit=5):
print(movie.movie_name, movie.box_info, movie.release_info)
# Search for movies by keyword and inspect first result
result = client.moviesearchresults.search(query="哪吒", limit=1).first()
if result:
print(result.title, result.box_office, result.release_date)
# Streaming heat rankings — hottest online shows right now
for show in client.streamingshows.list(limit=3):
print(show.series_info.name, show.series_info.platform_desc, show.curr_heat)
# Today's scheduling distribution across cinemas
for sched in client.movieschedules.list(limit=3):
print(sched.movie_name, sched.count, sched.count_rate)
# Theater revenue rankings
try:
theater = client.theaters.list_rankings(limit=1).first()
if theater:
print(theater.name, theater.box_desc, theater.view_count_desc)
except MovieNotFound as exc:
print(f"not found: {exc}")
# Upcoming release calendar
cal = client.releasecalendars.get()
print(cal.release_info.location, len(cal.release_info.calendars), "release dates tracked")
print("exercised: movies.list_rankings / moviesearchresults.search / streamingshows.list / movieschedules.list / theaters.list_rankings / releasecalendars.get")
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.
No input parameters required.
{
"type": "object",
"fields": {
"items": "array of box office record objects with date and revenue"
},
"sample": {
"data": {
"items": [
{
"date": "2025年01月29日",
"boxDesc": "18.08亿"
},
{
"date": "2021年02月12日",
"boxDesc": "16.93亿"
}
]
},
"status": "success"
}
}About the Maoyan API
Box Office and Scheduling Data
Two endpoints target theatrical performance directly. get_alltime_box_office_rankings returns the all-time China box office total rankings with fields like boxInfo (e.g. '154.46亿'), movieId, movieName, and releaseInfo. get_realtime_box_office returns historical single-day market records, each entry carrying a date and a boxDesc revenue string. For daily scheduling, get_movie_scheduling lists every current title's screening count, countRate (percentage share of total screenings), and movieId.
Theater and Release Intelligence
get_theater_rankings surfaces individual cinemas ranked by daily revenue, with boxDesc, viewCountDesc, avgViewBoxDesc (average ticket price), and avgShowViewDesc (average viewers per screening) — useful for tracking geographic performance concentration. get_release_calendar returns the upcoming release calendar as two structured objects: releaseInfo maps dates to movie counts, and releaseList groups detailed film records by release date.
Streaming and Search
get_online_streaming_heat_rankings returns online shows ranked by currHeat score, with each entry's seriesInfo object carrying name, platformDesc, releaseInfo, and seriesId. For discovery, search_movies_and_shows accepts a query string (Chinese title or partial title) and returns matching results including title, cast, director, box_office, and release_date. Results follow Maoyan's own fuzzy matching logic.
The Maoyan API is a managed, monitored endpoint for piaofang.maoyan.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when piaofang.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 piaofang.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?+
- Track which films currently hold the largest share of national screening slots using
countRatefromget_movie_scheduling - Build an all-time China box office leaderboard with
boxInfoandmovieNamefromget_alltime_box_office_rankings - Monitor online streaming competition by comparing
currHeatscores andplatformDescacross shows - Identify top-performing cinemas by daily revenue, average ticket price, and viewers-per-screening from
get_theater_rankings - Plan release-window analysis by pulling upcoming titles and their dates from
get_release_calendar - Search a film by partial Chinese title and retrieve its box office total and cast via
search_movies_and_shows - Record historical single-day market peaks using the
dateandboxDescfields fromget_realtime_box_office
| 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.
Does Maoyan Piaofang have an official developer API?+
What does `get_theater_rankings` return and how granular is it?+
get_theater_rankings returns individual cinema entries with name, boxDesc (daily revenue in 万), viewCountDesc (total viewers), avgViewBoxDesc (average ticket price), and avgShowViewDesc (average viewers per screening). It covers today's rankings nationally but does not break down performance by individual film within each theater.Does the API return per-movie daily box office trends over time?+
get_alltime_box_office_rankings, single-day market records via get_realtime_box_office, and today's scheduling share via get_movie_scheduling, but does not expose a time-series of daily revenue per individual film. You can fork this API on Parse and revise it to add an endpoint targeting per-film daily performance data.How does `search_movies_and_shows` handle queries, and what happens if a title has no box office data?+
query string (Chinese title or partial title) and applies Maoyan's own fuzzy matching. When a result has no recorded box office, the box_office field returns the string '暂无票房数据' rather than null, so callers should check for that sentinel value rather than treating the field as numeric.