API переводов

Переводы фильма

GET /3/movie/{movie_id}/translations возвращает по одной строке на каждый язык, для которого у фильма есть текст. В каждой строке есть объект data с переведенными полями. У вызова нет параметра языка, потому что смысл в том, чтобы увидеть все языки сразу.

Пример находит русскую строку и выводит ее название и начало описания.

curl -s "https://api.amodb.dev/3/movie/550/translations" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/movie/550/translations';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { translations } = await res.json();
const ru = translations.find((t) => t.iso_639_1 === 'ru');
console.log(ru ? `${ru.data.title}: ${ru.data.overview.slice(0, 80)}` : 'no Russian row');

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/550/translations",
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
ru = next((t for t in r.json()["translations"] if t["iso_639_1"] == "ru"), None)
print(f"{ru['data']['title']}: {ru['data']['overview'][:80]}" if ru else "no Russian row")

<?php
$ch = curl_init('https://api.amodb.dev/3/movie/550/translations');
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");
}
foreach (json_decode($body, true)['translations'] as $t) {
    if ($t['iso_639_1'] === 'ru') {
        echo $t['data']['title'], ': ', mb_substr($t['data']['overview'], 0, 80), PHP_EOL;
        exit;
    }
}
echo 'no Russian row', PHP_EOL;

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type Translations struct {
	Translations []struct {
		ISO6391 string `json:"iso_639_1"`
		Data    struct {
			Title    string `json:"title"`
			Overview string `json:"overview"`
		} `json:"data"`
	} `json:"translations"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/550/translations", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var t Translations
	if err := json.NewDecoder(res.Body).Decode(&t); err != nil {
		panic(err)
	}
	for _, row := range t.Translations {
		if row.ISO6391 == "ru" {
			text := []rune(row.Data.Overview)
			if len(text) > 80 {
				text = text[:80]
			}
			fmt.Printf("%s: %s\n", row.Data.Title, string(text))
			return
		}
	}
	fmt.Println("no Russian row")
}

Параметры

• movie_idпутьобязателен
  Числовой id фильма, например 550.
• api_keyqueryодно из двух
  Ваш ключ. Используйте его или заголовок Authorization: Bearer.

Поля ответа

Пример ответа

Показаны две строки из 50, описания сокращены.

{
  "id": 550,
  "translations": [
    {
      "iso_3166_1": "US",
      "iso_639_1": "en",
      "name": "English",
      "english_name": "English",
      "data": {
        "title": "Fight Club",
        "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy....",
        "homepage": "https://www.20thcenturystudios.com/movies/fight-club",
        "tagline": "Mischief. Mayhem. Soap.",
        "runtime": 0
      }
    },
    {
      "iso_3166_1": "RU",
      "iso_639_1": "ru",
      "name": "Русский",
      "english_name": "Russian",
      "data": {
        "title": "Бойцовский клуб",
        "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажд...",
        "homepage": "https://www.20thcenturystudios.com/movies/fight-club",
        "tagline": "«Интриги. Хаос. Мыло»",
        "runtime": 0
      }
    }
  ]
}

В amodb runtime в строке перевода всегда равен 0. Продолжительность читайте из записи деталей фильма.

Эндпоинты переводов и их ключи данных

У всех путей общая база https://api.amodb.dev/3. Каждый возвращает id и массив translations со строками описанной выше формы. Меняются только ключи внутри data.

У записей сериалов примерно столько же языков, сколько у фильмов. Строки серий охватывают только обслуживаемые языки, для которых у серии есть текст: от 2 до 14 в проверенных примерах. Отсутствующий ключ считайте пустым значением и игнорируйте незнакомые ключи. Родительские записи описаны в разделе сериалы.

amodb не предоставляет переводы для людей и коллекций. Биография человека следует параметру language вызова деталей человека, а описание коллекции приходит в том виде, в каком хранится.

Запасной язык при отсутствии текста

Название может быть на 14 языках и все же иметь пустое описание на том, который выбрал пользователь. Пройдите по цепочке языков, возьмите первое непустое значение и запомните, из какого языка оно пришло.

function pickText(translations, wanted, field) {
  for (const code of [...wanted, 'en']) {
    const row = translations.find((t) => t.iso_639_1 === code);
    const value = row?.data?.[field];
    if (value) return { code, value };
  }
  return null;
}

// Prefer Ukrainian, then Russian, then English.
// const hit = pickText(translations, ['uk', 'ru'], 'overview');

Для сериала передайте 'name' в качестве поля вместо 'title'. Отмечайте в интерфейсе текст из запасного языка, чтобы пользователь понимал, почему украинская страница показывает английский синопсис.

Переводы или параметр language

Теги, которые принимает language, смотрите на странице языки. Любой другой тег в вызове деталей откатывается на английский.

Ошибки

Несуществующий id фильма или сериала на этом пути не считается ошибкой: ответ 200 с "translations": [], тогда как путь деталей отвечает 404. Подробнее: ошибки и лимиты запросов.

Практические заметки

• Один вызов заменяет до 14 вызовов деталей. Используйте его, когда нужно больше двух языков одного названия.
• Строки отсортированы по коду языка, а это не порядок приоритета. Выбирайте строки по iso_639_1, а не по позиции в массиве.
• Вызовы типа деталей кэшируются на CDN на 6 часов, поэтому клиентский кэш такой же длины ничего не стоит по свежести данных.
• Оригинальные названия в других письменностях, например японской или корейской, всегда доступны в original_title и original_name записи деталей.
• Чтобы добавить переводы к вызову деталей, передайте append_to_response=translations и читайте тот же массив из ответа. Это работает для фильмов, сериалов и серий. У добавленного блока нет id.