# API калекцый > Калекцыя аб’ядноўвае фільмы адной франшызы, напрыклад трылогію або доўгі цыкл фільмаў. GET /3/collection/{collection_id} вяртае яе назву, апісанне, афармленне і масіў parts з фільмамі ў парадку выхаду. Фільмы спасылаюцца на сваю калекцыю праз belongs_to_collection, таму можна рухацца ў абодва бакі: ад фільма да франшызы і назад. ## Эндпоінт `GET /3/collection/{collection_id}` ```bash curl "https://api.amodb.dev/3/collection/10?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Адказ: ```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" } ] } ``` ## Атрыманне калекцыі `GET /3/collection/{collection_id}` вяртае адну франшызу: назву, апісанне, постэр, фонавую выяву і масіў `parts`. Кожная частка ёсць кароткім апісаннем фільма з палямі, патрэбнымі для карткі, таму адзін выклік можа намаляваць цэлую паліцу франшызы. У прыкладзе загружаецца калекцыя 10, фільмы Star Wars, і яе фільмы друкуюцца ў парадку выхаду. ```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) } } ``` ### Параметры | Параметр | Дзе | Абавязковы | Апісанне | | --------------- | ----- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `collection_id` | шлях | так | Лікавы id калекцыі, напрыклад `10`. | | `api_key` | запыт | адзін з двух | Ваш ключ. Выкарыстоўвайце яго або загаловак `Authorization: Bearer`. | | `language` | запыт | не | Адна з 14 падтрымліваных моў, напрыклад `en-US` або `fr-FR`. Задае мову назвы і апісання кожнай часткі. Па змаўчанні `en-US`. | Уласныя `name` і `overview` калекцыі прыходзяць у тым выглядзе, як захаваны, і не змяняюцца ад `language`. Для некаторых калекцый яны не па-англійску. ### Палі адказу | Поле | Тып | Заўвагі | | ---------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------- | | `id` | цэлы лік | Id калекцыі. | | `name` | радок | Назва франшызы. | | `overview` | радок | Кароткае апісанне. Для некаторых калекцый пусты. | | `poster_path`, `backdrop_path` | радок або null | Дадайце да `https://img.amodb.dev/t/p/{size}`. Гл. [выявы](https://amodb.dev/be/images-api/). | | `parts` | масіў | Кароткія апісанні фільмаў, самы стары `release_date` першым. | | `parts[].id` | цэлы лік | Id фільма. Перадайце яго ў [дэталі фільма](https://amodb.dev/be/movies/). | | `parts[].title`, `parts[].original_title` | радок | Лакалізаваная і арыгінальная назва. | | `parts[].overview` | радок | Лакалізаваны сюжэт. | | `parts[].release_date` | радок | `YYYY-MM-DD` або пусты радок для фільма без даты. Такія часткі ідуць апошнімі. | | `parts[].media_type` | радок | У калекцыі заўсёды `movie`. | | `parts[].genre_ids` | масіў | Лікавыя id. Назвы бярыце са старонкі [жанры](https://amodb.dev/be/genres/). | | `parts[].adult`, `parts[].video` | лагічнае значэнне | `adult` заўсёды `false`, бо фільмы для дарослых не вяртаюцца. | | `parts[].original_language` | радок | Двухлітарны код мовы. | | `parts[].popularity` | лік | Значэнне папулярнасці. | | `parts[].poster_path`, `parts[].backdrop_path` | радок або null | Афармленне фільма. | | `parts[].vote_average`, `parts[].vote_count` | лік, цэлы лік | Зводная ацэнка карыстальнікаў. | ### Прыклад адказу Паказаны дзве з дзевяці частак. ```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" } ] } ``` Доўгія радкі абрэзаны праз `...` для гэтай старонкі. Сапраўдны адказ змяшчае поўны тэкст. ## Як знайсці калекцыю фільма Рэдка пачынаюць з id калекцыі. Пачынаюць з фільма, а запіс [дэталяў фільма](https://amodb.dev/be/movies/) падказвае, да чаго ён належыць. Поле `belongs_to_collection` ёсць аб’ектам з `id`, `name`, `poster_path` і `backdrop_path`. Яно роўнае `null` для фільма, які не ўваходзіць у франшызу, напрыклад для фільма 550. ```json { "id": 11, "title": "Star Wars", "belongs_to_collection": { "id": 10, "name": "Star Wars Collection", "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg", "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg" } } ``` Прыклад ніжэй ідзе па гэтай спасылцы ад фільма да яго франшызы за два запыты. ```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); } ``` ## Афармленне і пошук Постэр і фонавая выява франшызы ёсць палямі `poster_path` і `backdrop_path` запісу калекцыі. Складзіце з іх адрас файла, як апісана на старонцы [выявы](https://amodb.dev/be/images-api/). amodb не прапануе шляхі `/collection/{collection_id}/images` і `/collection/{collection_id}/translations`, таму ў калекцыі няма спісу альтэрнатыўных постэраў і радкоў па мовах. Назвы частак замест гэтага залежаць ад параметра `language`, а [пераклады](https://amodb.dev/be/translations/) апісваюць шляхі, што вяртаюць радкі па мовах. Каб знайсці калекцыю па назве, скарыстайцеся `GET /3/search/collection?query=matrix`, апісаным на старонцы [пошук](https://amodb.dev/be/search/). Кожны вынік мае `id`, `name`, `overview`, `poster_path`, `backdrop_path`, `original_language`, `original_name` і `adult`. ## Памылкі | HTTP | status_code | Калі | | ---- | ----------- | ---------------------------------------------------------------------- | | 401 | 7 | Ключ адсутнічае або няправільны. | | 402 | 36 | Тэрмін дзеяння плана скончыўся. | | 404 | 34 | Калекцыі з гэтым id няма, або id не з’яўляецца лікам. | | 405 | 37 | Вы выкарысталі метад запісу на шляху калекцыі. | | 429 | 25 | Вы перавысілі ліміт запытаў у хвіліну. Пачакайце `Retry-After` секунд. | Поўны спіс гл. на старонцы [памылкі](https://amodb.dev/be/errors/), а ліміты планаў на старонцы [ліміты запытаў](https://amodb.dev/be/rate-limits/). ## Практычныя заўвагі - Калекцыі групуюць толькі фільмы. Фільм мае не болей за адзін аб’ект `belongs_to_collection`, таму адзін фільм адпавядае адной франшызе. - Часткі прыходзяць у парадку выхаду. Фільмы з пустой датай ідуць апошнімі, таму пазначайце іх як пакуль без даты. - Запіс калекцыі кэшуецца на edge на 6 гадзін, як і іншыя дэталі, таму старонка франшызы можа выкарыстоўваць адзін адказ столькі часу. - Частка нясе толькі кароткія палі. Працягласць, удзельнікаў і рэйтынгі па кожным фільме атрымлівайце праз [дэталі фільма](https://amodb.dev/be/movies/), калі карыстальнік яго адкрывае. - Выкарыстоўвайце `parts[].id` як ключ фільма, а не яго месца ў франшызе. Парадак і даты з часам выпраўляюцца. - Праверце, што `name` на вашай мове адлюстравання, перш чым паказваць яго. Некаторыя калекцыі маюць назву на іншай мове, і `language` яе не змяняе. ## Пытанні і адказы ### Як даведацца, ці належыць фільм калекцыі? Прачытайце belongs_to_collection у запісе дэталяў фільма. Гэта аб’ект з id, name, poster_path і backdrop_path або null, калі фільм стаіць асобна. Выкарыстайце гэты id у шляху калекцыі. ### Ці вяртаюцца часткі ў парадку выхаду? Так. Масіў parts ідзе ад самага старога па release_date. Фільм без даты мае пусты release_date і ставіцца ў канец, таму пазначайце яго як пакуль без даты. ### Ці ёсць калекцыі ў серыялаў? Не. Калекцыі групуюць фільмы. Серыял апісваецца сваімі сезонамі і эпізодамі, якія дакументаваны на старонках пра серыялы і пра сезоны і эпізоды. ### Як знайсці калекцыю па назве? Скарыстайцеся шляхам пошуку калекцый, напрыклад /3/search/collection?query=matrix. Ён вяртае спіс па старонках з id, name і афармленнем. Вазьміце id і выклічце эндпоінт калекцыі, каб атрымаць часткі. ## Звязаныя старонкі - [API дэталяў фільма](https://amodb.dev/be/movies/): API дэталяў фільма з тымі ж шляхамі і JSON, што ў TMDB v3. Адзін фільм па id, а акцёры, рэйтынгі і настрой праз append_to_response, на 14 мовах. - [API пошуку](https://amodb.dev/be/search/): API пошуку з шляхамі і JSON як у TMDB v3. Фільмы, серыялы, персоны, калекцыі, кампаніі і ключавыя словы па тэксце, з фільтрамі па годзе і старонкамі. - [API выяў і хост выяў](https://amodb.dev/be/images-api/): API выяў фільмаў з шляхамі TMDB v3: спісы постэраў, фонавых выяў, лагатыпаў і кадраў назвы, а потым загрузка з img.amodb.dev у 10 памерах без ключа. - [API перакладаў](https://amodb.dev/be/translations/): API перакладаў фільмаў з шляхамі TMDB v3: чытайце ўсе захаваныя назвы, апісанні і слоганы фільма, серыяла або эпізода на ўсіх мовах за адзін раз. - [Discover API](https://amodb.dev/be/discover/): Discover API з фільтрамі TMDB v3. Спіс фільмаў і серыялаў па жанры, акцёрах, кампаніі, ключавым слове, годзе, рэйтынгу і працягласці з сартаваннем. - [Хуткі старт](https://amodb.dev/be/quickstart/): Першы выклік да amodb: атрымайце ключ, запытайце дэталі фільма ў curl, JavaScript, Python, PHP або Go і загрузіце постэр з img.amodb.dev. Менш за 2 хвіліны. Абноўлена: 2026-10-18. Source: https://amodb.dev/be/collections/