Movie API for search, details and ratings

A movie API that speaks TMDB v3 and OMDb

amodb is an independent movie API. It speaks the same protocol as TMDB v3 and OMDb, so a client written for either one works after you change the base URL to https://api.amodb.dev/3 (or https://api.amodb.dev/omdb/ for OMDb style calls). You find a movie with /search/movie, then read it with /movie/{movie_id} and append_to_response.

What you get:

• JSON in the TMDB v3 shape, with the same paths and query parameters.
• Titles and overviews in 14 languages, selected with language.
• Cast, crew, trailers, keywords, images and release dates through append_to_response.
• Ratings from IMDb, Kinopoisk, Metacritic, Rotten Tomatoes and TMDB where known.
• Posters from https://img.amodb.dev/t/p/{size}/{file}, with no key.

What data you get

Start in 3 steps

1. Choose a plan on pricing. Plans differ only in rate: 20, 40 or 120 requests per minute.
2. Create a key in your account dashboard. A key is 32 lowercase hex characters.
3. Call the endpoint with the key in the api_key parameter or in an Authorization: Bearer header. See authentication.

Example request

The sample finds Inception by title, takes the first hit, and reads the movie with cast, trailers and ratings in one more call. That is two requests in total.

# 1. find the id
curl -s "https://api.amodb.dev/3/search/movie?query=inception&language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

# 2. read the movie with extras
curl -s "https://api.amodb.dev/3/movie/27205?language=en-US&append_to_response=credits,videos,ratings" \
  -H "Authorization: Bearer $AMODB_KEY"

const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };

async function get(path, params) {
  const res = await fetch(`${base}${path}?${new URLSearchParams(params)}`, { headers });
  if (res.status === 429) {
    throw new Error(`Over the limit, retry in ${res.headers.get('Retry-After')} s`);
  }
  if (!res.ok) throw new Error(`amodb returned ${res.status}`);
  return res.json();
}

const found = await get('/search/movie', { query: 'inception', language: 'en-US' });
if (!found.results.length) throw new Error('No match');

const movie = await get(`/movie/${found.results[0].id}`, {
  language: 'en-US',
  append_to_response: 'credits,videos,ratings',
});
const director = movie.credits.crew.find((c) => c.job === 'Director');
console.log(movie.title, movie.release_date, movie.runtime, director?.name);
console.log('IMDb', movie.ratings.imdb?.value);

The trimmed reply. Only some fields of the movie record are kept, credits is cut to one cast member and the director, and the videos block is left out.

{
  "genres": [
    {
      "id": 12,
      "name": "Adventure"
    },
    {
      "id": 28,
      "name": "Action"
    },
    {
      "id": 80,
      "name": "Crime"
    }
  ],
  "id": 27205,
  "imdb_id": "tt1375666",
  "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg",
  "release_date": "2010-07-15",
  "runtime": 148,
  "title": "Inception",
  "credits": {
    "cast": [
      {
        "adult": false,
        "gender": 2,
        "id": 6193,
        "known_for_department": "Acting",
        "name": "Leonardo DiCaprio",
        "original_name": "Leonardo DiCaprio",
        "popularity": 9.3213,
        "profile_path": "/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
        "character": "Dom Cobb",
        "credit_id": "52fe4534c3a368484e04de03",
        "order": 0
      }
    ],
    "crew": [
      {
        "adult": false,
        "gender": 2,
        "id": 525,
        "known_for_department": "Directing",
        "name": "Christopher Nolan",
        "original_name": "Christopher Nolan",
        "popularity": 8.578,
        "profile_path": "/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg",
        "credit_id": "5e83ac2ee33f830018359a00",
        "department": "Directing",
        "job": "Director"
      }
    ]
  },
  "ratings": {
    "imdb": {
      "value": 8.8,
      "votes": 2877173
    },
    "kinopoisk": {
      "value": 8.7,
      "votes": null
    },
    "metacritic": {
      "value": 74,
      "votes": null
    },
    "rotten_tomatoes": {
      "value": 86,
      "votes": null
    },
    "tmdb": {
      "value": 8.373,
      "votes": 40457
    }
  }
}

Ways to find a movie

Pick the call that matches what you already hold.

Store both ids. The numeric id is the key for every other call, and imdb_id joins your data to other systems. The lookup rules are on find by external id.

Empty fields and failed lookups

Real movie data has gaps, so write the display code for them. A search with no hit is not an error: it returns HTTP 200 with an empty results array. An unknown id is an error.

The full error list is on errors.

Staying inside the rate limit

A search and a details call cost one request each. At 20 requests per minute that is ten title lookups a minute, at 120 requests per minute it is sixty. A cache hit at the edge still counts, because the key check and the rate limit run before the cache. Keep a cache of your own for repeat lookups, and read X-RateLimit-Remaining to see how much of the minute is left. When you get a 429, wait the Retry-After seconds. Limits per plan are on rate limits.

How it compares

Pricing

Access is prepaid for 1, 3, 6, 12 or 24 months, with 0, 10, 20, 30 and 40 percent off the longer periods. There is no automatic renewal and no free tier. Every plan gets all data, and the plans differ only in rate: 20, 40 or 120 requests per minute. Pick one on pricing and make your first call in a few minutes.