# Gatunki i słowniki

> Endpointy gatunków i słowników zwracają małe listy referencyjne, które wystarczy pobrać raz: ID gatunków filmów i seriali z nazwami w 14 językach, a także kraje, języki, stanowiska ekipy, klasyfikacje wiekowe i dostawców streamingu. Używają ścieżek i kształtów TMDB v3, nie mają paginacji i rzadko się zmieniają, więc zapisuj je w cache na dobę.

## Endpoint

`GET /3/genre/movie/list`

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

Odpowiedź:

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

## Pobieranie listy gatunków filmowych

`GET /3/genre/movie/list` zwraca każdy gatunek filmowy jako `id` i `name`. ID to liczby, które `genre_ids` niesie na pozycjach list i których oczekuje `with_genres` w [discover](https://amodb.dev/pl/discover/). Nazwy zależą od parametru `language`.

Przykład pobiera listę i buduje mapę ID na nazwę, czyli pierwszą rzecz, jakiej potrzebuje większość aplikacji.

```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))
}
```

### Parametry

| Parametr   | Gdzie | Wymagany      | Opis                                                                                                   |
| ---------- | ----- | ------------- | ------------------------------------------------------------------------------------------------------ |
| `api_key`  | query | jeden z dwóch | Twój klucz. Użyj go albo nagłówka `Authorization: Bearer`.                                             |
| `language` | query | nie           | Tag TMDB, na przykład `en-US`, `ru-RU` lub `pt-BR`. Nazwy są zwracane w tym języku. Domyślnie `en-US`. |

### Pola odpowiedzi

| Pole            | Typ     | Uwagi                                          |
| --------------- | ------- | ---------------------------------------------- |
| `genres`        | array   | Cała lista w jednej odpowiedzi, bez paginacji. |
| `genres[].id`   | integer | Stałe ID gatunku.                              |
| `genres[].name` | string  | Nazwa gatunku w żądanym języku.                |

### Przykładowa odpowiedź

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

Odpowiedź zawiera 27 gatunków posortowanych według ID. Ta jest przycięta do pierwszych 4.

## ID gatunków

Obie ścieżki gatunków zwracają te 27 gatunków posortowanych według ID. Poniżej są nazwy angielskie. Inne języki zwracają te same ID z przetłumaczonymi nazwami.

| ID    | Nazwa              |
| ----- | ------------------ |
| 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           |

## Lista gatunków seriali

`GET /3/genre/tv/list` przyjmuje ten sam parametr `language` i zwraca identyczną listę, więc jedna mapa ID na nazwę obejmuje filmy i seriale. W danych list ID `10759` oraz od `10762` do `10768` występują tylko na pozycjach serialowych, a ID takie jak `28`, `12` i `878` na filmowych. Gdy filtrujesz seriale w [discover](https://amodb.dev/pl/discover/), użyj ID serialowych, na przykład `10765` dla Sci-Fi i fantasy.

## Słowniki

Te ścieżki zwracają dane referencyjne dla formularzy, filtrów i ekranów ustawień. Wszystkie wymagają klucza, żadna nie przyjmuje `page`.

| Metoda i ścieżka                          | Parametry                  | Pozycja lub kształt                                                    |
| ----------------------------------------- | -------------------------- | ---------------------------------------------------------------------- |
| `GET /configuration/countries`            | brak                       | Tablica `{ iso_3166_1, english_name, native_name }`                    |
| `GET /configuration/languages`            | brak                       | Tablica `{ iso_639_1, english_name, name }`                            |
| `GET /configuration/primary_translations` | brak                       | Tablica 14 ciągów, na przykład `ru-RU`                                 |
| `GET /configuration/jobs`                 | brak                       | Tablica `{ department, jobs }`, gdzie `jobs` zawiera nazwy stanowisk   |
| `GET /certification/movie/list`           | brak                       | `{ certifications }` według kodu kraju, 10 krajów                      |
| `GET /certification/tv/list`              | brak                       | `{ certifications }` według kodu kraju, jeden klucz na kraj w katalogu |
| `GET /watch/providers/regions`            | `language`                 | `{ results }` z pozycjami `{ iso_3166_1, english_name, native_name }`  |
| `GET /watch/providers/movie`              | `language`, `watch_region` | `{ results }` z dostawcami                                             |
| `GET /watch/providers/tv`                 | `language`, `watch_region` | `{ results }` z dostawcami                                             |

`/configuration/countries` i `/configuration/languages` ignorują `language` i zawsze zwracają te same nazwy. `native_name` na liście regionów zależy od `language`. amodb nie udostępnia `/configuration/timezones`.

Pozycja klasyfikacji wiekowej podaje oznaczenie, jego znaczenie i kolejność sortowania. Pozycje są pogrupowane według kodu kraju, więc jedno wywołanie obejmuje wszystkie rynki. Lista filmowa zawiera teksty klasyfikacji. Na liście seriali `meaning` jest pustym ciągiem.

```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 }
    ]
  }
}
```

Przykład jest przycięty do 2 z 6 pozycji dla USA. Lista filmowa obejmuje AU, BR, CA, DE, ES, FR, GB, IT, RU i US.

Pozycja dostawcy ma `provider_id`, `provider_name`, `logo_path`, `display_priority` i `display_priorities`, czyli mapę kodu kraju na priorytet. Bez `watch_region` dostaniesz wszystkich dostawców. Z `watch_region=US` zostają tylko dostawcy obsługujący ten kraj. Nieznany region zwraca pustą tablicę `results`. Podaj kod z `/watch/providers/regions`. Loga dostawców ładują się z hosta obrazów, zobacz [obrazy](https://amodb.dev/pl/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
}
```

To jedna pozycja z `/watch/providers/movie?watch_region=US`.

## Błędy

| HTTP | status_code | Kiedy                                                                               |
| ---- | ----------- | ----------------------------------------------------------------------------------- |
| 401  | 7           | Brakuje klucza lub jest błędny.                                                     |
| 402  | 36          | Okres planu dobiegł końca.                                                          |
| 404  | 34          | Ścieżka nie istnieje, na przykład `/genre/book/list`.                               |
| 405  | 37          | Użyto metody zapisu na ścieżce słownika.                                            |
| 429  | 25          | Przekroczono limit żądań na minutę. Poczekaj tyle sekund, ile podaje `Retry-After`. |

Szczegóły każdego kodu są na stronie [błędy](https://amodb.dev/pl/errors/). Limity planów są na stronie [limity żądań](https://amodb.dev/pl/rate-limits/).

## Praktyczne uwagi

- Pobierz listy raz dla każdego języka przy starcie i trzymaj je w pamięci lub w pliku. Edge zapisuje ścieżki `/configuration` w cache na 24 godziny, więc wystarczy odświeżać je u siebie raz dziennie.
- W bazie danych zapisuj ID gatunków, nie nazwy. Nazwa zmienia się z językiem, ID nie.
- Obie ścieżki gatunków zwracają te same 27 pozycji, więc jedna mapa obejmuje filmy i seriale. ID 10759 oraz od 10762 do 10768 występują tylko na pozycjach serialowych.
- `with_genres=28,12` w [discover](https://amodb.dev/pl/discover/) oznacza akcję i przygodę razem. `with_genres=28|12` oznacza dowolny z nich.
- Nazwy gatunków zależą od parametru `language`. Tag spoza 14 języków bazowych ze strony [języki](https://amodb.dev/pl/languages/) wraca do angielskiego, a kilka nazw w niektórych językach pozostaje po angielsku, na przykład `10759` po włosku.

## Pytania i odpowiedzi

### Czy ID gatunków zmieniają się między językami?

Nie. ID pozostaje takie samo, tłumaczona jest tylko nazwa. Pobierz listę w języku, który wyświetlasz, a w aplikacji trzymaj po jednej mapie ID na nazwę dla każdego języka.

### Czy filmy i seriale używają różnych ID gatunków?

Dzielą jedną przestrzeń ID. Obie ścieżki gatunków zwracają te same 27 gatunków. Pozycje filmowe używają ID takich jak 28 i 12, a serialowe połączonych ID, na przykład 10759 dla Akcji i przygody. Jedna mapa obejmuje oba typy.

### Jak filtrować po dwóch gatunkach naraz?

Przekaż with_genres do discover. Przecinek między ID oznacza wszystkie z nich, więc 28,12 to akcja i przygoda razem. Pionowa kreska oznacza dowolny z nich. Do wykluczania użyj without_genres.

### Czy słowniki wymagają paginacji?

Nie. Każda ścieżka słownika zwraca całą listę w jednej odpowiedzi. Pobierz je przy starcie i zapisz w cache na dobę. Ścieżki configuration są przechowywane w cache na edge przez 24 godziny.

## Powiązane strony

- [Discover API](https://amodb.dev/pl/discover/): Discover API z tymi samymi filtrami co TMDB v3. Wypisuj filmy i seriale według gatunku, obsady, firmy, słowa kluczowego, roku, oceny, czasu trwania i dostawcy.
- [API szczegółów filmu](https://amodb.dev/pl/movies/): API szczegółów filmu z tymi samymi ścieżkami i JSON co TMDB v3. Pobierz film po ID, dołącz obsadę, oceny i nastroje przez append_to_response, 14 języków.
- [API szczegółów serialu](https://amodb.dev/pl/tv-series/): API szczegółów serialu z tymi samymi ścieżkami i JSON co TMDB v3. Serial po ID z sezonami, sieciami, klasyfikacją wiekową i dostawcami streamingu.
- [Języki](https://amodb.dev/pl/languages/): amodb serwuje tytuły, opisy i nazwy w 14 językach. Podaj tag w stylu TMDB, np. ru-RU lub pt-BR, w language; każdy inny tag wraca do angielskiego.
- [API obrazów i host obrazów](https://amodb.dev/pl/images-api/): API obrazów filmów ze ścieżkami TMDB v3: wypisz plakaty, tła, loga i kadry każdego tytułu, a potem ładuj je z img.amodb.dev w 10 rozmiarach bez klucza.
- [Szybki start](https://amodb.dev/pl/quickstart/): Pierwsze wywołanie amodb: zdobądź klucz, pobierz szczegóły filmu w curl, JavaScript, Python, PHP lub Go, potem załaduj plakat z img.amodb.dev. Poniżej 2 minut.

Zaktualizowano: 2026-10-18. Source: https://amodb.dev/pl/genres/