# 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/be/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/be/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/be/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/be/rate-limits/), а іншыя эндпоінты спісаў на старонцы [трэнды і спісы](https://amodb.dev/be/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/be/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/be/showtimes/): API сеансаў фільмаў вяртае кінатэатры і час сеансаў фільма ў адной краіне або зводку па краінах. Далучайце яго да дэталяў або спалучайце з now_playing. - [Эндпоінты трэндаў і спісаў](https://amodb.dev/be/trending-lists/): API трэндавых фільмаў з шляхамі TMDB v3: чарты за дзень і тыдзень, спісы зараз у пракаце, папулярных, лепшых і хутка ў пракаце, кэш 30 хвілін. - [API дэталяў фільма](https://amodb.dev/be/movies/): API дэталяў фільма з тымі ж шляхамі і JSON, што ў TMDB v3. Адзін фільм па id, а акцёры, рэйтынгі і настрой праз append_to_response, на 14 мовах. - [Ліміты запытаў](https://amodb.dev/be/rate-limits/): amodb абмяжоўвае ключ па запытах у хвіліну ў слізгальным акне 60 секунд: 20, 40 або 120 па плане. Чытайце загалоўкі лімітаў і апрацоўвайце 429 праз Retry-After. - [Хуткі старт](https://amodb.dev/be/quickstart/): Першы выклік да amodb: атрымайце ключ, запытайце дэталі фільма ў curl, JavaScript, Python, PHP або Go і загрузіце постэр з img.amodb.dev. Менш за 2 хвіліны. Абноўлена: 2026-10-18. Source: https://amodb.dev/be/cinema-showtimes-api/