# 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}` повертає одну франшизу: назву, опис, постер, фон (backdrop) і масив `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` | query | одне з двох | Ваш ключ. Використовуйте його або заголовок `Authorization: Bearer`. | | `language` | query | ні | Одна з 14 підтримуваних мов, наприклад `en-US` або `fr-FR`. Задає мову назви й опису кожної частини. За замовчуванням `en-US`. | Власні `name` та `overview` колекції повертаються як збережені й не залежать від `language`. У деяких колекцій вони не англійською. ### Поля відповіді | Поле | Тип | Примітки | | ---------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------- | | `id` | integer | id колекції. | | `name` | string | Назва франшизи. | | `overview` | string | Короткий опис. У деяких колекцій порожній. | | `poster_path`, `backdrop_path` | string або null | Додайте до `https://img.amodb.dev/t/p/{size}`. Див. [зображення](https://amodb.dev/uk/images-api/). | | `parts` | array | Короткі записи про фільми, спершу найстаріший `release_date`. | | `parts[].id` | integer | id фільму. Передайте його в [деталі фільму](https://amodb.dev/uk/movies/). | | `parts[].title`, `parts[].original_title` | string | Локалізована й оригінальна назви. | | `parts[].overview` | string | Локалізований синопсис. | | `parts[].release_date` | string | `YYYY-MM-DD` або порожній рядок для фільму без дати. Такі частини йдуть останніми. | | `parts[].media_type` | string | У колекції завжди `movie`. | | `parts[].genre_ids` | array | Числові id. Назви беріть зі сторінки [жанри](https://amodb.dev/uk/genres/). | | `parts[].adult`, `parts[].video` | boolean | `adult` завжди `false`, бо контент для дорослих не віддається. | | `parts[].original_language` | string | Дволітерний код мови. | | `parts[].popularity` | number | Показник популярності. | | `parts[].poster_path`, `parts[].backdrop_path` | string або null | Зображення фільму. | | `parts[].vote_average`, `parts[].vote_count` | number, integer | Сукупна оцінка користувачів. | ### Приклад відповіді Показано дві з дев'яти частин. ```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/uk/movies/) підказує, до чого він належить. Поле `belongs_to_collection` є об'єктом з `id`, `name`, `poster_path` і `backdrop_path`. Для фільму поза франшизою, наприклад фільму 550, воно дорівнює `null`. ```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/uk/images-api/). amodb не надає шляхів `/collection/{collection_id}/images` і `/collection/{collection_id}/translations`, тому в колекції немає списку альтернативних постерів і рядків для окремих мов. Назви частин натомість залежать від параметра `language`, а шляхи, що повертають рядки з мовами, описані на сторінці [переклади](https://amodb.dev/uk/translations/). Щоб знайти колекцію за назвою, використайте `GET /3/search/collection?query=matrix`, описаний на сторінці [пошук](https://amodb.dev/uk/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/uk/errors/), а ліміти тарифів на сторінці [ліміти запитів](https://amodb.dev/uk/rate-limits/). ## Практичні поради - Колекції об'єднують лише фільми. Фільм має щонайбільше один об'єкт `belongs_to_collection`, тож один фільм відповідає одній франшизі. - Частини приходять у порядку виходу. Фільми з порожньою датою йдуть останніми, тож позначайте їх як «дата ще невідома». - Запис колекції кешується на рівні CDN на 6 годин, як і інші деталі, тож сторінка франшизи може використовувати одну відповідь стільки часу. - Частина містить лише скорочені поля. Тривалість, акторський склад і рейтинги окремого фільму завантажуйте через [деталі фільму](https://amodb.dev/uk/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/uk/movies/): API деталей фільму з тими самими шляхами та JSON, що в TMDB v3. Отримайте фільм за id, додайте акторів, рейтинги й настрої через append_to_response, 14 мовами. - [API пошуку](https://amodb.dev/uk/search/): API пошуку з тими самими шляхами та JSON, що в TMDB v3. Шукайте фільми, серіали, персон, колекції, компанії та ключові слова за текстом, з фільтром за роком. - [API зображень і хост зображень](https://amodb.dev/uk/images-api/): API зображень фільмів зі шляхами TMDB v3: списки постерів, фонів, логотипів і кадрів проєкту, а потім завантаження з img.amodb.dev у 10 розмірах без ключа. - [API перекладів](https://amodb.dev/uk/translations/): API перекладів фільмів зі шляхами TMDB v3: прочитайте всі збережені назви, описи та слогани фільму, серіалу чи серії всіма мовами одним запитом. - [Discover API](https://amodb.dev/uk/discover/): Discover API з тими самими фільтрами, що й у TMDB v3. Фільми та серіали за жанром, акторами, компанією, роком, рейтингом, тривалістю й провайдером. - [Швидкий старт](https://amodb.dev/uk/quickstart/): Перший виклик amodb: отримайте ключ, запросіть деталі фільму в curl, JavaScript, Python, PHP чи Go і завантажте постер з img.amodb.dev. Менш ніж за 2 хвилини. Оновлено: 2026-10-18. Source: https://amodb.dev/uk/collections/