IMDb API alternative

IMDb data over REST: the short answer

IMDb has no free general purpose REST API. Its non-commercial datasets are downloadable files, and commercial access is licensed, so check their docs for current terms. If you want to call an HTTP endpoint with an IMDb id and get JSON back, amodb does that on a paid plan. If your contract requires data licensed from IMDb itself, that agreement is with IMDb and amodb does not replace it.

Ways to use an IMDb id on amodb

Five calls cover most needs. Each one starts from an id you already have or ends with one.

Every row works with the same key. Ratings are described on the ratings page and id lookups on find by external id.

Read the IMDb score

The ratings endpoint returns the score and the vote count together. This is a real reply for Fight Club (id 550). Scores change over time.

{
  "id": 550,
  "imdb": {
    "value": 8.8,
    "votes": 2669989
  },
  "kinopoisk": {
    "value": 8.7,
    "votes": null
  },
  "metacritic": {
    "value": 67,
    "votes": null
  },
  "rotten_tomatoes": {
    "value": 81,
    "votes": null
  },
  "tmdb": {
    "value": 8.437,
    "votes": 33039
  }
}

For IMDb the value is on a 0 to 10 scale with one decimal. Show the vote count beside it, and render nothing when the object is null. In this reply only IMDb and TMDB carry votes. votes can be null for any source, so check it before you show it. A cached reply stays valid for 6 hours at the edge, so polling more often gains nothing.

Feature comparison

Where amodb differs

You call an endpoint instead of parsing a file. One request returns a title with its cast, trailers and ratings through append_to_response, and the shape matches TMDB v3, so existing client libraries work. The same key serves the OMDb style endpoint, which keeps older code that reads imdbRating running.

The ratings block is a fixed object with five keys. A source that is not known is null, not a missing key, so code that reads ratings.imdb does not need an existence check on the parent. A vote count can sit beside the value, which lets you hide a score that rests on few votes. It can also be null, as it is for three of the five sources in the example above.

Where IMDb is a better fit

• The origin of the score. IMDb publishes its own ratings first. amodb returns a value only where it is known, so a new or obscure title can come back null.
• Site features. User reviews, lists and watchlists live on the IMDb site. amodb is a metadata API and offers no user accounts.
• Licensed data. If a partner or a contract demands IMDb licensed data, only IMDb can provide it.
• Offline analysis. The non-commercial dataset files suit bulk research that you run on your own machine. Check their docs for the terms.

Migrate to amodb

You most likely hold a list of IMDb ids. Map each one to an amodb id once, store the pair, and call details by the numeric id afterwards.

curl -s "https://api.amodb.dev/3/find/tt0133093?external_source=imdb_id" \
  -H "Authorization: Bearer $AMODB_KEY"

import os
import requests

KEY = os.environ["AMODB_KEY"]
imdb_ids = ["tt0137523", "tt0133093", "tt1375666"]

for imdb_id in imdb_ids:
    r = requests.get(
        f"https://api.amodb.dev/3/find/{imdb_id}",
        params={"external_source": "imdb_id"},
        headers={"Authorization": f"Bearer {KEY}"},
        timeout=10,
    )
    r.raise_for_status()
    hits = r.json()["movie_results"]
    print(imdb_id, hits[0]["id"] if hits else None)

The three ids above map to 550, 603 and 27205, which are Fight Club, The Matrix and Inception. A series id such as tt0903747 comes back in tv_results, where Breaking Bad has id 1396. An empty array means no match was found for that id.

Pace the loop. Each id is one request, and a 429 includes a Retry-After header with the seconds to wait. See errors for the other codes.

Store ids safely

• Keep IMDb ids as strings. They start with tt and carry leading zeros, as in tt0137523, and a number type drops those zeros.
• Save the IMDb id and the amodb id as a pair. Either one finds the title again.
• Read tv_results for series and movie_results for films. A single id normally fills one array and leaves the others empty.
• Request details by the amodb id from then on, because a details call can carry cast, trailers and ratings through append_to_response.

Pricing

Choose one of three plans at 20, 40 or 120 requests per minute and prepay for 1, 3, 6, 12 or 24 months. Longer periods take 10, 20, 30 or 40 percent off. All plans return the same data, nothing renews on its own, and there is no free tier. See pricing for amounts.