# Жанры і даведачныя спісы

> Эндпоінты жанраў і даведнікаў вяртаюць невялікія даведачныя спісы, якія загружаюцца адзін раз: 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` у [пошуку па фільтрах](https://amodb.dev/be/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`, у запісах фільмаў. Калі вы фільтруеце серыялы ў [пошуку па фільтрах](https://amodb.dev/be/discover/), выкарыстоўвайце id для серыялаў, напрыклад `10765` для Sci-Fi and Fantasy.

## Даведачныя спісы

Гэтыя шляхі вяртаюць даведачныя даныя для формаў, фільтраў і экранаў налад. Усе прымаюць ключ; ніводзін не прымае `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 запісаў ЗША. Спіс для фільмаў ахоплівае 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/be/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/be/errors/). Ліміты планаў на старонцы [ліміты запытаў](https://amodb.dev/be/rate-limits/).

## Практычныя заўвагі

- Загружайце спісы адзін раз на мову пры старце і трымайце ў памяці або ў файле. Edge кэшуе шляхі `/configuration` на 24 гадзіны, таму штодзённага абнаўлення на вашым баку дастаткова.
- Захоўвайце ў базе даных id жанраў, а не назвы. Назва мяняецца ад мовы, id не мяняецца.
- Абодва шляхі жанраў вяртаюць тыя ж 27 запісаў, таму адна карта ахоплівае фільмы і серыялы. Id 10759 і 10762-10768 з’яўляюцца толькі ў запісах серыялаў.
- `with_genres=28,12` у [пошуку па фільтрах](https://amodb.dev/be/discover/) азначае Action і Adventure разам. `with_genres=28|12` азначае любы з іх.
- Назвы жанраў залежаць ад параметра `language`. Тэг па-за 14 базавымі мовамі са старонкі [мовы](https://amodb.dev/be/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.

### Ці патрэбны старонкі для даведачных спісаў?

Не. Кожны шлях даведніка вяртае ўвесь спіс за адзін адказ. Загружайце іх пры старце і кэшуйце на суткі. Шляхі канфігурацыі кэшуюцца на edge на 24 гадзіны.

## Звязаныя старонкі

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

Абноўлена: 2026-10-18. Source: https://amodb.dev/be/genres/