# Seanse kinowe > GET /3/movie/{movie_id}/showtimes?country=RU zwraca kina, które grają film w jednym kraju, z datowanymi seansami w każdym. Bez country zwraca tylko liczby według krajów w liście countries. Pokrycie zależy od kraju i tytułu, a pusta tablica results oznacza, że dla tej pary nic nie wiadomo. ## Endpoint `GET /3/movie/{movie_id}/showtimes` ```bash curl "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` Odpowiedź: ```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 }, { "date": "2026-10-20", "start": "2026-10-20T21: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/7f18e423-4a40-40f3-b68f-8664f4e3fa75/", "sold_out": false } ] }, { "id": 1115, "name": "Мираж Синема ПИК", "chain": { "key": "mirage-ru", "name": "Мираж Синема" }, "city": "Санкт-Петербург", "region": null, "address": "ул. Ефимова, д.2", "postal_code": null, "country": "RU", "timezone": "Europe/Moscow", "latitude": null, "longitude": null, "phone": null, "url": "https://www.mirage.ru/spb/cinema/27/", "showtimes": [ { "date": "2026-10-19", "start": "2026-10-19T20:10", "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/1d143ca6-1bbe-48ee-954a-063b6088a32a/", "sold_out": false }, { "date": "2026-10-20", "start": "2026-10-20T20:10", "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/8b2e0f6a-5b62-41eb-a398-1b709539f03d/", "sold_out": false }, { "date": "2026-10-21", "start": "2026-10-21T20:10", "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/3723875b-a7df-426f-968a-4bdaa1a8bdd7/", "sold_out": false } ] } ], "countries": [ { "country": "RU", "name": "Russia", "venues": 2, "cities": 1, "showtimes": 6, "first_day": "2026-10-19", "last_day": "2026-10-21" } ] } ``` ## Pobieranie seansów filmu `GET /3/movie/{movie_id}/showtimes?country=RU` zwraca kina, które grają film w jednym kraju, z datowanymi seansami w każdym. Parametr `country` przyjmuje dwuliterowy kod, wielkimi lub małymi literami. Pokrycie zależy od kraju i tytułu, więc dane są obecne tam, gdzie są znane, a brakuje ich tam, gdzie nie. Zwracane są tylko dni od dziś. Przykład prosi o Fight Club w Rosji i obsługuje pustą odpowiedź. ```bash curl -sf "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/movie/550/showtimes?country=RU'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const data = await res.json(); if (data.results.length === 0) console.log('no showtimes known'); for (const venue of data.results) { for (const s of venue.showtimes) { console.log(venue.name, venue.city, s.start, s.formats.join(','), s.booking_url); } } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/movie/550/showtimes", params={"country": "RU"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() results = r.json()["results"] if not results: print("no showtimes known") for venue in results: for s in venue["showtimes"]: print(venue["name"], venue["city"], s["start"], ",".join(s["formats"])) ``` ```php true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("amodb returned $status"); } $results = json_decode($body, true)['results']; if (!$results) { echo 'no showtimes known', PHP_EOL; } foreach ($results as $venue) { foreach ($venue['showtimes'] as $s) { echo $venue['name'], ' ', $s['start'], ' ', implode(',', $s['formats']), PHP_EOL; } } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "strings" "time" ) type Venue struct { Name string `json:"name"` City string `json:"city"` Showtimes []struct { Start string `json:"start"` Formats []string `json:"formats"` BookingURL string `json:"booking_url"` } `json:"showtimes"` } func main() { url := "https://api.amodb.dev/3/movie/550/showtimes?country=RU" req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var body struct { Results []Venue `json:"results"` } if err := json.NewDecoder(res.Body).Decode(&body); err != nil { panic(err) } if len(body.Results) == 0 { fmt.Println("no showtimes known") } for _, v := range body.Results { for _, s := range v.Showtimes { fmt.Println(v.Name, v.City, s.Start, strings.Join(s.Formats, ",")) } } } ``` ### Parametry | Parametr | Gdzie | Wymagany | Opis | | ---------- | ----- | ------------- | --------------------------------------------------------------------------------------------------------------------- | | `movie_id` | path | tak | Numeryczne ID filmu, na przykład `550`. | | `country` | query | nie | Dwuliterowy kod kraju, na przykład `RU`. Bez niego dostajesz tylko podsumowanie według krajów. `region` jest aliasem. | | `api_key` | query | jeden z dwóch | Twój klucz. Użyj go albo nagłówka `Authorization: Bearer`. | ### Pola odpowiedzi | Pole | Typ | Uwagi | | ------------------------------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer | ID filmu. | | `country` | string lub null | Kod wielkimi literami, o który prosisz, albo `null`, gdy `country` brakuje lub nie ma dwóch liter. | | `results` | array | Jeden obiekt na kino, uporządkowane według kina. Puste, gdy nic nie wiadomo lub nie wysłano kraju. Łącznie najwyżej 1500 seansów. | | `results[].id` | integer | ID kina. | | `results[].name` | string | Nazwa kina. | | `results[].chain` | object | `key` to klucz sieci, `name` to nazwa sieci albo `null`. | | `results[].city` | string lub null | Miasto. | | `results[].region` | string lub null | Region. | | `results[].address` | string lub null | Adres ulicy. | | `results[].postal_code` | string lub null | Kod pocztowy. | | `results[].country` | string | Kod kraju kina. | | `results[].timezone` | string lub null | Strefa czasowa IANA, na przykład `Europe/Moscow`. | | `results[].latitude`, `results[].longitude` | number lub null | Pozycja kina. | | `results[].phone` | string lub null | Numer telefonu. | | `results[].url` | string lub null | Strona kina. | | `results[].showtimes` | array | Seanse w tym kinie, uporządkowane według początku. | | `results[].showtimes[].date` | string | Dzień jako `2026-10-18`. | | `results[].showtimes[].start` | string | Początek w czasie lokalnym kina, na przykład `2026-10-18T21:40`, bez przesunięcia UTC. | | `results[].showtimes[].end` | string lub null | Koniec w czasie lokalnym kina. | | `results[].showtimes[].auditorium` | string lub null | Nazwa sali. | | `results[].showtimes[].formats` | array of strings | Formaty, na przykład `2D`. | | `results[].showtimes[].tags` | array of strings | Dodatkowe etykiety. Często puste. | | `results[].showtimes[].audio`, `subtitles`, `language` | string lub null | Szczegóły dźwięku, napisów i języka, gdy znane. | | `results[].showtimes[].price` | number lub null | Cena biletu. | | `results[].showtimes[].currency` | string lub null | Waluta `price`. | | `results[].showtimes[].prices` | any lub null | Szczegóły cen, gdy kino ma kilka. | | `results[].showtimes[].booking_url` | string lub null | Link do rezerwacji miejsca. | | `results[].showtimes[].sold_out` | boolean | `true`, gdy seans jest wyprzedany. | | `countries` | array | Podsumowanie według krajów, zobacz niżej. | Klucze, których używasz, czytaj po nazwie i pomijaj dodatkowe klucze wewnątrz obiektu kina lub seansu. Wiele pól ma dziś wartość `null`, bo nie każde kino je wysyła. ### Przykładowa odpowiedź ```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" } ] } ``` Lista jest przycięta do 1 z 2 kin i 2 z 4 seansów. Seanse istnieją tylko dla dni, które jeszcze nie minęły, więc ta odpowiedź zmienia się codziennie. ## Pobieranie podsumowania według krajów Pomiń `country`, a odpowiedź zawiera tylko liczby. `results` pozostaje puste, a `country` ma wartość `null`. Tablica `countries` wymienia do 60 krajów, które mają jeszcze jakiś seans, na początku ten z największą liczbą seansów. Użyj jej, by dowiedzieć się, gdzie tytuł jest w kinach, zanim poprosisz o kina. ```bash curl -sf "https://api.amodb.dev/3/movie/550/showtimes" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```json { "id": 550, "country": null, "results": [], "countries": [ { "country": "RU", "name": "Russia", "venues": 2, "cities": 1, "showtimes": 7, "first_day": "2026-10-18", "last_day": "2026-10-21" } ] } ``` | Pole | Typ | Uwagi | | ----------------------------------------------- | ------- | ---------------------------------------------------------- | | `countries[].country` | string | Dwuliterowy kod, gotowy do użycia jako parametr `country`. | | `countries[].name` | string | Angielska nazwa kraju. | | `countries[].venues` | integer | Kina z seansem. | | `countries[].cities` | integer | Miasta z seansem. | | `countries[].showtimes` | integer | Seanse od dziś. | | `countries[].first_day`, `countries[].last_day` | string | Pierwszy i ostatni dzień z seansem. | Kod kraju bez danych, taki jak `country=US` dla tego filmu, odpowiada `country` jako `US`, pustym `results` i tą samą listą `countries`. Tytuł bez seansów nigdzie, taki jak serial 1396, ma `"countries": []`. ## Dołączanie seansów do wywołania szczegółów `append_to_response=showtimes` scala ten sam blok z odpowiedzią szczegółów pod kluczem `showtimes`. Kod `country` wyślij w tym samym żądaniu. Blok zachowuje własne klucze `id`, `country`, `results` i `countries`. | Żądanie | Wynik | | -------------------------------------------------------------- | -------------------------------------------- | | `/3/movie/550?append_to_response=showtimes&country=RU` | Rekord filmu plus blok `showtimes` dla Rosji | | `/3/movie/550?append_to_response=credits,showtimes&country=RU` | Dodaje obsadę do tego samego wywołania | Liczy się jako jedno żądanie, więc strona filmu pokazująca obsadę i seanse potrzebuje jednego wywołania. Ten sam endpoint istnieje dla seriali jako `GET /3/tv/{tv_id}/showtimes`. ## Łączenie z now_playing i region Lista now playing daje tytuły. Endpoint seansów daje seanse jednego tytułu. Połącz je w swoim kodzie. | Krok | Żądanie | Wynik | | ---- | ------------------------------------------------------- | ---------------------------------------------- | | 1 | `GET /3/movie/now_playing?region=RU&page=1` | Do 20 filmów na stronę, w cache przez 30 minut | | 2 | `GET /3/movie/{id}/showtimes?country=RU` dla każdego ID | Kina i godziny, gdzie znane | Poniższa pętla ponawia próbę raz lub dwa razy, gdy zostanie osiągnięty limit planu, czekając liczbę sekund z `Retry-After`. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path, retries = 2) { const res = await fetch(base + path, { headers }); if (res.status === 429 && retries > 0) { const wait = Number(res.headers.get('Retry-After') ?? 60); await new Promise((resolve) => setTimeout(resolve, wait * 1000)); return get(path, retries - 1); } if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const playing = await get('/movie/now_playing?region=RU&page=1'); for (const movie of playing.results) { const data = await get(`/movie/${movie.id}/showtimes?country=RU`); if (data.results.length > 0) console.log(movie.title, data.results.length, 'venues'); } ``` Strona z 20 tytułami to 20 żądań o seanse. W planie z 20 żądaniami na minutę zużywa to całe okno, więc zapisz wynik w cache u siebie. Parametry list zobacz w [trendy i listy](https://amodb.dev/pl/trending-lists/). ## Błędy Treść błędu odpowiada TMDB: `success`, `status_code` i `status_message`. Zły klucz pokazuje `status_code` 7. | HTTP | status_code | Kiedy | | ---- | ----------- | ----------------------------------------------------------------------------------- | | 401 | 7 | Brakuje klucza lub jest błędny. | | 402 | 36 | Okres planu dobiegł końca. | | 404 | 34 | Brak filmu o tym ID. | | 429 | 25 | Przekroczono limit żądań na minutę. Poczekaj tyle sekund, ile podaje `Retry-After`. | Brak seansów to nie błąd: spodziewaj się statusu 200 i pustej tablicy `results`. Brakujące lub nieprawidłowe `country` też nie jest błędem. Zobacz [błędy](https://amodb.dev/pl/errors/) i [limity żądań](https://amodb.dev/pl/rate-limits/). ## Praktyczne uwagi - Pokrycie zależy od kraju i tytułu. Pustą tablicę `results` traktuj jako nieznane, a nie jako film nie jest grany. - Pokaż `start` dokładnie tak, jak przyszło. To czas lokalny kina bez przesunięcia UTC, a zegar kina jest tym, czego oczekują odwiedzający. - Seanse są w cache na edge przez 30 minut. Nie żądaj ich przy każdym wyświetleniu strony i trzymaj własny cache krótko. - Użyj jednej listy now playing dla wszystkich odwiedzających w regionie. Na edge też jest w cache przez 30 minut. - Użyj `booking_url`, by wysłać odwiedzającego na stronę rezerwacji kina. Ma wartość `null`, gdy kino nie podaje linku. - Przegląd zastosowania zobacz w [API seansów kinowych](https://amodb.dev/pl/cinema-showtimes-api/), a inne dane filmu w [filmy](https://amodb.dev/pl/movies/). ## Pytania i odpowiedzi ### Czy parametr country jest wymagany? Nie, ale potrzebujesz go, by dostać kina. Wyślij dwuliterowy kod, na przykład RU lub DE. Bez country albo z kodem, który nie ma dwóch liter, results jest puste, a lista countries pokazuje, gdzie seanse istnieją. Parametr region działa jako alias. ### Co oznacza pusta tablica results? Oznacza, że dla tego tytułu w tym kraju od dziś nie są znane żadne seanse. Nie dowodzi to, że film nie jest w kinach. Lista countries nadal pokazuje inne kraje z danymi. Zamiast tego podaj datę premiery ze szczegółów filmu. ### Jak znaleźć filmy, które są teraz w kinach? Wywołaj GET /3/movie/now_playing z parametrem region, a potem pobierz seanse dla ID, które cię interesują. Lista jest w cache przez 30 minut, więc możesz użyć jej dla każdego odwiedzającego. ### Czy godziny są w strefie czasowej mojego odwiedzającego? Nie. Wartość start to czas lokalny w kinie i nie ma przesunięcia UTC. Każde kino ma też timezone, na przykład Europe/Moscow. Pokaż start tak, jak przyszło, i nie przeliczaj go strefą czasową odwiedzającego. ## Powiązane strony - [API seansów kinowych](https://amodb.dev/pl/cinema-showtimes-api/): API seansów kinowych: GET /3/movie/{movie_id}/showtimes z kodem kraju zwraca kina, godziny rozpoczęcia i formaty, jeśli są znane. Połącz je 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. - [Oceny filmów i seriali](https://amodb.dev/pl/ratings/): API ocen filmów zwraca wyniki z IMDb, Kinopoisk, Metacritic, Rotten Tomatoes i TMDB dla tytułu jednym wywołaniem, z null dla każdego nieznanego źródła. - [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/showtimes/