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