IMDb API: a movie or series entry in JSON

You type in a movie or series title, my API returns its details in JSON: year, duration, genres, rating and number of votes. Two calls to know, one key, and that's it.

Behind it, there's a database of nearly 13 million titles: movies, made-for-TV movies, short films, series, miniseries and episodes, with their titles in every country. It's the kind of data you find on IMDb, except here you receive it in a format your code swallows without a fuss. I use it myself to display movie ratings in my TV guide.

Free or PRO: what you get

Both plans give access to the same calls and the same data. The only difference is the number of requests per day. The green bar shows what you can ask for in one day.

The counter resets at midnight UTC, so at 1 or 2 in the morning in France depending on the season. Each accepted call counts as a request, even when the search finds nothing. A rejected key costs nothing.

Get your key

It takes a minute: create an account, validate your e-mail address, then copy the key shown in your account. It's the same key as for my other services. It is sent in the Authorization header of each request, instead of VotreCleApi in the examples below.

Were you using the old version with apiKey in the URL? This parameter is no longer read, the key now goes only through the header. A key wandering around in an address ends up in the logs of every server it passes through, and I didn't want that anymore.

Search for a movie by its title

This is the SearchByTitle call. The only required parameter is title:

curl -H "Authorization: Bearer VotreCleApi" "https://imdb.digital3d.com/api/SearchByTitle?title=ben-hur"

Well, you'll receive every Ben-Hur in the history of cinema, and there are loads of them. Three filters let you narrow it down:

Which gives, for the real Ben-Hur, the one with the chariot race:

curl -H "Authorization: Bearer VotreCleApi" "https://imdb.digital3d.com/api/SearchByTitle?title=ben-hur&year=1959&type=movie&region=US"

Titles that match exactly come first, the right year first, then the ones with the most votes. And if nothing matches exactly, the API returns the closest titles instead of leaving you staring at an empty list. Handy when you can no longer remember the spelling. The response contains a maximum of 100 results.

Retrieve a record by its identifier

Every film has an identifier that starts with tt, the one you see in the address of its IMDb page. If you already have it, the GetByTitleId call goes straight to the point, with no possible ambiguity:

curl -H "Authorization: Bearer VotreCleApi" "https://imdb.digital3d.com/api/GetByTitleId?titleId=tt0111161&region=FR"

With region=FR, the title field contains the French title. Without this parameter, you receive one line per known title of the film, across all countries.

What the response contains

The response is always a JSON array, even for a single film. Here is the record for The Shawshank Redemption, shortened to its most useful fields:

[
  {
    "titleId": "tt0111161",
    "title": "Les Évadés",
    "region": "FR",
    "titleType": "movie",
    "primaryTitle": "The Shawshank Redemption",
    "startYear": "1994",
    "endYear": null,
    "runtimeMinutes": "142",
    "genres": "Drama",
    "averageRating": "9.3",
    "numVotes": "3246333",
    "poster": "",
    "backdrop": ""
  }
]

Two things to know before coding. All values are strings, including the year, duration and rating: remember to convert them. And the poster and backdrop fields (the poster and background image) are only filled in for a small portion of titles for now, so don't count on them to dress up an entire media library.

Tracking your quota

No need to count on your end. As soon as the key is accepted, every response carries three headers: X-RateLimit-Limit (your daily limit), X-RateLimit-Remaining (what you have left) and X-RateLimit-Reset (the reset time, in Unix seconds).

As for errors, there are three to plan for:

• 401 : the key is missing, it is written incorrectly, or the account has not been validated yet.
• 429 : the daily quota has been used up. The Retry-After header gives the number of seconds to wait before the reset.
• 503 : the service was unable to verify the key. Try again 30 seconds later.

I ran the test with a free account: ten requests go through, the eleventh gets its 429. I wasn't born yesterday, I check.

Test without writing a line of code

Everything is documented in the API's Swagger (a page that lists the calls and lets you run them from the browser). Click on "Authorize", paste your key, then try each call with the "Try it out" button. Just watch out: these tests count towards your quota, like any request.

Why a subscription?

Because the database runs on a server that I pay for, and a database of this size needs maintenance. The free plan is still there for testing and light use. If the API is useful to you every day, the PRO subscription at €12 per month raises the limit to 1000 requests per day, includes the complete TV guide and all my software, and that's what keeps the service alive. Commercial use without a subscription is not allowed.