Director's Box Office Summary
A director's whole box office career, in one page.
Type a name to see their total worldwide gross, the domestic/international split, their biggest hits,
every film's numbers and a gross-over-time chart. Read it as a web page or save it as a PDF.
Data from IMDb, no API key needed.
https://github.com/user-attachments/assets/66c4b5af-6700-4060-b24a-40b216f3c60b
The welcome page. Enter a name or an IMDb id, pick a format and press Get the report.
Top half of the web report for Christopher Nolan. Full files:
PDF · HTML
The same report as a PDF: a summary page with the top films, the full filmography and the
career chart.
Examples
GitHub previews the PDFs in the browser, but it shows HTML files as source code. To see the
page, download the file (Raw, then save) and open it in a browser. Images are embedded,
so it works offline.
These were generated on 2026-10-17. The numbers change as IMDb updates its data.
Quick start
Requires Python 3.10 or newer.
git clone <repo-url>
cd DirectorsBoxOfficeSummary
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
uvicorn app:app --reload
Open http://127.0.0.1:8000. You don't need an account, key or .env file.
Web app
- Search: type a name or an IMDb id (such as
nm0634240, from the director's IMDb URL).
Case and accents don't matter. A clear match opens the report straight away ("nolan" finds
Christopher Nolan). If the name is ambiguous ("Paul Anderson"), you get a list of up to
five people to choose from.
- Format: the Web page / PDF toggle picks how the report opens. Reports live at
/report/<nm id>.html and /report/<nm id>.pdf, so you can link to them directly.
- Errors are shown on the search page, not as tracebacks. If IMDb or the network fails,
the message says why (for example "IMDb returned 403").
- Size and caching: the web page links its images to IMDb's CDN rather than embedding
them, so it is only tens of KB. Responses are cacheable for a day, so repeat requests
don't hit IMDb.
- Hosting: it runs on Vercel's free Hobby plan (
app.py and vercel.json are all it
needs). Keep such a deployment private: see the disclaimer below.
Command line
The CLI writes the same reports to files. Only the runtime dependencies are needed
(pip install -r requirements.txt).
$ python main.py
Director's full name: Christopher Nolan
Found Christopher Nolan (nm0634240). Fetching filmography...
13 film(s).
Output format [pdf/html/both] (pdf): both
Building PDF...
Saved output/Christopher Nolan.pdf
Downloading 14 image(s)...
Saved output/Christopher Nolan.html
- Name or id: the same matching rules as the web app. An ambiguous name gives a numbered
list; pick one, or leave it blank to cancel.
- Format:
pdf, html or both. The first letter is enough, and a blank answer means
pdf.
- Output: files go to
output/<Director Name>.pdf and .html. The folder is created on
first run. Unlike the web page, the CLI's HTML file embeds all images, so it works offline.
What's in the report
Both formats contain:
- Header: portrait, name and total worldwide box office.
- Totals: domestic gross, international gross and the number of feature films.
- Top three films, with posters: highest worldwide gross, highest domestic gross and
biggest domestic opening weekend.
- Filmography: every film ranked by worldwide gross, with its budget and grosses.
- Career chart: worldwide and domestic gross for each film, in release order.
PDF
A4 pages with a fixed layout. The chart always gets the last page to itself. With more than
15 films that page switches to landscape, and the x-axis labels rotate or wrap so that every
title stays readable. Here is Spielberg's chart, with 36 films:
HTML
All CSS and JavaScript are inlined (the CLI also inlines the images, giving a single offline file).
- Light and dark themes: follows your system setting.
- Interactive chart: hover a film, or focus it with the keyboard, to see its title, year
and grosses.
- Sortable table: click a column header to sort. Films with missing data always sort
last.
- Extra table columns: an opening weekend column, and a bar per film showing its
worldwide gross with the domestic share highlighted.
- Phone layout: works on narrow screens. The chart and table scroll sideways.
Which films count
The report includes released feature films that the person is credited as directing.
Shorts, TV movies, direct-to-video titles and unreleased or abandoned projects are left out.
All amounts are in US dollars. A missing figure is shown as -:
- A film with no box office data on IMDb stays in the table and is not left out.
- A budget that IMDb reports in another currency also shows as
-. For example, RRR's
budget is listed in Indian rupees.
How it works
One run makes three requests to IMDb's GraphQL endpoint (caching.graphql.imdb.com): a
name search, the director's profile and their directing credits with box office data. For
the HTML page it also downloads the portrait and posters as small thumbnails. Dropped
connections, rate limits and server errors are retried with exponential backoff. If the API returns an error, the run stops
rather than producing a report with missing films.
main.py prompts, file output; wires the layers together
app.py the same pipeline as a web app (FastAPI)
src/
movies.py domain: API JSON -> Director / Movie, search ranking, totals, top films
imdb_api.py IMDb GraphQL queries
http_client.py HTTP with retries
pdf.py, chart.py PDF renderer (fpdf2) and matplotlib chart
html_page.py HTML renderer, with svg_chart.py and assets/ (CSS + JS)
images.py downloads the images for the HTML page as data URIs
search_page.py the web app's search page
tests/ offline tests for the HTML output and the web routes
examples/ the sample reports linked above
Everything under src/ is free of side effects, and all I/O happens in main.py and app.py.
Tests
pytest
The tests run offline and cover the HTML renderer (escaping, missing values, placeholders,
chart ordering, number formatting) and the web routes (redirects, candidate list, error
pages, PDF output). They need requirements-dev.txt.
Disclaimer
This is a personal, non-commercial project and is not affiliated with IMDb. It uses IMDb's
unofficial, undocumented GraphQL API. Every response includes IMDb's notice that "public,
commercial, and/or non-private use" of the data is not allowed, and IMDb's Conditions of Use
prohibit automated access. The endpoint can change or be blocked without warning. Posters and
portraits belong to their respective owners.
