# API за прожекции в кината > API за прожекции в кината е GET /3/movie/{movie_id}/showtimes?country=US. Връща кина с адрес и часова зона, а за всяка прожекция начален час, формати и връзка за резервация, където са известни. Без country получавате само бройки по държави. Покритието зависи от заглавието, а празен масив results означава, че нищо не е известно. ## Вземане на прожекциите на филм `GET /3/movie/{movie_id}/showtimes?country=US` връща кината, които прожектират един филм в една държава, всяко със списък от прожекции. `country` е двубуквен код. Без него `results` остава празен и получавате само бройки по държави. Покритието зависи от държавата и заглавието, а празен масив `results` означава, че за тази двойка нищо не е известно. Получавате име на кино, верига, адрес и часова зона, а за всяка прожекция начален час, зала, формати, тагове и връзка за резервация, където са известни. Връщат се само прожекции от днес нататък. Отговорът описва прожекции. Не е услуга за продажба на билети. ## Какви данни получавате | Ендпойнт | Какво връща | | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `GET /3/movie/{movie_id}/showtimes` | Кина и прожекции на един филм в `country`, или бройки по държави без нея | | `GET /3/movie/now_playing` | Филми, които се дават в кината, стеснени по `region` | | `GET /3/movie/{movie_id}` с `append_to_response=showtimes` | Детайли плюс прожекции в една заявка, вижте [прожекции](https://amodb.dev/bg/showtimes/) | Полета в отговора за прожекции: | Поле | Тип | Значение | | ---------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------- | | `id` | цяло число | Id на филма | | `country` | низ или null | Двубуквеният код, който сте поискали, `null`, когато никой не е бил валиден | | `results` | масив | Един елемент на кино, празен, когато нищо не е известно или `country` липсва | | `countries` | масив | Бройки по държави: `country`, `name`, `venues`, `cities`, `showtimes`, `first_day`, `last_day` | | `results[].id`, `name`, `city`, `address` | цяло число, низове | Id на киното, име, град и пощенски адрес | | `results[].chain` | обект или null | `key` и `name` на веригата кина | | `results[].timezone` | низ или null | Зона по IANA на киното, например `Europe/Moscow` | | `results[].latitude`, `longitude` | число или null | Позиция, когато е известна | | `results[].region`, `postal_code`, `phone`, `url` | низ или null | Допълнителни данни за киното, често null | | `results[].showtimes` | масив | Прожекции в това кино | | `showtimes[].date` | низ | Местен ден като `2026-10-18` | | `showtimes[].start` | низ | Местен начален час като `2026-10-18T21:40`, без отместване | | `showtimes[].auditorium` | низ или null | Име или номер на залата | | `showtimes[].formats` | масив | Формати на прожекцията, например `2D`, `IMAX` или `Dolby Atmos` | | `showtimes[].tags` | масив | Допълнителни етикети като `Reserved Seating` | | `showtimes[].booking_url` | низ или null | Връзка за купуване на билет, когато е известна | | `showtimes[].sold_out` | булева стойност | `true`, когато източникът отбелязва прожекцията като разпродадена | | `showtimes[].end`, `audio`, `subtitles`, `language`, `price`, `currency`, `prices` | различни, често null | Попълват се само когато източникът на киното ги дава | Отговорът съдържа най-много 1500 прожекции, подредени по кино, после по начален час. ## Започнете в 3 стъпки 1. Отворете [цени](https://amodb.dev/bg/pricing/) и изберете план. Прожекциите са включени във всеки план. 2. Създайте ключ в личния си профил. 3. Поискайте `/3/movie/{movie_id}/showtimes` с код `country` и подайте ключа в `api_key` или в заглавка Bearer. ## Пример със заявка Bash примерът чете прожекциите на Fight Club (id `550`) в Русия, където amodb днес има прожекции за него. JS примерът взема първите пет филма от списъка `now_playing` за Русия и отпечатва до три прожекции на кино или бележка, когато нищо не е известно. ```bash curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const BASE = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path, params = {}) { const res = await fetch(`${BASE}${path}?${new URLSearchParams(params)}`, { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const country = 'RU'; const playing = await get('/movie/now_playing', { region: country, page: 1 }); for (const movie of playing.results.slice(0, 5)) { const { results } = await get(`/movie/${movie.id}/showtimes`, { country }); if (results.length === 0) { console.log(`${movie.title}: no showtimes known`); continue; } for (const cinema of results) { const times = cinema.showtimes .slice(0, 3) .map((s) => `${s.start.slice(5, 10)} ${s.start.slice(11, 16)} ${s.formats.join('/')}`) .join(', '); console.log(`${movie.title} at ${cinema.name}, ${cinema.city}: ${times}`); } } ``` Съкратен отговор за `country=RU`: първото кино с 2 от прожекциите си. ```json { "id": 550, "country": "RU", "results": [ { "id": 1114, "name": "Мираж Синема НА БОЛЬШОМ", "chain": { "key": "mirage-ru", "name": "Мираж Синема" }, "city": "Санкт-Петербург", "region": null, "address": "Большой пр. П.С., д. 35А", "postal_code": null, "country": "RU", "timezone": "Europe/Moscow", "latitude": null, "longitude": null, "phone": null, "url": "https://www.mirage.ru/spb/cinema/1/", "showtimes": [ { "date": "2026-10-18", "start": "2026-10-18T21:40", "end": null, "auditorium": null, "formats": [ "2D" ], "tags": [], "audio": null, "subtitles": null, "language": null, "price": null, "currency": null, "prices": null, "booking_url": "https://www.mirage.ru/ticket_new/aca7b114-d587-4fc5-9df6-28568e8fa9b3/", "sold_out": false }, { "date": "2026-10-19", "start": "2026-10-19T22:20", "end": null, "auditorium": "Зал №4", "formats": [ "2D" ], "tags": [], "audio": null, "subtitles": null, "language": null, "price": null, "currency": null, "prices": null, "booking_url": "https://www.mirage.ru/ticket_new/0c32e190-890a-4c81-a754-3300fefc4d5e/", "sold_out": false } ] } ], "countries": [ { "country": "RU", "name": "Russia", "venues": 2, "cities": 1, "showtimes": 7, "first_day": "2026-10-18", "last_day": "2026-10-21" } ] } ``` ## Покритие и празни резултати Данни за кината няма за всяка държава или заглавие. Планирайте интерфейса си с това предвид. | Ситуация | Какво виждате | Какво да направите | | --------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------- | | Прожекциите са известни | `results` има един елемент на кино | Покажете списъка | | За тази държава и заглавие нищо не е известно | `results` е празен масив, `countries` изброява къде има данни | Покажете неутрална бележка, а не празна таблица | | Не е изпратен `country` | `results` е празен, `country` е `null`, `countries` има бройки | Оставете потребителя да избере от `countries` | | Непознато id на филм | 404 със `status_code` 34 | Проверете id | | Надхвърлен лимит | 429 със `status_code` 25 | Изчакайте `Retry-After` секунди | Празният масив не е грешка и не твърдение, че филмът липсва от кината. Означава, че няма известни данни за прожекции. Вижте [грешки](https://amodb.dev/bg/errors/) за пълния формат на тялото. ## Изградете страница с афиш за текущи премиери Комбинирайте два ендпойнта. Списъкът казва кои филми са текущи, а прожекциите попълват програмата. | Стъпка | Заявка | Бележки | | ------ | ---------------------------------------------- | -------------------------------------- | | 1 | `GET /3/movie/now_playing?region=US&page=1` | До 20 филма на страница, кеш 30 минути | | 2 | `GET /3/movie/{movie_id}/showtimes?country=US` | Едно извикване на филм, кеш 30 минути | | 3 | Филтриране във вашия код | По `city`, `formats` или `tags` | Една страница с 20 филма струва 21 заявки. Отговор за голяма премиера може да е няколкостотин килобайта, защото съдържа до 1500 прожекции. При плана с 20 заявки в минута това е цяла минута от бюджета, затова теглете във фонова задача и обслужвайте посетителите от запазеното си копие. Плановете за 40 и 120 заявки в минута се справят със същата задача с резерв. Вижте [лимити на заявките](https://amodb.dev/bg/rate-limits/) за прозореца и заглавките, а за другите ендпойнти със списъци вижте [тенденции и списъци](https://amodb.dev/bg/trending-lists/). ## Поддържайте копието си свежо Прожекциите се менят по дни, за разлика от детайлите на филм. Пазете всеки отговор с id на филма, държавата и времето на теглене. TTL от 30 минути до няколко часа върши работа за повечето страници с афиш, а прожекции, които вече са започнали, можете да скриете, като сравните `start` с текущото време в `timezone` на киното. Тъй като `start` няма отместване, не го преместете в часовата зона на посетителя. ## Как се сравнява | Възможност | Обработка на сайтове на кина | API за метаданни без прожекции | amodb | | ---------------------- | ---------------------------------- | ------------------------------ | ------------------------------------------------------------------- | | Настройка | По един скрейпър за сайт на кино | Не е налично | Един ендпойнт, една форма на JSON | | Свързване с id на филм | Съпоставяне по текст на заглавието | Не е налично | Id на филма в пътя | | Покритие | Каквото успеете да изтеглите | Няма | Зависи от държавата и заглавието, празен масив, когато е неизвестно | | Формати и резервация | Разчитане на етикети и връзки | Не е налично | Полетата `formats`, `tags` и `booking_url` | | Поддръжка | Чупи се, когато сайт се промени | Няма | Една форма на JSON за всяка държава | ## Цени Предплатените планове са за 1, 3, 6, 12 или 24 месеца, с отстъпка 0, 10, 20, 30 или 40 процента за по-дългите. Нищо не се подновява автоматично. Плановете позволяват 20, 40 и 120 заявки в минута и всеки включва прожекции заедно с всички други данни. Страница с афиш, която се обновява на 30 минути за няколко държави, се събира в най-малката скорост. Няма безплатен план. Изберете план на страницата с [цените](https://amodb.dev/bg/pricing/). ## Въпроси и отговори ### Как да взема прожекциите на филм? Изпратете GET /3/movie/{movie_id}/showtimes?country=US с ключа си. Параметърът country е двубуквен код, а region работи като псевдоним. Отговорът изброява кина и всяко кино има своите прожекции с начален час, формати, тагове и връзка за резервация, където са известни. ### Какво означава празен масив results? Означава, че amodb няма данни за прожекции на този филм в тази държава. Не е грешка и не значи, че филмът го няма в кината. Масивът countries в същия отговор пак изброява къде има данни, така че можете да предложите друга държава. ### Кои държави са покрити? Покритието зависи от държавата и заглавието. Всеки отговор съдържа масив countries с брой кина, градове и прожекции, до 60 държави, първо тези с най-много прожекции. Четете го за всеки филм, вместо да вписвате списък в кода. ### Мога ли да изброя филмите, които се дават в кината в момента? Да. GET /3/movie/now_playing с параметъра region изброява текущите премиери, кеш 30 минути. Вземете id на всеки филм от списъка и поискайте прожекциите му със същия код на държава. ### В коя часова зона са стойностите на start? Стойността start изглежда като 2026-10-18T21:40 и няма UTC отместване. Третирайте я като местно стенно време в кината. Всяко кино има и timezone, например Europe/Moscow. Не преобразувайте start в часовата зона на зрителя. ## Свързани страници - [Прожекции в кината](https://amodb.dev/bg/showtimes/): API за прожекции на филми връща кина и часове на прожекции в една държава или обобщение по държави. Слейте го с детайлите или го съчетайте с now_playing. - [Ендпойнти за тенденции и списъци](https://amodb.dev/bg/trending-lists/): API за филми в тенденция с пътища на TMDB v3: класации за ден и седмица, списъци в кината, популярни, най-добри и предстоящи, кеш 30 минути. - [API за детайли на филм](https://amodb.dev/bg/movies/): API за детайли на филм със същите пътища и JSON като TMDB v3. Един филм по id, а актьори, рейтинги и настроения през append_to_response, на 14 езика. - [Лимити на заявките](https://amodb.dev/bg/rate-limits/): amodb ограничава всеки ключ по заявки в минута в плъзгащ се прозорец от 60 секунди: 20, 40 или 120. Заглавки за лимита и обработка на 429 с Retry-After. - [Бърз старт](https://amodb.dev/bg/quickstart/): Първата ви заявка към amodb: вземете ключ, поискайте детайли за филм с curl, JavaScript, Python, PHP или Go и заредете постера от img.amodb.dev. До 2 минути. Обновено: 2026-10-18. Source: https://amodb.dev/bg/cinema-showtimes-api/