Жанры и справочники

Получение списка жанров фильмов

GET /3/genre/movie/list возвращает каждый жанр фильмов в виде id и name. ID это числа, которые genre_ids содержит в элементах списков и которые with_genres ожидает в discover. Названия зависят от параметра language.

Пример загружает список и строит карту ID к названию, это первое, что нужно большинству приложений.

curl -s "https://api.amodb.dev/3/genre/movie/list?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/genre/movie/list?language=en-US';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const { genres } = await res.json();
const names = new Map(genres.map((g) => [g.id, g.name]));
console.log(names.get(878), names.size);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/genre/movie/list",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
names = {g["id"]: g["name"] for g in r.json()["genres"]}
print(names[878], len(names))

<?php
$url = 'https://api.amodb.dev/3/genre/movie/list?language=en-US';
$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");
}
$names = [];
foreach (json_decode($body, true)['genres'] as $g) {
    $names[$g['id']] = $g['name'];
}
echo $names[878], ' ', count($names), PHP_EOL;

package main

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

type Genres struct {
	Genres []struct {
		ID   int    `json:"id"`
		Name string `json:"name"`
	} `json:"genres"`
}

func main() {
	url := "https://api.amodb.dev/3/genre/movie/list?language=en-US"
	req, _ := http.NewRequest("GET", url, 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 g Genres
	if err := json.NewDecoder(res.Body).Decode(&g); err != nil {
		panic(err)
	}
	names := map[int]string{}
	for _, x := range g.Genres {
		names[x.ID] = x.Name
	}
	fmt.Println(names[878], len(names))
}

Параметры

• api_keyстрока запросаодин из двух
  Ваш ключ. Используйте его или заголовок Authorization: Bearer.
• languageстрока запроса
  Тег TMDB, например en-US, ru-RU или pt-BR. Названия возвращаются на этом языке. По умолчанию en-US.

Поля ответа

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

{
  "genres": [
    { "id": 12, "name": "Adventure" },
    { "id": 14, "name": "Fantasy" },
    { "id": 16, "name": "Animation" },
    { "id": 18, "name": "Drama" }
  ]
}

Ответ содержит 27 жанров, отсортированных по ID. Здесь он сокращен до первых 4.

ID жанров

Оба пути жанров возвращают эти 27 жанров, отсортированных по ID. Ниже указаны английские названия. Другие языки возвращают те же ID с переведенными названиями.

Список жанров сериалов

GET /3/genre/tv/list принимает тот же параметр language и возвращает такой же список, поэтому одна карта ID к названию покрывает и фильмы, и сериалы. В данных списков ID 10759 и с 10762 по 10768 встречаются только у сериалов, а ID вроде 28, 12 и 878 встречаются у фильмов. Когда вы фильтруете сериалы в discover, используйте ID сериалов, например 10765 для Sci-Fi и фэнтези.

Справочники

Эти пути возвращают справочные данные для форм, фильтров и экранов настроек. Все принимают ключ, и ни один не принимает page.

/configuration/countries и /configuration/languages игнорируют language и всегда возвращают одни и те же названия. native_name в списке регионов зависит от language. amodb не предоставляет /configuration/timezones.

Запись сертификации содержит рейтинг, его значение и порядок сортировки. Записи сгруппированы по коду страны, поэтому один вызов охватывает все рынки. Список фильмов содержит тексты рейтингов. В списке сериалов meaning это пустая строка.

{
  "certifications": {
    "US": [
      { "certification": "PG", "meaning": "Some material may not be suitable for children under 10.", "order": 3 },
      { "certification": "R", "meaning": "Under 17 requires accompanying parent or adult guardian.", "order": 5 }
    ]
  }
}

Пример сокращен до 2 из 6 записей для US. Список фильмов охватывает AU, BR, CA, DE, ES, FR, GB, IT, RU и US.

Запись провайдера содержит provider_id, provider_name, logo_path, display_priority и display_priorities, то есть карту кода страны к приоритету. Без watch_region вы получаете всех провайдеров. С watch_region=US остаются только провайдеры, которые работают в этой стране. Неизвестный регион возвращает пустой массив results. Передавайте код из /watch/providers/regions. Логотипы провайдеров загружаются с хоста изображений, см. API изображений.

{
  "display_priorities": { "AT": 1, "DE": 1, "GB": 1, "JP": 1, "US": 3 },
  "display_priority": 3,
  "logo_path": "/gMZdpavHmxFNnLpMHwVxfqeux2g.png",
  "provider_name": "Amazon Prime Video",
  "provider_id": 9
}

Это одна запись из /watch/providers/movie?watch_region=US.

Ошибки

Подробности по каждому коду описаны на странице ошибки. Лимиты тарифов описаны на странице лимиты запросов.

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

• Загружайте списки один раз для каждого языка при запуске и храните в памяти или в файле. Edge-серверы кэшируют пути /configuration на 24 часа, поэтому достаточно обновлять их у себя раз в сутки.
• Храните в базе ID жанров, а не названия. Название меняется с языком, ID нет.
• Оба пути жанров возвращают одни и те же 27 записей, поэтому одна карта покрывает фильмы и сериалы. ID 10759 и с 10762 по 10768 встречаются только у сериалов.
• with_genres=28,12 в discover означает Action и Adventure вместе. with_genres=28|12 означает любой из них.
• Названия жанров зависят от параметра language. Тег вне 14 базовых языков из раздела языки заменяется на английский, а несколько названий остаются на английском в некоторых языках, например 10759 в итальянском.