API promítacích časů kin

Získání promítacích časů filmu

GET /3/movie/{movie_id}/showtimes?country=US vrací kina, která promítají jeden film v jedné zemi, každé se seznamem promítání. country je dvoupísmenný kód. Bez něj zůstane results prázdné a dostanete jen počty podle zemí. Pokrytí se liší podle země a titulu a prázdné pole results znamená, že pro tuto dvojici nic není známo.

Dostanete název kina, řetězec, adresu a časové pásmo a u každého promítání čas začátku, sál, formáty, štítky a odkaz na rezervaci, pokud jsou známé. Vrací se jen promítání od dneška. Odpověď popisuje promítání. Není to prodejní služba vstupenek.

Jaká data dostanete

Pole v odpovědi s promítacími časy:

Odpověď obsahuje nejvýše 1 500 promítání seřazených podle kina a pak podle času začátku.

Začněte ve 3 krocích

1. Otevřete ceník a vyberte tarif. Promítací časy jsou součástí každého tarifu.
2. Vytvořte klíč v panelu účtu.
3. Zavolejte /3/movie/{movie_id}/showtimes s kódem country a klíč předejte v api_key nebo v hlavičce Bearer.

Příklad požadavku

Ukázka v bashi čte promítací časy filmu Fight Club (ID 550) v Rusku, kde má amodb dnes promítání pro tento film. Ukázka v JS vezme prvních pět filmů z ruského seznamu now_playing a vypíše až tři promítání na kino, nebo poznámku, když žádná nejsou známa.

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

Zkrácená odpověď pro country=RU: první kino se 2 svými promítáními.

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

Pokrytí a prázdné výsledky

Data o kinech nejsou k dispozici pro každou zemi ani titul. Rozhraní tomu přizpůsobte.

Prázdné pole není chyba ani tvrzení, že film v kinech chybí. Znamená to, že data o promítání nejsou známa. Úplný formát těla viz chyby.

Sestavení stránky programu aktuálních premiér

Zkombinujte dva endpointy. Seznam říká, které filmy jsou aktuální, a promítací časy doplní promítání.

Jedna stránka s 20 filmy stojí 21 požadavků. Odpověď pro velkou premiéru může mít několik set kilobajtů, protože obsahuje až 1 500 promítání. V tarifu s 20 požadavky za minutu je to celý minutový rozpočet, proto data stahujte úlohou na pozadí a návštěvníkům servírujte uloženou kopii. Tarify s 40 a 120 požadavky za minutu stejnou úlohu zvládnou s rezervou. Okno a hlavičky popisují limity požadavků, další endpointy se seznamy jsou na stránce trendy a seznamy.

Udržujte kopii aktuální

Promítací časy se mění ze dne na den, na rozdíl od detailů filmu. Každou odpověď ukládejte s ID filmu, zemí a časem stažení. Pro většinu stránek s programem stačí TTL od 30 minut do několika hodin a promítání, která už začala, lze skrýt porovnáním start s aktuálním časem v timezone kina. Protože start nemá posun, nepřevádějte ho do časového pásma návštěvníka.

Jak si stojí v porovnání

Ceník

Předplacené tarify trvají 1, 3, 6, 12 nebo 24 měsíců, u delších je sleva 0, 10, 20, 30 nebo 40 procent. Nic se neobnovuje automaticky. Tarify povolují 20, 40 a 120 požadavků za minutu a každý zahrnuje promítací časy spolu se všemi ostatními daty. Stránka s programem, která se obnovuje každých 30 minut pro několik zemí, se vejde do nejmenšího limitu. Bezplatný tarif neexistuje. Vyberte tarif na stránce ceník.