Жанри та довідкові списки

Список жанрів фільмів

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_keyqueryодне з двох
  Ваш ключ. Використовуйте його або заголовок Authorization: Bearer.
• languagequery
  Тег 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 для «НФ і фентезі».

Довідкові списки

Ці шляхи повертають довідкові дані для форм, фільтрів і екранів налаштувань. Усі приймають ключ, жоден не приймає 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. Логотипи провайдерів завантажуються з хоста зображень, див. зображення.

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

Помилки

Подробиці про кожен код дивіться на сторінці помилки. Ліміти тарифів описано на сторінці ліміти запитів.

Практичні поради

• Завантажуйте списки один раз для кожної мови під час запуску й тримайте їх у пам'яті або у файлі. CDN кешує шляхи /configuration на 24 години, тож щоденного оновлення з вашого боку достатньо.
• Зберігайте в базі даних id жанрів, а не назви. Назва змінюється разом з мовою, id ні.
• Обидва шляхи жанрів повертають ті самі 27 записів, тож одна відповідність охоплює фільми й серіали. Id 10759 та від 10762 до 10768 трапляються лише в елементах серіалів.
• with_genres=28,12 у discover означає «Бойовик і пригоди» разом. with_genres=28|12 означає будь-який із двох.
• Назви жанрів залежать від параметра language. Тег поза 14 базовими мовами зі сторінки мови відкочується на англійську, а кілька назв у деяких мовах лишаються англійськими, наприклад 10759 в італійській.