# API promítacích časů kin > API promítacích časů kin je GET /3/movie/{movie_id}/showtimes?country=US. Vrací kina s adresou a časovým pásmem a u každého promítání čas začátku, formáty a odkaz na rezervaci, pokud jsou známé. Bez country dostanete jen počty podle zemí. Pokrytí se liší podle titulu a prázdné pole results znamená, že nic není známo. ## 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 | Endpoint | Vrací | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `GET /3/movie/{movie_id}/showtimes` | Kina a promítání jednoho filmu v `country`, nebo bez něj počty podle zemí | | `GET /3/movie/now_playing` | Filmy aktuálně v kinech, zúžené přes `region` | | `GET /3/movie/{movie_id}` s `append_to_response=showtimes` | Detaily plus promítací časy v jednom požadavku, viz [promítací časy](https://amodb.dev/cs/showtimes/) | Pole v odpovědi s promítacími časy: | Pole | Typ | Význam | | ---------------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------- | | `id` | integer | ID filmu | | `country` | string nebo null | Dvoupísmenný kód, o který jste požádali, `null`, když žádný nebyl platný | | `results` | array | Jedna položka na kino, prázdné, když nic není známo nebo chybí `country` | | `countries` | array | Počty podle zemí: `country`, `name`, `venues`, `cities`, `showtimes`, `first_day`, `last_day` | | `results[].id`, `name`, `city`, `address` | integer, string | ID kina, název, město a ulice s číslem | | `results[].chain` | object nebo null | `key` a `name` řetězce kin | | `results[].timezone` | string nebo null | Zóna IANA kina, například `Europe/Moscow` | | `results[].latitude`, `longitude` | number nebo null | Poloha, pokud je známa | | `results[].region`, `postal_code`, `phone`, `url` | string nebo null | Další údaje o kině, často null | | `results[].showtimes` | array | Promítání v daném kině | | `showtimes[].date` | string | Místní den, například `2026-10-18` | | `showtimes[].start` | string | Místní čas začátku, například `2026-10-18T21:40`, bez posunu | | `showtimes[].auditorium` | string nebo null | Název nebo číslo sálu | | `showtimes[].formats` | array | Formáty promítání, například `2D`, `IMAX` nebo `Dolby Atmos` | | `showtimes[].tags` | array | Další štítky, například `Reserved Seating` | | `showtimes[].booking_url` | string nebo null | Odkaz na koupi vstupenky, pokud je znám | | `showtimes[].sold_out` | boolean | `true`, když zdroj označí promítání jako vyprodané | | `showtimes[].end`, `audio`, `subtitles`, `language`, `price`, `currency`, `prices` | různé, často null | Vyplněno jen tehdy, když je zdroj kina poskytuje | 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](https://amodb.dev/cs/pricing/) 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. ```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}`); } } ``` Zkrácená odpověď pro `country=RU`: první kino se 2 svými promítáními. ```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" } ] } ``` ## Pokrytí a prázdné výsledky Data o kinech nejsou k dispozici pro každou zemi ani titul. Rozhraní tomu přizpůsobte. | Situace | Co uvidíte | Co dělat | | ------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------ | | Promítání jsou známa | `results` má jednu položku na kino | Zobrazte seznam | | Pro tuto zemi a titul nic není známo | `results` je prázdné pole, `countries` uvádí, kde data existují | Zobrazte neutrální poznámku, ne prázdnou tabulku | | Nebylo odesláno `country` | `results` je prázdné, `country` je `null`, `countries` obsahuje počty | Nechte uživatele vybrat z `countries` | | Neznámé ID filmu | 404 se `status_code` 34 | Zkontrolujte ID | | Překročený limit | 429 se `status_code` 25 | Počkejte tolik sekund, kolik říká `Retry-After` | 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](https://amodb.dev/cs/errors/). ## 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í. | Krok | Požadavek | Poznámky | | ---- | ---------------------------------------------- | -------------------------------------- | | 1 | `GET /3/movie/now_playing?region=US&page=1` | Až 20 filmů na stránku, cache 30 minut | | 2 | `GET /3/movie/{movie_id}/showtimes?country=US` | Jedno volání na film, cache 30 minut | | 3 | Filtrujte ve svém kódu | Podle `city`, `formats` nebo `tags` | 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ů](https://amodb.dev/cs/rate-limits/), další endpointy se seznamy jsou na stránce [trendy a seznamy](https://amodb.dev/cs/trending-lists/). ## 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í | Schopnost | Scrapování webů kin | Metadata API bez promítacích časů | amodb | | -------------------- | --------------------------------- | --------------------------------- | -------------------------------------------------------------- | | Nastavení | Jeden scraper na web každého kina | Není k dispozici | Jeden endpoint, jeden tvar JSON | | Přiřazení k ID filmu | Párování podle textu názvu | Není k dispozici | ID filmu v cestě | | Pokrytí | Cokoli, co umíte seškrábat | Žádné | Liší se podle země a titulu, prázdné pole, když nic není známo | | Formáty a rezervace | Parsovat popisky a odkazy | Není k dispozici | Pole `formats`, `tags` a `booking_url` | | Údržba | Rozbije se, když se web změní | Žádná | Jeden tvar JSON pro každou zemi | ## 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](https://amodb.dev/cs/pricing/). ## Otázky a odpovědi ### Jak získám promítací časy filmu? Pošlete GET /3/movie/{movie_id}/showtimes?country=US se svým klíčem. Parametr country je dvoupísmenný kód a region funguje jako alias. Odpověď uvádí kina a každé kino má promítání s časem začátku, formáty, štítky a odkazem na rezervaci, pokud jsou známé. ### Co znamená prázdné pole results? Znamená to, že amodb nemá pro daný film v dané zemi data o promítání. Není to chyba a neříká to, že film v kinech není. Pole countries ve stejné odpovědi stále uvádí, kde data existují, takže můžete nabídnout jinou zemi. ### Které země jsou pokryté? Pokrytí se liší podle země a titulu. Každá odpověď obsahuje pole countries s počty míst, měst a promítání, nejvýše 60 zemí, s nejvíce promítáními na začátku. Čtěte je pro každý film, místo abyste seznam zadávali napevno. ### Mohu vypsat filmy, které jsou právě v kinech? Ano. GET /3/movie/now_playing s parametrem region vypíše aktuální premiéry a cachuje se 30 minut. Z tohoto seznamu vezměte ID každého filmu a vyžádejte si jeho promítací časy se stejným kódem země. ### Jaké časové pásmo mají hodnoty start? Hodnota start vypadá jako 2026-10-18T21:40 a nenese posun UTC. Berte ji jako místní čas na hodinách v kině. Každé místo má také timezone, například Europe/Moscow. Nepřevádějte start do časového pásma diváka. ## Související stránky - [Promítací časy v kinech](https://amodb.dev/cs/showtimes/): API promítacích časů filmu vrací kina a časy promítání v jedné zemi nebo souhrn zemí. Sloučte je s detaily přes append_to_response nebo spárujte s now_playing. - [Trendy a seznamy](https://amodb.dev/cs/trending-lists/): API trendů filmů s cestami TMDB v3: denní a týdenní žebříčky a seznamy now playing, popular, top rated a upcoming pro filmy a seriály, cachované 30 minut. - [API detailu filmu](https://amodb.dev/cs/movies/): API detailu filmu se stejnými cestami a JSON jako TMDB v3. Načtěte film podle ID, přidejte obsazení, hodnocení a nálady přes append_to_response, 14 jazyků. - [Limity požadavků](https://amodb.dev/cs/rate-limits/): amodb omezuje klíč počtem požadavků za minutu v klouzavém okně 60 sekund: 20, 40 nebo 120 podle tarifu. Čtěte hlavičky limitu a řešte 429 pomocí Retry-After. - [Rychlý start](https://amodb.dev/cs/quickstart/): První volání amodb: získejte klíč, vyžádejte detail filmu v curl, JavaScriptu, Pythonu, PHP nebo Go a načtěte plakát z img.amodb.dev. Za méně než 2 minuty. Aktualizováno: 2026-10-18. Source: https://amodb.dev/cs/cinema-showtimes-api/