Box Office Mojo APIboxofficemojo.com ↗
Access Box Office Mojo data via API: movie gross totals, daily charts, all-time worldwide rankings, release schedules, and performance time-series.
What is the Box Office Mojo API?
The Box Office Mojo API exposes 6 endpoints covering movie search, detailed gross summaries, domestic daily charts, and all-time worldwide rankings. The get_movie_details endpoint returns domestic, international, and worldwide lifetime grosses alongside distributor, budget, MPAA rating, runtime, and market breakdowns by region. Whether you are tracking a film's opening weekend or comparing all-time earners, the endpoints chain together via shared identifiers like imdb_id and release_id.
curl -X GET 'https://api.parse.bot/scraper/19716ded-a751-4e1a-a385-4ee11fac2ab2/search_movies?query=Avatar' \ -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 boxofficemojo-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: Box Office Mojo SDK — search movies, explore charts, drill into performance."""
from parse_apis.box_office_mojo_api import BoxOfficeMojo, PerformanceType, MovieNotFound
client = BoxOfficeMojo()
# Search for movies by title and access typed fields.
for movie in client.moviesummaries.search(query="Avatar", limit=3):
print(movie.title, movie.imdb_id, movie.url)
# Drill into the first search result's full details.
result = client.moviesummaries.search(query="Inception", limit=1).first()
if result:
detail = result.details()
print(detail.title, detail.gross_summary)
# Get today's daily chart and inspect top entries.
for entry in client.charts.daily(limit=5):
print(entry.release_name, entry.daily, entry.theaters, entry.distributor)
# All-time worldwide rankings.
for record in client.charts.all_time_worldwide(limit=3):
print(record.title, record.worldwide_lifetime_gross, record.year)
# Fetch release performance using the PerformanceType enum.
top_entry = client.charts.daily(limit=1).first()
if top_entry:
try:
perf = client.releaseperformance(release_id=top_entry.release_id)
for day in perf.list(type=PerformanceType.DAILY, limit=3):
print(day.date, day.daily, day.rank)
except MovieNotFound as exc:
print(f"Release not found: {exc}")
# Upcoming releases schedule.
for upcoming in client.charts.upcoming(limit=3):
print(upcoming.title, upcoming.date, upcoming.scale)
print("exercised: search / details / daily chart / all_time_worldwide / release performance / upcoming schedule")
Full-text search for movies by title keyword. Returns a list of matching movies with their IMDb IDs and Box Office Mojo URLs. Results are ordered by relevance. No pagination — a single page of results is returned.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Movie title search query. |
{
"type": "object",
"fields": {
"results": "array of movie search result objects with title, imdb_id, url, and metadata"
},
"sample": {
"data": {
"results": [
{
"url": "https://www.boxofficemojo.com/title/tt0499549/?ref_=bo_se_r_1",
"title": "Avatar",
"imdb_id": "tt0499549",
"metadata": ""
},
{
"url": "https://www.boxofficemojo.com/title/tt1757678/?ref_=bo_se_r_2",
"title": "Avatar: Fire and Ash",
"imdb_id": "tt1757678",
"metadata": ""
}
]
},
"status": "success"
}
}About the Box Office Mojo API
Movie Search and Detail
Use search_movies with a query string to retrieve matching titles along with their imdb_id and Box Office Mojo URLs. Pass any imdb_id into get_movie_details to get the full financial picture: gross_summary breaks out domestic, international, and worldwide totals; summary includes domestic_distributor, budget, earliest_release_date, mpaa, running_time, and genres; and market_breakdowns maps individual regions to rows of performance data. The releases array within that response lists each release version (theatrical, re-release, etc.) with its own release_id.
Performance Time-Series
get_movie_release_performance accepts a release_id and an optional type parameter (daily, weekend, or weekly) to return a full time-series table. Each row in the performance array carries Date, DOW, Rank, Daily earnings, Theaters, Avg, To Date cumulative gross, and Day number in release. This lets you reconstruct a film's full theatrical run from opening day through the final weekend.
Charts and Rankings
get_daily_chart takes an optional date in YYYY-MM-DD format and returns the domestic daily chart for that date, or the most recent available if the parameter is omitted. Each row includes TD (rank), Release, Daily, Theaters, Avg, To Date, Days, Distributor, and a release_id you can pass directly to get_movie_release_performance. get_all_time_worldwide requires no inputs and returns the top-grossing films of all time with Worldwide Lifetime Gross, Domestic Lifetime Gross, Foreign Lifetime Gross, and percentage splits — each entry includes an imdb_id for further lookup.
Release Schedule
get_release_schedule returns upcoming theatrical releases ordered chronologically, with date, title, distributor, scale (Wide or Limited), and a release_id that becomes active once the film opens and chart data begins accumulating.
The Box Office Mojo API is a managed, monitored endpoint for boxofficemojo.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when boxofficemojo.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 boxofficemojo.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 film investment dashboard comparing
budgetagainstworldwidegross for wide-release titles. - Track a specific movie's opening-weekend velocity using
get_movie_release_performanceinweeklymode. - Monitor the domestic daily chart via
get_daily_chartto detect surprise breakout performances. - Populate an all-time box office leaderboard using
get_all_time_worldwidewith domestic and foreign splits. - Alert system for upcoming studio releases by polling
get_release_scheduleand filtering bydistributor. - Cross-reference IMDb metadata with box office performance by chaining
search_movies→get_movie_details. - Analyze theater-count expansion curves over a film's run using
TheatersandDayfields fromget_movie_release_performance.
| 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 Box Office Mojo have an official developer API?+
What does `get_movie_details` return beyond the gross totals?+
domestic, international, and worldwide lifetime grosses, the summary object includes domestic_distributor, domestic_opening, budget, earliest_release_date, mpaa, running_time, and genres. The market_breakdowns object further segments performance by individual international regions, and the releases array lists every tracked release version (e.g., original run, re-release) each with its own release_id.Does `search_movies` support pagination or filtering by year?+
title, imdb_id, and url for each match. You can fork the API on Parse and revise it to add server-side filtering or multi-page traversal.Does the API cover international daily charts or only the domestic (US) chart?+
get_daily_chart endpoint returns the domestic US chart only. International market data is accessible at the title level via market_breakdowns in get_movie_details, but there are no per-country daily ranking charts currently exposed. You can fork the API on Parse and revise it to add international chart endpoints.How current is the daily chart data, and what happens if I query a future date?+
date parameter from get_daily_chart always returns the most recent available chart, which is the safest default for automated polling.