# API kolekcji > Kolekcja grupuje filmy jednej franczyzy, na przykład trylogię lub długą serię filmów. GET /3/collection/{collection_id} zwraca jej nazwę, opis, grafiki i tablicę parts z filmami w kolejności premier. Filmy wskazują z powrotem swoją kolekcję przez belongs_to_collection, więc możesz poruszać się w obu kierunkach. ## Endpoint `GET /3/collection/{collection_id}` ```bash curl "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Odpowiedź: ```json { "id": 10, "name": "Star Wars - Saga", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various characters \"a long time ago in a galaxy far, far away….\"", "poster_path": "/6mHkagjziBPth2Mx0VpEercocm4.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/jKquaxnCRelAbibZVMdTsUEnkKm.jpg", "genre_ids": [ 12, 28, 878 ], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort to take over the galactic Empire. Venturesome Luke Skywalker and dashing captain Han Solo team together with the loveable robot duo R2-D2 and C-3PO to re...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23028, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empire, learns the ways of the Jedi from aging master Yoda. But Darth Vader is more determined than ever to capture Luke. Meanwhile, rebel leader Princess Le...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18993, "media_type": "movie" }, { "adult": false, "backdrop_path": "/ziECpBRIyclmBNaFSWlvCfsKbMD.jpg", "genre_ids": [ 12, 28, 878 ], "id": 1892, "original_language": "en", "original_title": "Return of the Jedi", "overview": "Luke Skywalker leads a mission to rescue his friend Han Solo from the clutches of Jabba the Hutt, the Emperor prepares to crush the Rebellion with a more powerful Death Star, and the Rebel fleet mounts a massive attack on the space station....", "popularity": 26.3255, "poster_path": "/jQYlydvHm3kUix1f8prMucrplhm.jpg", "release_date": "1983-05-25", "title": "Return of the Jedi", "video": false, "vote_average": 7.911, "vote_count": 17442, "media_type": "movie" } ] } ``` ## Pobieranie kolekcji `GET /3/collection/{collection_id}` zwraca jedną franczyzę: jej nazwę, opis, plakat, tło i tablicę `parts`. Każda część to podsumowanie filmu z polami potrzebnymi do karty, więc jedno wywołanie może narysować całą półkę franczyzy. Przykład pobiera kolekcję 10, czyli filmy Star Wars, i wypisuje jej filmy w kolejności premier. ```bash curl -s "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/collection/10?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 collection = await res.json(); console.log(collection.name); for (const p of collection.parts) console.log(p.release_date || 'not dated', p.title); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/collection/10", params={"language": "en-US"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() collection = r.json() print(collection["name"]) for p in collection["parts"]: print(p.get("release_date") or "not dated", p["title"]) ``` ```php 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"); } $collection = json_decode($body, true); echo $collection['name'], PHP_EOL; foreach ($collection['parts'] as $p) { echo $p['release_date'] ?: 'not dated', ' ', $p['title'], PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Collection struct { Name string `json:"name"` Parts []struct { Title string `json:"title"` ReleaseDate string `json:"release_date"` } `json:"parts"` } func main() { url := "https://api.amodb.dev/3/collection/10?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 c Collection if err := json.NewDecoder(res.Body).Decode(&c); err != nil { panic(err) } fmt.Println(c.Name) for _, p := range c.Parts { date := p.ReleaseDate if date == "" { date = "not dated" } fmt.Println(date, p.Title) } } ``` ### Parametry | Parametr | Gdzie | Wymagany | Opis | | --------------- | ----- | ------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `collection_id` | path | tak | Numeryczne ID kolekcji, na przykład `10`. | | `api_key` | query | jeden z dwóch | Twój klucz. Użyj go albo nagłówka `Authorization: Bearer`. | | `language` | query | nie | Jeden z 14 obsługiwanych języków, na przykład `en-US` lub `fr-FR`. Ustawia język tytułu i opisu każdej części. Domyślnie `en-US`. | Własne `name` i `overview` kolekcji przychodzą tak, jak zapisano, i nie zmieniają się z `language`. W niektórych kolekcjach nie są po angielsku. ### Pola odpowiedzi | Pole | Typ | Uwagi | | ---------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------ | | `id` | integer | ID kolekcji. | | `name` | string | Nazwa franczyzy. | | `overview` | string | Krótki opis. Pusty w niektórych kolekcjach. | | `poster_path`, `backdrop_path` | string lub null | Dołącz do `https://img.amodb.dev/t/p/{size}`. Zobacz [obrazy](https://amodb.dev/pl/images-api/). | | `parts` | array | Podsumowania filmów, od najstarszego `release_date`. | | `parts[].id` | integer | ID filmu. Przekaż je do [szczegółów filmu](https://amodb.dev/pl/movies/). | | `parts[].title`, `parts[].original_title` | string | Tytuł zlokalizowany i oryginalny. | | `parts[].overview` | string | Zlokalizowane streszczenie. | | `parts[].release_date` | string | `YYYY-MM-DD` albo pusty ciąg dla filmu bez daty. Takie części są na końcu. | | `parts[].media_type` | string | W kolekcji zawsze `movie`. | | `parts[].genre_ids` | array | Numeryczne ID. Nazwy pochodzą ze strony [gatunki](https://amodb.dev/pl/genres/). | | `parts[].adult`, `parts[].video` | boolean | `adult` jest zawsze `false`, bo tytuły dla dorosłych nie są udostępniane. | | `parts[].original_language` | string | Dwuliterowy kod języka. | | `parts[].popularity` | number | Wskaźnik popularności. | | `parts[].poster_path`, `parts[].backdrop_path` | string lub null | Grafiki filmu. | | `parts[].vote_average`, `parts[].vote_count` | number, integer | Zbiorcza ocena użytkowników. | ### Przykładowa odpowiedź Pokazano dwie z dziewięciu części. ```json { "id": 10, "name": "Star Wars Collection", "overview": "An epic space-opera theatrical film series, which depicts the adventures of various cha...", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg", "parts": [ { "adult": false, "backdrop_path": "/zqkmTXzjkAgXmEWLRsY4UpTWCeo.jpg", "genre_ids": [12, 28, 878], "id": 11, "original_language": "en", "original_title": "Star Wars", "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort...", "popularity": 70.481, "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg", "release_date": "1977-05-25", "title": "Star Wars", "video": false, "vote_average": 8.207, "vote_count": 23025, "media_type": "movie" }, { "adult": false, "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg", "genre_ids": [12, 28, 878], "id": 1891, "original_language": "en", "original_title": "The Empire Strikes Back", "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empi...", "popularity": 29.9034, "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg", "release_date": "1980-05-20", "title": "The Empire Strikes Back", "video": false, "vote_average": 8.393, "vote_count": 18990, "media_type": "movie" } ] } ``` Długie ciągi są na tej stronie skrócone przez `...`. Prawdziwa odpowiedź zawiera pełny tekst. ## Znajdź kolekcję filmu Rzadko zaczynasz od ID kolekcji. Zaczynasz od filmu, a rekord [szczegółów filmu](https://amodb.dev/pl/movies/) mówi, gdzie należy. Pole `belongs_to_collection` to obiekt z `id`, `name`, `poster_path` i `backdrop_path`. Ma wartość `null` dla filmu, który nie jest częścią franczyzy, na przykład dla filmu 550. ```json { "id": 11, "title": "Star Wars", "belongs_to_collection": { "id": 10, "name": "Star Wars Collection", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg" } } ``` Poniższy przykład podąża za tym linkiem od filmu do jego franczyzy w dwóch żądaniach. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function getJson(path) { const res = await fetch(`${base}${path}`, { headers }); if (!res.ok) throw new Error(`${path} returned ${res.status}`); return res.json(); } const movie = await getJson('/movie/11'); if (movie.belongs_to_collection) { const collection = await getJson(`/collection/${movie.belongs_to_collection.id}`); console.log(movie.title, 'is one of', collection.parts.length, 'films in', collection.name); } ``` ## Grafiki i wyszukiwanie Plakat i tło franczyzy to pola `poster_path` i `backdrop_path` rekordu kolekcji. Adres pliku zbuduj z nich tak, jak opisuje strona [obrazy](https://amodb.dev/pl/images-api/). amodb nie udostępnia ścieżek `/collection/{collection_id}/images` i `/collection/{collection_id}/translations`, więc kolekcja nie ma listy alternatywnych plakatów ani wierszy językowych. Tytuły części zależą za to od parametru `language`, a ścieżki zwracające wiersze językowe omawia strona [tłumaczenia](https://amodb.dev/pl/translations/). Aby znaleźć kolekcję po nazwie, użyj `GET /3/search/collection?query=matrix`, opisanego na stronie [wyszukiwanie](https://amodb.dev/pl/search/). Każdy wynik ma `id`, `name`, `overview`, `poster_path`, `backdrop_path`, `original_language`, `original_name` i `adult`. ## Błędy | HTTP | status_code | Kiedy | | ---- | ----------- | ----------------------------------------------------------------------------------- | | 401 | 7 | Brakuje klucza lub jest błędny. | | 402 | 36 | Okres planu dobiegł końca. | | 404 | 34 | Brak kolekcji o tym ID albo ID nie jest liczbą. | | 405 | 37 | Użyto metody zapisu na ścieżce kolekcji. | | 429 | 25 | Przekroczono limit żądań na minutę. Poczekaj tyle sekund, ile podaje `Retry-After`. | Pełna lista jest na stronie [błędy](https://amodb.dev/pl/errors/), a limity planów na stronie [limity żądań](https://amodb.dev/pl/rate-limits/). ## Praktyczne uwagi - Kolekcje grupują tylko filmy. Film ma co najwyżej jeden obiekt `belongs_to_collection`, więc jeden film należy do jednej franczyzy. - Części przychodzą w kolejności premier. Filmy z pustą datą są na końcu, więc oznacz je jako jeszcze bez daty. - Rekord kolekcji jest w cache na edge przez 6 godzin jak inne szczegóły, więc strona franczyzy może używać jednej odpowiedzi przez ten czas. - Część niesie tylko pola podsumowania. Czas trwania, obsadę i oceny pobieraj dla każdego filmu przez [szczegóły filmu](https://amodb.dev/pl/movies/), gdy użytkownik go otworzy. - Jako klucza filmu używaj `parts[].id`, a nie jego pozycji we franczyzie. Kolejność i daty są z czasem poprawiane. - Zanim pokażesz `name`, sprawdź, czy jest w twoim języku wyświetlania. Niektóre kolekcje mają nazwę w innym języku, a `language` jej nie zmienia. ## Pytania i odpowiedzi ### Jak sprawdzić, czy film należy do kolekcji? Odczytaj belongs_to_collection w rekordzie szczegółów filmu. To obiekt z id, name, poster_path i backdrop_path albo null, gdy film stoi samodzielnie. Użyj tego id w ścieżce kolekcji. ### Czy części są zwracane w kolejności premier? Tak. Tablica parts jest uporządkowana od najstarszego według release_date. Film bez daty ma puste release_date i trafia na koniec, więc oznacz go jako jeszcze bez daty. ### Czy seriale mają kolekcje? Nie. Kolekcje grupują filmy. Serial opisują jego sezony i odcinki, udokumentowane na stronach seriali oraz sezonów i odcinków. ### Jak wyszukać kolekcję po nazwie? Użyj ścieżki wyszukiwania kolekcji, na przykład /3/search/collection?query=matrix. Zwraca listę z paginacją z id, name i grafikami. Weź id i wywołaj endpoint kolekcji, by dostać części. ## Powiązane strony - [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 wyszukiwania](https://amodb.dev/pl/search/): API wyszukiwania z tymi samymi ścieżkami i JSON co TMDB v3. Znajdź filmy, seriale, osoby, kolekcje, firmy i słowa kluczowe po tekście, z filtrem roku. - [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. - [API tłumaczeń](https://amodb.dev/pl/translations/): API tłumaczeń filmów ze ścieżkami TMDB v3: odczytaj wszystkie zapisane tytuły, opisy i slogany filmu, serialu lub odcinka we wszystkich językach naraz. - [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. - [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/collections/