Filmové API pro vyhledávání, detaily a hodnocení

Filmové API, které mluví TMDB v3 a OMDb

amodb je nezávislé filmové API. Mluví stejným protokolem jako TMDB v3 a OMDb, takže klient napsaný pro kterékoli z nich funguje po změně základní URL na https://api.amodb.dev/3 (nebo https://api.amodb.dev/omdb/ pro volání ve stylu OMDb). Film najdete přes /search/movie a pak ho načtete přes /movie/{movie_id} a append_to_response.

Co dostanete:

• JSON ve tvaru TMDB v3, se stejnými cestami a parametry dotazu.
• Názvy a popisy ve 14 jazycích, vybírané přes language.
• Obsazení, štáb, trailery, klíčová slova, obrázky a data premiér přes append_to_response.
• Hodnocení ze zdrojů IMDb, Kinopoisk, Metacritic, Rotten Tomatoes a TMDB, kde jsou známá.
• Plakáty z https://img.amodb.dev/t/p/{size}/{file}, bez klíče.

Jaká data dostanete

Začněte ve 3 krocích

1. Vyberte tarif na stránce ceník. Tarify se liší jen rychlostí: 20, 40 nebo 120 požadavků za minutu.
2. Vytvořte klíč v panelu účtu. Klíč má 32 malých hexadecimálních znaků.
3. Zavolejte endpoint s klíčem v parametru api_key nebo v hlavičce Authorization: Bearer. Viz autentizace.

Příklad požadavku

Ukázka najde Inception podle názvu, vezme první nález a v dalším volání načte film s obsazením, trailery a hodnocením. Dohromady jsou to dva požadavky.

# 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);

Zkrácená odpověď. Ze záznamu filmu zůstala jen část polí, credits je zkráceno na jednoho herce a režiséra a blok videos je vynechán.

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

Způsoby, jak najít film

Vyberte volání podle toho, co už máte.

Ukládejte obě ID. Číselné id je klíč pro všechna ostatní volání a imdb_id propojuje vaše data s jinými systémy. Pravidla vyhledávání jsou na stránce hledání podle externího ID.

Prázdná pole a neúspěšná vyhledání

Skutečná filmová data mají mezery, proto pro ně napište zobrazovací kód. Vyhledávání bez nálezu není chyba: vrací HTTP 200 s prázdným polem results. Neznámé ID je chyba.

Úplný seznam chyb je na stránce chyby.

Jak zůstat v limitu požadavků

Vyhledání a volání detailů stojí po jednom požadavku. Při 20 požadavcích za minutu je to deset vyhledání titulů za minutu, při 120 požadavcích za minutu šedesát. Zásah cache na edge se stále počítá, protože kontrola klíče a limitu proběhne před cache. Pro opakovaná vyhledání si veďte vlastní cache a z X-RateLimit-Remaining zjistíte, kolik z minuty zbývá. Při 429 počkejte počet sekund z Retry-After. Limity podle tarifu jsou na stránce limity požadavků.

Jak si stojí v porovnání

Ceník

Přístup je předplacený na 1, 3, 6, 12 nebo 24 měsíců, u delších období je sleva 0, 10, 20, 30 a 40 procent. Neexistuje automatické obnovení ani bezplatný tarif. Každý tarif dostane všechna data a tarify se liší jen rychlostí: 20, 40 nebo 120 požadavků za minutu. Vyberte tarif na stránce ceník a první volání provedete během několika minut.