API сеансаў у кінатэатрах

API сеансаў у кінатэатрах гэта GET /3/movie/{movie_id}/showtimes?country=US. Ён вяртае кінатэатры з адрасам і гадзінным поясам, а для кожнага сеанса час пачатку, фарматы і спасылку на бранаванне, дзе вядомыя. Без country вы атрымаеце толькі лічбы па краінах. Пакрыццё залежыць ад назвы, а пусты масіў results азначае, што нічога невядома.

Глядзець тарыфы Адкрыць хуткі старт

Запыт

curl JavaScript

bashjs

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}`);
  }
}

Адказ 200

{
  "id": 550,
  "country": "RU",
  "results": [
    {
      "id": 1114,
      "name": "Мираж Синема НА БОЛЬШОМ",
      "chain": {
        "key": "mirage-ru",
        "name": "Мираж Синема"
      },
      "city": "Санкт-Петербург",
      "region": null,
      "address": "Большой пр. П.С., д. 35А",

Атрыманне сеансаў фільма

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`	Дэталі плюс сеансы адным запытам, гл. сеансы

Палі ў адказе па сеансах:

Поле	Тып	Сэнс
`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 крокі

Адкрыйце цэны і абярыце план. Сеансы ўваходзяць у кожны план.
Стварыце ключ у асабістым кабінеце.
Запытайце /3/movie/{movie_id}/showtimes з кодам country і перадайце ключ у api_key або ў загалоўку Bearer.

Прыклад запыту

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

curl JavaScript

bashjs

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 сеансамі.

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` секунд

Пусты масіў не памылка і не сцвярджэнне, што фільма няма ў кінатэатрах. Ён азначае, што даных пра сеансы невядома. Поўны фармат цела гл. на старонцы памылкі.

Старонка афішы бягучых рэлізаў

Спалучыце два эндпоінты. Спіс паказвае, якія фільмы бягучыя, а сеансы запаўняюць расклад.

Крок	Запыт	Заўвагі
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 запытаў у хвіліну спраўляюцца з той жа задачай з запасам. Акно і загалоўкі гл. на старонцы ліміты запытаў, а іншыя эндпоінты спісаў на старонцы трэнды і спісы.

Як трымаць копію свежай

Сеансы мяняюцца па днях, у адрозненне ад дэталяў фільма. Захоўвайце кожны адказ з 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 хвілін для некалькіх краін, хопіць найменшай частаты. Бясплатнага тарыфа няма. Абярыце план на старонцы цэны.

Пытанні і адказы

Як атрымаць сеансы фільма?

Адпраўце 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 у гадзінны пояс гледача.

Абноўлена 18 кас 2026 г.

Адкрыць у Markdown