# IMDb API alternative

> IMDb has no free general purpose REST API: its non-commercial datasets are downloadable files and commercial access is licensed. amodb is a paid JSON API where you look up a title by IMDb id, read the IMDb rating and vote count where known, and get cast, images and trailers with one key.

## 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.

| You have or want        | Call                                            | You get                                                |
| ----------------------- | ----------------------------------------------- | ------------------------------------------------------ |
| A title from an IMDb id | `GET /3/find/tt0137523?external_source=imdb_id` | Arrays `movie_results`, `tv_results`, `person_results` |
| The IMDb id of a movie  | `GET /3/movie/550`, field `imdb_id`             | `tt0137523` for Fight Club                             |
| The IMDb id of a series | `GET /3/tv/1396/external_ids`                   | `imdb_id` next to the TVDB id                          |
| The IMDb score          | `GET /3/movie/550/ratings`                      | `imdb` as `value` and `votes`, or null                 |
| An OMDb style record    | `GET /omdb/?i=tt0137523`                        | `imdbRating`, `imdbVotes`, `imdbID`                    |

Every row works with the same key. Ratings are described on the [ratings](https://amodb.dev/ratings/) page and id lookups on [find by external id](https://amodb.dev/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.

```json
{
  "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

| Feature         | IMDb                                                            | amodb                                                 |
| --------------- | --------------------------------------------------------------- | ----------------------------------------------------- |
| Pricing model   | Licensed for commercial access, check their docs                | Prepaid, from 1 to 24 months                          |
| Free tier       | No free general purpose REST API                                | None, and no trial                                    |
| Authentication  | Check their docs                                                | `api_key` query parameter or Bearer header            |
| Response format | Downloadable dataset files, check their docs for licensed feeds | JSON                                                  |
| Languages       | Check their docs                                                | 14 interface languages                                |
| Movies          | Check their docs for fields                                     | Details, credits, images, videos                      |
| TV              | Check their docs for fields                                     | Series, seasons, episodes                             |
| People          | Check their docs for fields                                     | Profiles, filmography, images                         |
| Images          | Check their docs                                                | `img.amodb.dev`, no key needed                        |
| Ratings         | Its own score, check their docs for access                      | Five sources, IMDb among them, where known            |
| Rate limit      | Check their docs                                                | 20, 40 or 120 requests per minute                     |
| Commercial use  | Licensed, check their docs                                      | Paid plans, see [pricing](https://amodb.dev/pricing/) |
| Compatibility   | Its own formats, check their docs                               | TMDB v3 reads and the OMDb protocol                   |

## 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.

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

```python
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](https://amodb.dev/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](https://amodb.dev/pricing/) for amounts.

## Questions and answers

### Does IMDb offer a free REST API?

IMDb has no free general purpose REST API. Its non-commercial datasets are downloadable files, and commercial access is licensed. Check their docs for the current terms, formats and fields before you plan around them.

### Can I look up a title by its IMDb id on amodb?

Yes. Call /3/find/tt0137523 with external_source=imdb_id and read movie_results, tv_results or person_results. The OMDb style endpoint also accepts the i parameter with an IMDb id.

### Is the IMDb rating always present?

No. The ratings object always has the five keys imdb, kinopoisk, metacritic, rotten_tomatoes and tmdb, but each one is null when the score is not known. Handle null before you render a number.

### Do I get IMDb user reviews or lists?

No. amodb returns the IMDb id, and the IMDb score with its vote count where known. It does not host IMDb user reviews, lists or watchlists. The TMDB style reviews endpoint answers 200, and most titles return an empty list.

### How long does it take to map a list of IMDb ids?

One find request per id. A list of 500 ids needs 500 requests, so on the plan with 20 requests per minute that takes about 25 minutes. Store the result, because the mapping rarely changes.

## Related pages

- [Find by external id](https://amodb.dev/find-by-external-id/): Look up a movie, series or person by IMDb, TVDB, Wikidata or Kinopoisk id with the TMDB find endpoint, and read external ids and Wikidata facts for a title.
- [Movie and TV ratings](https://amodb.dev/ratings/): Movie ratings API that returns IMDb, Kinopoisk, Metacritic, Rotten Tomatoes and TMDB scores for a title in one call, with null for any source not known.
- [OMDb compatible endpoint](https://amodb.dev/omdb-endpoint/): OMDb API compatible endpoint at api.amodb.dev/omdb/. Look up by i or t, search with s, read the Ratings array and keep your client by changing the base URL.
- [OMDb API alternative](https://amodb.dev/omdb-api-alternative/): Hit the OMDb daily cap or need more than one record per call? amodb answers OMDb style requests and also serves TMDB v3 endpoints, with the same key.
- [Authentication](https://amodb.dev/authentication/): How to send your amodb key: api_key in the query, an Authorization Bearer header, or apikey for OMDb calls. Key format, storage, rotation and the 401 errors.
- [Rate limits](https://amodb.dev/rate-limits/): amodb limits each key by requests per minute in a sliding 60 second window: 20, 40 or 120 by plan. Read the rate limit headers and handle 429 with Retry-After.

Updated: 2026-10-18. Source: https://amodb.dev/imdb-api-alternative/