API фільмаў для пошуку, дэталяў і рэйтынгаў

API фільмаў, якое працуе па пратаколе TMDB v3 і OMDb

amodb уяўляе сабой незалежнае API фільмаў. Яно працуе па тым жа пратаколе, што TMDB v3 і OMDb, таму кліент, напісаны для любога з іх, будзе працаваць пасля змены базавага URL на https://api.amodb.dev/3 (або https://api.amodb.dev/omdb/ для выклікаў у стылі OMDb). Фільм знаходзяць праз /search/movie, а потым чытаюць праз /movie/{movie_id} і append_to_response.

Што вы атрымліваеце:

• JSON у форме TMDB v3 з тымі ж шляхамі і параметрамі запыту.
• Назвы і апісанні на 14 мовах, мова выбіраецца праз language.
• Акцёрскі склад, здымачная група, трэйлеры, ключавыя словы, выявы і даты выхаду праз append_to_response.
• Рэйтынгі IMDb, Kinopoisk, Metacritic, Rotten Tomatoes і TMDB, калі яны вядомыя.
• Постэры з https://img.amodb.dev/t/p/{size}/{file} без ключа.

Якія даныя вы атрымліваеце

Пачніце за 3 крокі

1. Абярыце тарыфны план на старонцы цэны. Планы адрозніваюцца толькі абмежаваннем: 20, 40 або 120 запытаў у хвіліну.
2. Стварыце ключ у асабістым кабінеце. Ключ уяўляе сабой 32 шаснаццатковыя сімвалы ў ніжнім рэгістры.
3. Выклічце эндпоінт, перадаўшы ключ у параметры api_key або ў загалоўку Authorization: Bearer. Гл. аўтэнтыфікацыя.

Прыклад запыту

У прыкладзе фільм Inception знаходзіцца па назве, бярэцца першы вынік, а потым адным выклікам чытаюцца фільм з акцёрамі, трэйлерамі і рэйтынгамі. Разам атрымліваецца два запыты.

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

Скарочаны адказ. З запісу фільма пакінуты толькі некаторыя палі, credits скарочаны да аднаго акцёра і рэжысёра, а блок videos прапушчаны.

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

Спосабы знайсці фільм

Абярыце выклік, які адпавядае таму, што ў вас ужо ёсць.

Захоўвайце абодва id. Лікавы id патрэбны для ўсіх астатніх выклікаў, а imdb_id звязвае вашы даныя з іншымі сістэмамі. Правілы пошуку апісаны на старонцы пошук па вонкавым ідэнтыфікатары.

Пустыя палі і няўдалыя запыты

У рэальных даных пра фільмы бываюць прабелы, таму ўлічвайце іх у коде адлюстравання. Пошук без вынікаў не з’яўляецца памылкай: ён вяртае HTTP 200 і пусты масіў results. Невядомы id з’яўляецца памылкай.

Поўны спіс памылак ёсць на старонцы памылкі.

Як застацца ў межах ліміту запытаў

Пошук і выклік дэталяў каштуюць па адным запыце. Пры 20 запытах у хвіліну гэта дзесяць пошукаў назвы ў хвіліну, пры 120 запытах у хвіліну гэта шэсцьдзесят. Трапленне ў edge-кэш усё роўна ўлічваецца, бо праверка ключа і ліміту запытаў адбываецца да кэшу. Трымайце ўласны кэш для паўторных пошукаў і глядзіце на X-RateLimit-Remaining, каб бачыць, колькі запытаў застаецца ў бягучай хвіліне. Калі прыходзіць 429, пачакайце столькі секунд, колькі вызначае Retry-After. Ліміты па тарыфах апісаны на старонцы ліміты запытаў.

Параўнанне

Цэны

Доступ аплачваецца наперад на 1, 3, 6, 12 або 24 месяцы, а за доўгія перыяды даюць зніжку 0, 10, 20, 30 і 40 працэнтаў. Аўтапрадаўжэння і бясплатнага тарыфа няма. Усе тарыфы даюць доступ да ўсіх даных і адрозніваюцца толькі абмежаваннем па частаце: 20, 40 або 120 запытаў у хвіліну. Абярыце тарыф на старонцы цэны і зрабіце першы выклік праз некалькі хвілін.