API сеансов кинотеатров

Получение сеансов фильма

GET /3/movie/{movie_id}/showtimes?country=US возвращает кинотеатры, в которых идет один фильм в одной стране, и список сеансов каждого. country принимает код из 2 букв. Без него results остается пустым, и вы получаете только счетчики по странам. Покрытие зависит от страны и фильма, а пустой массив results означает, что для этой пары ничего не известно.

Вы получаете название кинотеатра, сеть, адрес и часовой пояс, а для каждого сеанса время начала, зал, форматы, теги и ссылку на бронирование, где они известны. Возвращаются только сеансы начиная с сегодняшнего дня. Ответ описывает сеансы. Это не сервис продажи билетов.

Какие данные вы получаете

Поля в ответе с сеансами:

Ответ содержит не более 1 500 сеансов, упорядоченных по кинотеатру, а затем по времени начала.

Начало работы в 3 шага

1. Откройте страницу цены и выберите тариф. Сеансы входят в каждый тариф.
2. Создайте ключ в личном кабинете.
3. Запросите /3/movie/{movie_id}/showtimes с кодом country и передайте ключ в api_key или в заголовке Bearer.

Пример запроса

Пример на bash читает сеансы Fight Club (id 550) в России, где у amodb сегодня есть сеансы этого фильма. Пример на JS берет первые пять фильмов из российского списка now_playing и выводит до трех сеансов на кинотеатр или заметку, если сеансы неизвестны.

curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -H "Authorization: Bearer $AMODB_KEY"

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 его сеанса.

{
  "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"
    }
  ]
}

Покрытие и пустые результаты

Данные о кинотеатрах есть не для каждой страны и не для каждого фильма. Учитывайте это при проектировании интерфейса.

Пустой массив не считается ошибкой и не утверждает, что фильма нет в кинотеатрах. Он означает, что данные о сеансах неизвестны. Полный формат тела ответа описан на странице ошибки.

Страница афиши для текущих новинок

Объедините два эндпоинта. Список подсказывает, какие фильмы идут сейчас, а сеансы наполняют афишу.

Одна страница из 20 фильмов стоит 21 запрос. Ответ для крупной новинки может занимать несколько сотен килобайт, потому что содержит до 1 500 сеансов. На тарифе 20 запросов в минуту это целая минута бюджета, поэтому загружайте данные фоновой задачей, а посетителям отдавайте сохраненную копию. Тарифы 40 и 120 запросов в минуту выполняют ту же задачу с запасом. Окно и заголовки описаны на странице лимиты запросов, а остальные эндпоинты списков на странице списки трендов.

Как поддерживать копию свежей

Сеансы меняются каждый день, в отличие от данных фильма. Сохраняйте каждый ответ вместе с id фильма, страной и временем получения. TTL от 30 минут до нескольких часов подходит для большинства страниц афиши, а уже начавшиеся сеансы можно скрывать, сравнивая start с текущим временем в timezone кинотеатра. Поскольку у start нет смещения, не переводите его в часовой пояс посетителя.

Сравнение

Цены

Тарифы предоплачиваются на 1, 3, 6, 12 или 24 месяца, за длинные периоды скидка составляет 0, 10, 20, 30 или 40 процентов. Автоматического продления нет. Тарифы допускают 20, 40 и 120 запросов в минуту, и каждый включает сеансы вместе со всеми остальными данными. Страница афиши, которая обновляется каждые 30 минут для нескольких стран, укладывается в самый малый лимит. Бесплатного тарифа нет. Выберите тариф на странице цены.