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

> Эндпоинты жанров и справочников возвращают небольшие списки, которые достаточно загрузить один раз: 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/ru/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`  | строка запроса | один из двух | Ваш ключ. Используйте его или заголовок `Authorization: Bearer`.                                            |
| `language` | строка запроса | нет          | Тег TMDB, например `en-US`, `ru-RU` или `pt-BR`. Названия возвращаются на этом языке. По умолчанию `en-US`. |

### Поля ответа

| Поле            | Тип         | Примечания                                 |
| --------------- | ----------- | ------------------------------------------ |
| `genres`        | массив      | Весь список в одном ответе, без пагинации. |
| `genres[].id`   | целое число | Постоянный ID жанра.                       |
| `genres[].name` | строка      | Название жанра на запрошенном языке.       |

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

```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/ru/discover/), используйте ID сериалов, например `10765` для Sci-Fi и фэнтези.

## Справочники

Эти пути возвращают справочные данные для форм, фильтров и экранов настроек. Все принимают ключ, и ни один не принимает `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`. Логотипы провайдеров загружаются с хоста изображений, см. [API изображений](https://amodb.dev/ru/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/ru/errors/). Лимиты тарифов описаны на странице [лимиты запросов](https://amodb.dev/ru/rate-limits/).

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

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

## Вопросы и ответы

### Меняются ли ID жанров между языками?

Нет. ID остается тем же, переводится только название. Запрашивайте список на языке, который вы показываете, и держите в приложении одну карту ID к названию на каждый язык.

### Используют ли фильмы и сериалы разные ID жанров?

У них общее пространство ID. Оба пути жанров возвращают одни и те же 27 жанров. Фильмы используют ID вроде 28 и 12, а сериалы объединенные ID вроде 10759 для Action and Adventure. Одна карта покрывает оба случая.

### Как отфильтровать сразу по двум жанрам?

Передайте with_genres в discover. Запятая между ID означает все сразу, поэтому 28,12 это Action и Adventure вместе. Вертикальная черта означает любой из них. Для исключения используйте without_genres.

### Нужна ли справочникам пагинация?

Нет. Каждый путь справочника возвращает весь список одним ответом. Загрузите их при запуске и кэшируйте на сутки. Пути configuration кэшируются на edge-серверах на 24 часа.

## Связанные страницы

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

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