# API сеансів кінотеатрів > API сеансів кінотеатрів це GET /3/movie/{movie_id}/showtimes?country=US. Він повертає кінотеатри з адресою та часовим поясом, а також кожен сеанс із часом початку, форматами й посиланням на бронювання, якщо вони відомі. Без country ви отримаєте лише лічильники за країнами. Покриття залежить від фільму, а порожній масив results означає, що даних немає. ## Отримайте сеанси фільму `GET /3/movie/{movie_id}/showtimes?country=US` повертає кінотеатри, що показують один фільм в одній країні, кожен зі списком сеансів. `country` це 2-літерний код. Без нього `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/uk/showtimes/) | Поля у відповіді showtimes: | Поле | Тип | Значення | | ---------------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------- | | `id` | ціле число | Id фільму | | `country` | рядок або null | 2-літерний код, який ви запитали, `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 | Заповнюються лише тоді, коли їх надає джерело кінотеатру | Відповідь містить щонайбільше 1,500 сеансів, упорядкованих за кінотеатром, а потім за часом початку. ## Почніть за 3 кроки 1. Відкрийте [ціни](https://amodb.dev/uk/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/uk/errors/). ## Складіть сторінку афіші для поточних прем'єр Поєднайте два ендпоінти. Список показує, які фільми зараз у прокаті, а showtimes заповнюють сеанси. | Крок | Запит | Примітки | | ---- | ---------------------------------------------- | ---------------------------------------- | | 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 запит. Відповідь для великої прем'єри може важити кілька сотень кілобайтів, бо містить до 1,500 сеансів. На тарифі з 20 запитами на хвилину це повна хвилина ліміту, тож завантажуйте дані у фоновому завданні й віддавайте відвідувачам збережену копію. Тарифи з 40 і 120 запитами на хвилину впораються з тим самим завданням із запасом. Про вікно й заголовки дивіться [ліміти запитів](https://amodb.dev/uk/rate-limits/), а про інші ендпоінти списків [списки трендів](https://amodb.dev/uk/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/uk/pricing/). ## Запитання й відповіді ### Як отримати сеанси фільму? Надішліть GET /3/movie/{movie_id}/showtimes?country=US зі своїм ключем. Параметр country це 2-літерний код, а 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/uk/showtimes/): API сеансів фільмів повертає кінотеатри та час показів фільму в одній країні або зведення по країнах. Додайте його до деталей або поєднайте з now_playing. - [Ендпоінти трендів і списків](https://amodb.dev/uk/trending-lists/): API трендів фільмів зі шляхами TMDB v3: чарти за день і тиждень, а також списки в прокаті, популярних, найкращих і майбутніх фільмів та серіалів, кеш 30 хвилин. - [API деталей фільму](https://amodb.dev/uk/movies/): API деталей фільму з тими самими шляхами та JSON, що в TMDB v3. Отримайте фільм за id, додайте акторів, рейтинги й настрої через append_to_response, 14 мовами. - [Ліміти запитів](https://amodb.dev/uk/rate-limits/): amodb обмежує кожен ключ запитами на хвилину в ковзному вікні 60 секунд: 20, 40 або 120 за тарифом. Читайте заголовки ліміту й обробляйте 429 із Retry-After. - [Швидкий старт](https://amodb.dev/uk/quickstart/): Перший виклик amodb: отримайте ключ, запросіть деталі фільму в curl, JavaScript, Python, PHP чи Go і завантажте постер з img.amodb.dev. Менш ніж за 2 хвилини. Оновлено: 2026-10-18. Source: https://amodb.dev/uk/cinema-showtimes-api/