# 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/bg/images-api/). | | `parts` | масив | Кратки описания на филми, най-старият `release_date` първо. | | `parts[].id` | цяло число | Id на филма. Подайте го на [детайли за филм](https://amodb.dev/bg/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/bg/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/bg/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/bg/images-api/). amodb не предлага пътищата `/collection/{collection_id}/images` и `/collection/{collection_id}/translations`, така че колекцията няма списък с алтернативни постери и редове по езици. Заглавията на частите следват параметъра `language`, а [преводи](https://amodb.dev/bg/translations/) описва пътищата, които връщат редове по езици. За да намерите колекция по име, ползвайте `GET /3/search/collection?query=matrix`, описан на страницата [търсене](https://amodb.dev/bg/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/bg/errors/) за пълния списък и [лимити на заявките](https://amodb.dev/bg/rate-limits/) за лимитите на плановете. ## Практически бележки - Колекциите групират само филми. Един филм има най-много един обект `belongs_to_collection`, така че един филм съответства на един франчайз. - Частите пристигат по ред на излизане. Филмите с празна дата са последни, затова ги обозначете като още без дата. - Записът за колекция се кешира на edge за 6 часа като другите детайли, така че страница на франчайз може да ползва един отговор толкова дълго. - Частта носи само кратки полета. Взимайте продължителност, участници и рейтинги за всеки филм през [детайли за филм](https://amodb.dev/bg/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/bg/movies/): API за детайли на филм със същите пътища и JSON като TMDB v3. Един филм по id, а актьори, рейтинги и настроения през append_to_response, на 14 езика. - [API за търсене](https://amodb.dev/bg/search/): API за търсене със същите пътища и JSON като TMDB v3. Намира филми, сериали, личности, колекции, компании и ключови думи по текст, с филтър по година. - [API за изображения и хост за изображения](https://amodb.dev/bg/images-api/): API за изображения на филми с пътища на TMDB v3: списъци с постери, фонови изображения, лога и кадри, после зареждане от img.amodb.dev в 10 размера без ключ. - [API за преводи](https://amodb.dev/bg/translations/): API за преводи на филми с пътища на TMDB v3: четете всяко записано заглавие, описание и слоган на филм, сериал или епизод на всички негови езици наведнъж. - [Discover API](https://amodb.dev/bg/discover/): Discover API със същите филтри като TMDB v3. Списък с филми и сериали по жанр, актьори, компания, ключова дума, година, рейтинг и продължителност със сортиране. - [Бърз старт](https://amodb.dev/bg/quickstart/): Първата ви заявка към amodb: вземете ключ, поискайте детайли за филм с curl, JavaScript, Python, PHP или Go и заредете постера от img.amodb.dev. До 2 минути. Обновено: 2026-10-18. Source: https://amodb.dev/bg/collections/