# Жанрове и справочни списъци

> Ендпойнтите за жанрове и справочници връщат малки справочни списъци, които зареждате веднъж: 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/bg/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/bg/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/bg/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/bg/errors/). Лимитите на плановете са на страницата [лимити на заявките](https://amodb.dev/bg/rate-limits/).

## Практически бележки

- Зареждайте списъците веднъж на език при старт и ги дръжте в паметта или във файл. Edge кешира пътищата `/configuration` за 24 часа, така че дневно обновяване при вас е достатъчно.
- Пазете в базата id на жанрове, а не имена. Името се променя с езика, id не.
- И двата пътя за жанрове връщат същите 27 записа, така че една карта покрива филми и сериали. Id 10759 и 10762-10768 се появяват само при сериали.
- `with_genres=28,12` в [откриване по филтри](https://amodb.dev/bg/discover/) означава Action и Adventure заедно. `with_genres=28|12` означава някое от двете.
- Имената на жанровете следват параметъра `language`. Таг извън 14-те основни езика от страницата [езици](https://amodb.dev/bg/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/bg/discover/): Discover API със същите филтри като TMDB v3. Списък с филми и сериали по жанр, актьори, компания, ключова дума, година, рейтинг и продължителност със сортиране.
- [API за детайли на филм](https://amodb.dev/bg/movies/): API за детайли на филм със същите пътища и JSON като TMDB v3. Един филм по id, а актьори, рейтинги и настроения през append_to_response, на 14 езика.
- [API за сериали](https://amodb.dev/bg/tv-series/): API за сериали със същите пътища и JSON като TMDB v3. Сериал по id със сезони, мрежи и следващ епизод, плюс възрастови рейтинги и доставчици за гледане.
- [Езици](https://amodb.dev/bg/languages/): amodb връща заглавия, описания и имена на 14 езика. Подайте таг в стил TMDB, например ru-RU или pt-BR, в language; всеки друг таг се заменя с английски.
- [API за изображения и хост за изображения](https://amodb.dev/bg/images-api/): API за изображения на филми с пътища на TMDB v3: списъци с постери, фонови изображения, лога и кадри, после зареждане от img.amodb.dev в 10 размера без ключ.
- [Бърз старт](https://amodb.dev/bg/quickstart/): Първата ви заявка към amodb: вземете ключ, поискайте детайли за филм с curl, JavaScript, Python, PHP или Go и заредете постера от img.amodb.dev. До 2 минути.

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