The Numbers APIthe-numbers.com ↗
Access box office charts, movie financials, cast/crew, and all-time records from the-numbers.com. 5 endpoints covering daily grosses, budgets, and rankings.
What is the The Numbers API?
The Numbers API exposes 5 endpoints covering box office and film industry data from the-numbers.com. Use get_daily_box_office_chart to pull ranked daily domestic grosses with theater counts, search_movies to look up films by title, and get_movie_details to retrieve production budgets, cumulative revenue, runtime, genre, and synopsis for any title. All-time records and full cast/crew listings are also available.
curl -X GET 'https://api.parse.bot/scraper/0e52317c-3651-49f2-b8bf-cd39e09d01de/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 the-numbers-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: TheNumbers SDK — movie box office data, bounded and re-runnable."""
from parse_apis.the_numbers_api import TheNumbers, MovieNotFound
client = TheNumbers()
# Search for movies by title — limit caps total items fetched.
for movie in client.movies.search(query="Avatar", limit=5):
print(movie.title, movie.year, movie.director)
# Get today's daily box office chart.
for entry in client.dailyboxofficeentries.list(limit=5):
print(entry.rank, entry.title, entry.gross, entry.theaters)
# Drill into a single movie's full details via .first() then .details().
movie = client.movies.search(query="Backrooms", limit=1).first()
if movie:
detail = movie.details()
print(detail.title, detail.worldwide_box_office, detail.genre, detail.running_time)
# Typed error handling: catch MovieNotFound for a bad slug.
try:
bad = client.movies.get(slug="Nonexistent-Movie-(9999)")
print(bad.title)
except MovieNotFound as exc:
print(f"Movie not found: {exc.slug}")
print("exercised: movies.search / dailyboxofficeentries.list / movies.get / movie.details")
Search for movies by title using the site's autocomplete API. Returns up to 10 movie results matching the query, filtered to movies only (excludes franchises). Each result includes title, slug, year, lead cast, and director when available.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword or movie title to search for |
{
"type": "object",
"fields": {
"items": "array of movie objects with title, slug, year, lead_cast, and director fields"
},
"sample": {
"data": {
"items": [
{
"slug": "Avatar-Fire-and-Ash-(2025)",
"year": 2025,
"title": "Avatar: Fire and Ash",
"director": "James Cameron",
"lead_cast": "Sam Worthington, Zoe Saldaña"
},
{
"slug": "Avatar-(2009)",
"year": 2009,
"title": "Avatar",
"director": "James Cameron",
"lead_cast": "Sam Worthington, Zoe Saldaña"
}
]
},
"status": "success"
}
}About the The Numbers API
Movie Search and Detail
The search_movies endpoint accepts a query string and returns up to 10 matching movie objects, excluding franchise entries. Each result includes a slug (e.g. Avatar-(2009)) that serves as the key identifier for other endpoints. Pass that slug to get_movie_details to retrieve financial data (domestic gross, production budget, cumulative totals), along with genre, runtime, and a synopsis. The same slug works with get_movie_cast_and_crew, which returns actor names, character names, and per-person slugs for further lookups.
Daily Box Office Charts
get_daily_box_office_chart returns a ranked list of films for a given date, supplied in YYYY/MM/DD format via the date parameter. Each entry in the response includes rank, title, single-day gross, theater count, and cumulative total gross. Omitting the date parameter returns the most recently available chart, which is useful when you need the latest figures without knowing the exact date.
All-Time Records
get_all_time_box_office_records returns ranked historical box office totals filterable by category: domestic, international, or worldwide. Each record includes the rank, movie title, a Movie_slug for cross-referencing with get_movie_details, domestic gross, and worldwide gross. This makes it straightforward to build leaderboards or benchmark a specific film's performance against historical highs.
The The Numbers API is a managed, monitored endpoint for the-numbers.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when the-numbers.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 the-numbers.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 daily domestic box office performance for any date using ranked gross and theater count data
- Look up a film's production budget vs. cumulative gross to assess financial performance
- Build all-time worldwide box office leaderboards filtered by domestic, international, or worldwide category
- Retrieve full cast and crew listings by movie slug for film database applications
- Cross-reference a newly released film's daily ranking with all-time records to gauge relative performance
- Power a movie discovery tool that surfaces genre, runtime, and synopsis alongside revenue data
- Monitor box office trends by querying daily charts across a date range
| 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 the-numbers.com have an official developer API?+
What financial fields does get_movie_details return?+
Does the daily chart cover international or opening-weekend box office?+
get_daily_box_office_chart endpoint returns domestic (U.S.) daily gross figures. International daily charts and per-territory breakdowns are not currently covered. You can fork this API on Parse and revise it to add an endpoint targeting international chart data.Is weekly or cumulative box office history available per film?+
get_movie_details, and all-time ranking records. Week-by-week performance history for individual titles is not exposed. You can fork the API on Parse and revise it to add a weekly breakdown endpoint.How do I look up cast data if I only know the movie title?+
search_movies with the title as the query parameter to get a matching slug, then pass that slug to get_movie_cast_and_crew. The cast endpoint returns actor name, character name, and an Actor_person_slug for each credited performer.