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

Отримайте сеанси фільму

GET /3/movie/{movie_id}/showtimes?country=US повертає кінотеатри, що показують один фільм в одній країні, кожен зі списком сеансів. country це 2-літерний код. Без нього results лишається порожнім, і ви отримуєте лише лічильники за країнами. Покриття залежить від країни та фільму, а порожній масив results означає, що для цієї пари нічого не відомо.

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

Які дані ви отримуєте

Поля у відповіді showtimes:

Відповідь містить щонайбільше 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"
    }
  ]
}

Покриття та порожні результати

Дані про кінотеатри доступні не для кожної країни чи фільму. Плануйте інтерфейс з урахуванням цього.

Порожній масив не є помилкою і не означає, що фільму немає в кінотеатрах. Він означає, що даних про сеанси немає. Повний формат тіла помилки дивіться на сторінці помилки.

Складіть сторінку афіші для поточних прем'єр

Поєднайте два ендпоінти. Список показує, які фільми зараз у прокаті, а showtimes заповнюють сеанси.

Одна сторінка з 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 хвилин для кількох країн, вкладається в найменший ліміт. Безкоштовного тарифу немає. Оберіть тариф на сторінці ціни.