# API seansów kinowych > API seansów kinowych to GET /3/movie/{movie_id}/showtimes?country=US. Zwraca kina z adresem i strefą czasową oraz każdy seans z godziną rozpoczęcia, formatami i linkiem do rezerwacji, jeśli są znane. Bez country dostaniesz tylko liczby według krajów. Pokrycie zależy od tytułu, a pusta tablica results oznacza, że nic nie wiadomo. ## 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 | Endpoint | Zwraca | | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `GET /3/movie/{movie_id}/showtimes` | Kina i seanse jednego filmu w `country` albo, bez niego, liczby według krajów | | `GET /3/movie/now_playing` | Filmy aktualnie w kinach, zawężone przez `region` | | `GET /3/movie/{movie_id}` z `append_to_response=showtimes` | Szczegóły plus seanse w jednym żądaniu, zobacz [seanse](https://amodb.dev/pl/showtimes/) | Pola w odpowiedzi z seansami: | Pole | Typ | Znaczenie | | ---------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- | | `id` | integer | ID filmu | | `country` | string lub null | Dwuliterowy kod, o który prosisz, `null`, gdy żaden nie był poprawny | | `results` | array | Jedna pozycja na kino, puste, gdy nic nie wiadomo lub brakuje `country` | | `countries` | array | Liczby według krajów: `country`, `name`, `venues`, `cities`, `showtimes`, `first_day`, `last_day` | | `results[].id`, `name`, `city`, `address` | integer, string | ID kina, nazwa, miasto i adres ulicy | | `results[].chain` | object lub null | `key` i `name` sieci kin | | `results[].timezone` | string lub null | Strefa IANA kina, na przykład `Europe/Moscow` | | `results[].latitude`, `longitude` | number lub null | Pozycja, gdy znana | | `results[].region`, `postal_code`, `phone`, `url` | string lub null | Dalsze dane kina, często null | | `results[].showtimes` | array | Seanse w tym kinie | | `showtimes[].date` | string | Lokalny dzień, na przykład `2026-10-18` | | `showtimes[].start` | string | Lokalna godzina rozpoczęcia, na przykład `2026-10-18T21:40`, bez przesunięcia | | `showtimes[].auditorium` | string lub null | Nazwa lub numer sali | | `showtimes[].formats` | array | Formaty seansu, na przykład `2D`, `IMAX` lub `Dolby Atmos` | | `showtimes[].tags` | array | Dodatkowe etykiety, na przykład `Reserved Seating` | | `showtimes[].booking_url` | string lub null | Link do zakupu biletu, gdy znany | | `showtimes[].sold_out` | boolean | `true`, gdy źródło oznacza seans jako wyprzedany | | `showtimes[].end`, `audio`, `subtitles`, `language`, `price`, `currency`, `prices` | różne, często null | Wypełnione tylko wtedy, gdy źródło kina je podaje | 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](https://amodb.dev/pl/pricing/) 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. ```bash curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js 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. ```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" } ] } ``` ## Pokrycie i puste wyniki Dane kin nie są dostępne dla każdego kraju ani tytułu. Zaplanuj interfejs z tym na uwadze. | Sytuacja | Co widzisz | Co zrobić | | --------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------- | | Seanse są znane | `results` ma jedną pozycję na kino | Pokaż listę | | Dla tego kraju i tytułu nic nie wiadomo | `results` to pusta tablica, `countries` wskazuje, gdzie dane istnieją | Pokaż neutralną notatkę, nie pustą tabelę | | Nie wysłano `country` | `results` jest puste, `country` to `null`, `countries` ma liczby | Pozwól użytkownikowi wybrać z `countries` | | Nieznane ID filmu | 404 z `status_code` 34 | Sprawdź ID | | Przekroczony limit | 429 z `status_code` 25 | Poczekaj tyle sekund, ile podaje `Retry-After` | 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](https://amodb.dev/pl/errors/). ## Budowanie strony repertuaru bieżących premier Połącz dwa endpointy. Lista mówi, które filmy są aktualne, a seanse uzupełniają godziny. | Krok | Żądanie | Uwagi | | ---- | ---------------------------------------------- | ----------------------------------------------- | | 1 | `GET /3/movie/now_playing?region=US&page=1` | Do 20 filmów na stronę, w cache przez 30 minut | | 2 | `GET /3/movie/{movie_id}/showtimes?country=US` | Jedno wywołanie na film, w cache przez 30 minut | | 3 | Filtruj w swoim kodzie | Według `city`, `formats` lub `tags` | 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ń](https://amodb.dev/pl/rate-limits/), a inne endpointy list [trendy i listy](https://amodb.dev/pl/trending-lists/). ## 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 | Możliwość | Scraping stron kin | API metadanych bez seansów | amodb | | ----------------------- | --------------------------------- | -------------------------- | ------------------------------------------------------------ | | Konfiguracja | Jeden scraper na stronę kina | Niedostępne | Jeden endpoint, jeden kształt JSON | | Dopasowanie do ID filmu | Dopasowanie po tekście tytułu | Niedostępne | ID filmu w ścieżce | | Pokrycie | Cokolwiek uda się zescrapować | Brak | Zależy od kraju i tytułu, pusta tablica, gdy nic nie wiadomo | | Formaty i rezerwacja | Parsować etykiety i linki | Niedostępne | Pola `formats`, `tags` i `booking_url` | | Utrzymanie | Psuje się, gdy strona się zmienia | Brak | Jeden kształt JSON dla każdego kraju | ## 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](https://amodb.dev/pl/pricing/). ## Pytania i odpowiedzi ### Jak pobrać seanse filmu? Wyślij GET /3/movie/{movie_id}/showtimes?country=US ze swoim kluczem. Parametr country to dwuliterowy kod, a region działa jako alias. Odpowiedź wymienia kina, a każde kino ma seanse z godziną rozpoczęcia, formatami, etykietami i linkiem do rezerwacji, jeśli są znane. ### Co oznacza pusta tablica results? Oznacza, że amodb nie ma danych o seansach tego filmu w tym kraju. To nie błąd i nie informacja, że filmu nie ma w kinach. Tablica countries w tej samej odpowiedzi nadal pokazuje, gdzie dane istnieją, więc możesz zaproponować inny kraj. ### Jakie kraje są objęte? Pokrycie zależy od kraju i tytułu. Każda odpowiedź zawiera tablicę countries z liczbą miejsc, miast i seansów, do 60 krajów, z największą liczbą seansów na początku. Czytaj ją dla każdego filmu zamiast wpisywać listę na stałe. ### Czy mogę wypisać filmy grane teraz w kinach? Tak. GET /3/movie/now_playing z parametrem region wypisuje bieżące premiery i jest w cache przez 30 minut. Weź ID każdego filmu z tej listy i pobierz jego seanse z tym samym kodem kraju. ### Jakiej strefy czasowej używają wartości start? Wartość start wygląda jak 2026-10-18T21:40 i nie niesie przesunięcia UTC. Traktuj ją jako lokalny czas zegarowy w kinie. Każde miejsce ma też timezone, na przykład Europe/Moscow. Nie przeliczaj start na strefę czasową widza. ## Powiązane strony - [Seanse kinowe](https://amodb.dev/pl/showtimes/): API seansów filmu zwraca kina i godziny seansów w jednym kraju albo podsumowanie krajów. Scal je ze szczegółami przez append_to_response lub z now_playing. - [Trendy i listy](https://amodb.dev/pl/trending-lists/): API trendów filmowych ze ścieżkami TMDB v3: wykresy dzienne i tygodniowe oraz listy now playing, popular, top rated i upcoming, w cache 30 minut. - [API szczegółów filmu](https://amodb.dev/pl/movies/): API szczegółów filmu z tymi samymi ścieżkami i JSON co TMDB v3. Pobierz film po ID, dołącz obsadę, oceny i nastroje przez append_to_response, 14 języków. - [Limity żądań](https://amodb.dev/pl/rate-limits/): amodb limituje klucz liczbą żądań na minutę w przesuwanym oknie 60 sekund: 20, 40 lub 120 zależnie od planu. Czytaj nagłówki limitu i obsłuż 429 z Retry-After. - [Szybki start](https://amodb.dev/pl/quickstart/): Pierwsze wywołanie amodb: zdobądź klucz, pobierz szczegóły filmu w curl, JavaScript, Python, PHP lub Go, potem załaduj plakat z img.amodb.dev. Poniżej 2 minut. Zaktualizowano: 2026-10-18. Source: https://amodb.dev/pl/cinema-showtimes-api/