API de filmes para busca, detalhes e avaliações

Uma API de filmes que fala TMDB v3 e OMDb

O amodb é uma API de filmes independente. Ela fala o mesmo protocolo do TMDB v3 e do OMDb, então um cliente escrito para qualquer um dos dois funciona depois que você troca a URL base para https://api.amodb.dev/3 (ou https://api.amodb.dev/omdb/ para chamadas no estilo OMDb). Você encontra um filme com /search/movie e depois o lê com /movie/{movie_id} e append_to_response.

O que você recebe:

• JSON no formato do TMDB v3, com os mesmos caminhos e parâmetros de consulta.
• Títulos e sinopses em 14 idiomas, selecionados com language.
• Elenco, equipe técnica, trailers, palavras-chave, imagens e datas de lançamento por meio de append_to_response.
• Avaliações do IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB, quando conhecidas.
• Pôsteres de https://img.amodb.dev/t/p/{size}/{file}, sem chave.

Quais dados você recebe

Comece em 3 passos

1. Escolha um plano em preços. Os planos diferem apenas no limite: 20, 40 ou 120 requisições por minuto.
2. Crie uma chave no painel da sua conta. Uma chave tem 32 caracteres hexadecimais minúsculos.
3. Chame o endpoint com a chave no parâmetro api_key ou em um cabeçalho Authorization: Bearer. Veja autenticação.

Exemplo de requisição

O exemplo encontra Inception pelo título, pega o primeiro resultado e lê o filme com elenco, trailers e avaliações em mais uma chamada. São duas requisições no 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);

A resposta reduzida. Só alguns campos do registro do filme foram mantidos, credits foi cortado para um membro do elenco e o diretor, e o bloco videos foi omitido.

{
  "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
    }
  }
}

Formas de encontrar um filme

Escolha a chamada que corresponde ao que você já tem.

Guarde os dois IDs. O id numérico é a chave de todas as outras chamadas, e imdb_id liga seus dados a outros sistemas. As regras de consulta estão em busca por ID externo.

Campos vazios e consultas que falham

Dados reais de filmes têm lacunas, então escreva o código de exibição pensando nelas. Uma busca sem resultado não é um erro: ela retorna HTTP 200 com um array results vazio. Um ID desconhecido é um erro.

A lista completa de erros está em erros.

Como ficar dentro do limite de requisições

Uma busca e uma chamada de detalhes custam uma requisição cada. Com 20 requisições por minuto são dez consultas de título por minuto, com 120 requisições por minuto são sessenta. Um acerto no cache de borda também conta, porque a verificação da chave e o limite de requisições rodam antes do cache. Mantenha um cache próprio para consultas repetidas e leia X-RateLimit-Remaining para ver quanto do minuto resta. Ao receber um 429, aguarde os segundos indicados em Retry-After. Os limites de cada plano estão em limites de requisições.

Como se compara

Preços

O acesso é pré-pago por 1, 3, 6, 12 ou 24 meses, com 0, 10, 20, 30 e 40 por cento de desconto nos períodos mais longos. Não há renovação automática nem plano gratuito. Todos os planos recebem todos os dados, e os planos diferem apenas no limite: 20, 40 ou 120 requisições por minuto. Escolha um em preços e faça sua primeira chamada em poucos minutos.