Многоязычный API метаданных фильмов

Данные о фильмах на 14 языках

GET /3/movie/{movie_id}?language=ru-RU возвращает название, описание, слоган и названия жанров на русском. Параметр language принимает теги TMDB, например ru-RU или pt-BR, и работает на каждом эндпоинте, который возвращает текст. Идентификаторы остаются одинаковыми на всех языках, поэтому одной строки в вашей базе данных хватает для всех.

Вы получаете 14 языков на одном ключе, original_title каждого фильма, эндпоинт переводов со всеми языками тайтла и локализованные названия жанров. Полный список приведен на странице языки.

14 поддерживаемых языков

Любой другой тег откатывается на en. Японский и корейский не поддерживаются как языки интерфейса. Их оригинальные названия по-прежнему приходят в original_title для фильмов и в original_name для сериалов.

Какие данные вы получаете

Начало работы за 3 шага

1. Выберите тариф на странице цены. Число языков от тарифа не зависит, меняется только частота запросов.
2. Создайте ключ в личном кабинете.
3. Вызовите любой эндпоинт с тегом language и передайте ключ как api_key или в заголовке Bearer.

Пример запроса

Пример на bash печатает название Fight Club (ID 550) на трех языках. Для вывода одного поля используется jq. Пример на PHP запрашивает белорусский и откатывается на английский, если описание пустое.

for lang in en-US ru-RU he-IL; do
  curl -s "https://api.amodb.dev/3/movie/550?language=$lang" \
    -H "Authorization: Bearer $AMODB_KEY" | jq -r '.title'
done

<?php
function amodb(string $path, array $query = []): array
{
    $url = 'https://api.amodb.dev/3' . $path . '?' . http_build_query($query);
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status !== 200) {
        throw new RuntimeException("amodb returned $status");
    }
    return json_decode($body, true);
}

function localizedMovie(int $id, string $lang): array
{
    $movie = amodb("/movie/$id", ['language' => $lang]);
    $movie['text_language'] = $lang;
    if (trim($movie['overview'] ?? '') === '') {
        $fallback = amodb("/movie/$id", ['language' => 'en-US']);
        $movie['overview'] = $fallback['overview'] ?? '';
        $movie['text_language'] = 'en-US';
    }
    return $movie;
}

$movie = localizedMovie(550, 'be-BY');
echo $movie['title'], ' (', $movie['original_title'], ')', PHP_EOL;
echo '[', $movie['text_language'], '] ', $movie['overview'], PHP_EOL;

Ответ для language=ru-RU, сокращенный до нескольких полей. Ключ text_language в примере на PHP добавляет ваш код, а не API.

{
  "genres": [
    {
      "id": 18,
      "name": "драма"
    },
    {
      "id": 53,
      "name": "триллер"
    }
  ],
  "id": 550,
  "original_language": "en",
  "original_title": "Fight Club",
  "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажды в очередной командировке он...",
  "poster_path": "/66RvLrRJTm4J8l3uHXWF09AICol.jpg",
  "tagline": "«Интриги. Хаос. Мыло»",
  "title": "Бойцовский клуб"
}

Откат на английский, когда поле пустое

Не у каждого тайтла есть текст на каждом языке. overview может прийти пустым, если перевода нет, а title или tagline может прийти на английском. API не выдумывает текст. Используйте фиксированный порядок, чтобы на странице всегда было что показать:

1. Запросите язык, который вы показываете.
2. Если поле пустое, запросите тот же ID с en-US или возьмите английскую запись из списка переводов.
3. Если название пустое, покажите original_title.
4. Сохраняйте, на каком языке пришло каждое поле, чтобы позже повторить запрос.

Edge-кэш хранит по одной копии на каждый язык для каждого кэшируемого пути, поэтому английский запасной вариант для популярного тайтла обычно отдается из кэша.

Список всех переводов тайтла

GET /3/movie/{movie_id}/translations возвращает массив translations, по одной записи на каждый язык, для которого есть данные. Список может быть длиннее 14 поддерживаемых языков: у Fight Club 50 записей. Используйте его для переключателя языков или чтобы хранить все тексты тайтла в одной строке.

Такой же эндпоинт есть для сериалов и серий. Записи сериалов содержат data.name и не содержат runtime, а записи серий содержат только name и overview. Сезоны отвечают пустым списком, а у людей и коллекций эндпоинта переводов нет. Подробности на странице переводы. Один запрос переводов заменяет до 14 запросов деталей, когда нужны сразу все языки.

Постеры и видео по языку

Изображения и видео несут собственные языковые теги в iso_639_1. На эндпоинтах изображений передайте список через запятую и добавьте null для элементов без языка, например постеров без текста. Ответ содержит подходящие элементы, поэтому ранжируйте их в своем коде.

Эндпоинты видео возвращают все языки в одном ответе и игнорируют include_video_language, поэтому фильтруйте по iso_639_1 самостоятельно. Размеры и CDN описаны на странице API изображений.

Иврит и текст справа налево

Иврит единственный из 14 языков с письмом справа налево. Обрабатывайте его на странице, а не в данных:

• Задайте lang="he" и dir="rtl" для элемента с текстом.
• Оберните латинские названия внутри текста на иврите в элемент <bdi>, чтобы знаки препинания не прыгали на другую сторону.
• Используйте логические свойства CSS, например margin-inline-start, вместо left и right.

Сравнение

Цены

Набор языков одинаков на каждом тарифе, поэтому вы платите только за частоту запросов и срок. Покупайте 1, 3, 6, 12 или 24 месяца по предоплате: на более длинные периоды скидка составляет 0, 10, 20, 30 или 40 процентов, автоматического продления нет. Тарифы на 20, 40 и 120 запросов в минуту включают все языки и все эндпоинты. Сайту на пяти языках нужно до пяти запросов деталей на тайтл, а повторные запросы 6 часов отдаются из edge-кэша. Бесплатного тарифа нет. См. цены.