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

> Ендпоінти жанрів і довідників повертають невеликі списки, які завантажують один раз: id жанрів фільмів і серіалів з назвами 14 мовами, а також країни, мови, посади знімальної групи, вікові рейтинги й стрімінгові провайдери. Вони мають шляхи й структуру TMDB v3, не потребують посторінкової видачі та рідко змінюються, тож кешуйте їх на добу.

## Ендпоінт

`GET /3/genre/movie/list`

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

Відповідь:

```json
{
  "genres": [
    {
      "id": 28,
      "name": "Action"
    },
    {
      "id": 12,
      "name": "Adventure"
    },
    {
      "id": 16,
      "name": "Animation"
    }
  ]
}
```

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

`GET /3/genre/movie/list` повертає всі жанри фільмів у вигляді `id` і `name`. Id це числа, які `genre_ids` містить в елементах списків і яких очікує `with_genres` у [discover](https://amodb.dev/uk/discover/). Назви залежать від параметра `language`.

Приклад завантажує список і будує відповідність id до назви, це перше, що потрібно більшості застосунків.

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

```js
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);
```

```python
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
<?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;
```

```go
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`  | query | одне з двох  | Ваш ключ. Використовуйте його або заголовок `Authorization: Bearer`.                                       |
| `language` | query | ні           | Тег TMDB, наприклад `en-US`, `ru-RU` або `pt-BR`. Назви повертаються цією мовою. За замовчуванням `en-US`. |

### Поля відповіді

| Поле            | Тип     | Примітки                                                  |
| --------------- | ------- | --------------------------------------------------------- |
| `genres`        | array   | Увесь список в одній відповіді, без посторінкової видачі. |
| `genres[].id`   | integer | Стабільний id жанру.                                      |
| `genres[].name` | string  | Назва жанру запитаною мовою.                              |

### Приклад відповіді

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

Відповідь містить 27 жанрів, відсортованих за id. Тут її скорочено до перших 4.

## Id жанрів

Обидва шляхи жанрів повертають ці 27 жанрів, відсортованих за id. Нижче наведено англійські назви. Інші мови повертають ті самі id з перекладеними назвами.

| Id    | Назва              |
| ----- | ------------------ |
| 12    | Adventure          |
| 14    | Fantasy            |
| 16    | Animation          |
| 18    | Drama              |
| 27    | Horror             |
| 28    | Action             |
| 35    | Comedy             |
| 36    | History            |
| 37    | Western            |
| 53    | Thriller           |
| 80    | Crime              |
| 99    | Documentary        |
| 878   | Science Fiction    |
| 9648  | Mystery            |
| 10402 | Music              |
| 10749 | Romance            |
| 10751 | Family             |
| 10752 | War                |
| 10759 | Action & Adventure |
| 10762 | Kids               |
| 10763 | News               |
| 10764 | Reality            |
| 10765 | Sci-Fi & Fantasy   |
| 10766 | Soap               |
| 10767 | Talk               |
| 10768 | War & Politics     |
| 10770 | TV Movie           |

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

`GET /3/genre/tv/list` приймає той самий параметр `language` і повертає ідентичний список, тож одна відповідність id до назви охоплює фільми й серіали. У даних списків id `10759` та від `10762` до `10768` трапляються лише в елементах серіалів, а id на кшталт `28`, `12` і `878` трапляються в елементах фільмів. Коли ви фільтруєте серіали в [discover](https://amodb.dev/uk/discover/), використовуйте id для серіалів, наприклад `10765` для «НФ і фентезі».

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

Ці шляхи повертають довідкові дані для форм, фільтрів і екранів налаштувань. Усі приймають ключ, жоден не приймає `page`.

| Метод і шлях                              | Параметри                  | Кожен елемент або структура                                                |
| ----------------------------------------- | -------------------------- | -------------------------------------------------------------------------- |
| `GET /configuration/countries`            | немає                      | Масив `{ iso_3166_1, english_name, native_name }`                          |
| `GET /configuration/languages`            | немає                      | Масив `{ iso_639_1, english_name, name }`                                  |
| `GET /configuration/primary_translations` | немає                      | Масив із 14 рядків, наприклад `ru-RU`                                      |
| `GET /configuration/jobs`                 | немає                      | Масив `{ department, jobs }`, де `jobs` містить назви посад                |
| `GET /certification/movie/list`           | немає                      | `{ certifications }` за кодом країни, 10 країн                             |
| `GET /certification/tv/list`              | немає                      | `{ certifications }` за кодом країни, один ключ на кожну країну в каталозі |
| `GET /watch/providers/regions`            | `language`                 | `{ results }` з `{ iso_3166_1, english_name, native_name }`                |
| `GET /watch/providers/movie`              | `language`, `watch_region` | `{ results }` з провайдерами                                               |
| `GET /watch/providers/tv`                 | `language`, `watch_region` | `{ results }` з провайдерами                                               |

`/configuration/countries` і `/configuration/languages` ігнорують `language` та завжди повертають ті самі назви. `native_name` у списку регіонів залежить від `language`. amodb не надає `/configuration/timezones`.

Запис вікового рейтингу містить сам рейтинг, його значення та порядок сортування. Записи згруповано за кодом країни, тож один виклик охоплює всі ринки. Список для фільмів містить тексти рейтингів. У списку для серіалів `meaning` це порожній рядок.

```json
{
  "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`. Логотипи провайдерів завантажуються з хоста зображень, див. [зображення](https://amodb.dev/uk/images-api/).

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

## Помилки

| HTTP | status_code | Коли                                                                                               |
| ---- | ----------- | -------------------------------------------------------------------------------------------------- |
| 401  | 7           | Ключ відсутній або неправильний.                                                                   |
| 402  | 36          | Термін дії тарифу закінчився.                                                                      |
| 404  | 34          | Шляху не існує, наприклад `/genre/book/list`.                                                      |
| 405  | 37          | Ви використали метод запису на довідковому шляху.                                                  |
| 429  | 25          | Ви перевищили ліміт запитів на хвилину. Зачекайте стільки секунд, скільки вказано в `Retry-After`. |

Подробиці про кожен код дивіться на сторінці [помилки](https://amodb.dev/uk/errors/). Ліміти тарифів описано на сторінці [ліміти запитів](https://amodb.dev/uk/rate-limits/).

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

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

## Запитання й відповіді

### Чи змінюються id жанрів залежно від мови?

Ні. Id лишається тим самим, перекладається лише назва. Запитуйте список мовою, яку ви показуєте, і тримайте в застосунку одну відповідність id до назви для кожної мови.

### Чи використовують фільми й серіали різні id жанрів?

Вони мають спільний простір id. Обидва шляхи жанрів повертають однакові 27 жанрів. Записи фільмів використовують id на кшталт 28 і 12, а записи серіалів об'єднані id, наприклад 10759 для «Бойовик і пригоди». Одна відповідність охоплює обидва.

### Як відфільтрувати за двома жанрами одночасно?

Передайте with_genres у discover. Кома між id означає всі разом, тож 28,12 це «Бойовик і пригоди» водночас. Вертикальна риска означає будь-який із них. Щоб виключити жанр, використайте without_genres.

### Чи потребують довідкові списки посторінкової видачі?

Ні. Кожен довідковий шлях повертає повний список в одній відповіді. Завантажуйте їх під час запуску й кешуйте на добу. Шляхи configuration кешуються на рівні CDN на 24 години.

## Пов'язані сторінки

- [Discover API](https://amodb.dev/uk/discover/): Discover API з тими самими фільтрами, що й у TMDB v3. Фільми та серіали за жанром, акторами, компанією, роком, рейтингом, тривалістю й провайдером.
- [API деталей фільму](https://amodb.dev/uk/movies/): API деталей фільму з тими самими шляхами та JSON, що в TMDB v3. Отримайте фільм за id, додайте акторів, рейтинги й настрої через append_to_response, 14 мовами.
- [API серіалів](https://amodb.dev/uk/tv-series/): API серіалів з тими самими шляхами та JSON, що в TMDB v3. Отримайте серіал за id із сезонами, телемережами й наступною серією, плюс вікові рейтинги.
- [Мови](https://amodb.dev/uk/languages/): amodb віддає назви, описи та імена 14 мовами. Передайте в language тег у стилі TMDB, наприклад ru-RU або pt-BR; будь-який інший тег переходить на англійську.
- [API зображень і хост зображень](https://amodb.dev/uk/images-api/): API зображень фільмів зі шляхами TMDB v3: списки постерів, фонів, логотипів і кадрів проєкту, а потім завантаження з img.amodb.dev у 10 розмірах без ключа.
- [Швидкий старт](https://amodb.dev/uk/quickstart/): Перший виклик amodb: отримайте ключ, запросіть деталі фільму в curl, JavaScript, Python, PHP чи Go і завантажте постер з img.amodb.dev. Менш ніж за 2 хвилини.

Оновлено: 2026-10-18. Source: https://amodb.dev/uk/genres/