API seansów kinowych

Pobieranie seansów filmu

GET /3/movie/{movie_id}/showtimes?country=US zwraca kina, które grają jeden film w jednym kraju, każde z listą seansów. country to dwuliterowy kod. Bez niego results pozostaje puste i dostajesz tylko liczby według krajów. Pokrycie zależy od kraju i tytułu, a pusta tablica results oznacza, że dla tej pary nic nie wiadomo.

Dostajesz nazwę kina, sieć, adres i strefę czasową, a dla każdego seansu godzinę rozpoczęcia, salę, formaty, etykiety i link do rezerwacji, jeśli są znane. Zwracane są tylko seanse od dziś. Odpowiedź opisuje seanse. To nie jest usługa sprzedaży biletów.

Jakie dane dostajesz

Pola w odpowiedzi z seansami:

Odpowiedź zawiera najwyżej 1 500 seansów, uporządkowanych według kina, a potem godziny rozpoczęcia.

Start w 3 krokach

1. Otwórz cennik i wybierz plan. Seanse są w każdym planie.
2. Utwórz klucz w panelu konta.
3. Wywołaj /3/movie/{movie_id}/showtimes z kodem country i przekaż klucz w api_key albo w nagłówku Bearer.

Przykładowe żądanie

Przykład w bashu czyta seanse filmu Fight Club (ID 550) w Rosji, gdzie amodb ma dziś seanse tego filmu. Przykład w JS bierze pierwsze pięć filmów z rosyjskiej listy now_playing i wypisuje do trzech seansów na kino albo notatkę, gdy żadne nie są znane.

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

Przycięta odpowiedź dla country=RU: pierwsze kino z 2 swoimi seansami.

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

Pokrycie i puste wyniki

Dane kin nie są dostępne dla każdego kraju ani tytułu. Zaplanuj interfejs z tym na uwadze.

Pusta tablica to nie błąd i nie twierdzenie, że filmu nie ma w kinach. Oznacza, że dane o seansach nie są znane. Pełny format treści odpowiedzi opisuje strona błędy.

Budowanie strony repertuaru bieżących premier

Połącz dwa endpointy. Lista mówi, które filmy są aktualne, a seanse uzupełniają godziny.

Jedna strona z 20 filmami kosztuje 21 żądań. Odpowiedź dla dużej premiery może mieć kilkaset kilobajtów, bo zawiera do 1 500 seansów. W planie z 20 żądaniami na minutę to cały minutowy budżet, więc pobieraj dane w zadaniu w tle, a odwiedzającym serwuj zapisaną kopię. Plany z 40 i 120 żądaniami na minutę obsłużą to samo zadanie z zapasem. Okno i nagłówki opisują limity żądań, a inne endpointy list trendy i listy.

Utrzymuj kopię w aktualnym stanie

Seanse zmieniają się z dnia na dzień, inaczej niż szczegóły filmu. Zapisuj każdą odpowiedź z ID filmu, krajem i czasem pobrania. Dla większości stron z repertuarem sprawdza się TTL od 30 minut do kilku godzin, a seanse, które już się zaczęły, można ukryć, porównując start z bieżącym czasem w timezone kina. Ponieważ start nie ma przesunięcia, nie przesuwaj go do strefy czasowej odwiedzającego.

Jak wypada w porównaniu

Cennik

Plany przedpłacone trwają 1, 3, 6, 12 lub 24 miesiące, a za dłuższe jest zniżka 0, 10, 20, 30 lub 40 procent. Nic nie odnawia się automatycznie. Plany dopuszczają 20, 40 i 120 żądań na minutę i każdy zawiera seanse razem ze wszystkimi innymi danymi. Strona z repertuarem odświeżana co 30 minut dla kilku krajów mieści się w najmniejszym limicie. Nie ma darmowego planu. Wybierz plan na stronie cennik.