# Promítací časy v kinech > GET /3/movie/{movie_id}/showtimes?country=RU vrací kina, která film promítají v jedné zemi, s datovanými časy promítání u každého. Bez country vrací jen počty podle zemí v seznamu countries. Pokrytí se liší podle země a titulu a prázdné pole results znamená, že pro danou dvojici nic není známo. ## Endpoint `GET /3/movie/{movie_id}/showtimes` ```bash curl "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` Odpověď: ```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-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 }, { "date": "2026-10-21", "start": "2026-10-21T21: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/5ad6b82b-82b3-4ea6-9e65-79388d71b230/", "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" } ] } ``` ## Získání promítacích časů filmu `GET /3/movie/{movie_id}/showtimes?country=RU` vrací kina, která film promítají v jedné zemi, s datovanými časy promítání u každého. Parametr `country` přijímá dvoupísmenný kód, velkými i malými písmeny. Pokrytí se liší podle země a titulu, takže data jsou přítomna tam, kde jsou známa, a chybí tam, kde ne. Vracejí se jen dny od dneška. Ukázka si vyžádá Fight Club v Rusku a zvládne prázdnou odpověď. ```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 | Kde | Povinný | Popis | | ---------- | ----- | ------------- | -------------------------------------------------------------------------------------------------- | | `movie_id` | path | ano | Číselné ID filmu, například `550`. | | `country` | query | ne | Dvoupísmenný kód země, například `RU`. Bez něj dostanete jen souhrn podle zemí. `region` je alias. | | `api_key` | query | jeden ze dvou | Váš klíč. Použijte jej, nebo hlavičku `Authorization: Bearer`. | ### Pole odpovědi | Pole | Typ | Poznámky | | ------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer | ID filmu. | | `country` | string nebo null | Kód velkými písmeny, o který jste požádali, nebo `null`, když `country` chybí nebo nemá dvě písmena. | | `results` | array | Jeden objekt na kino, řazeno podle kina. Prázdné, když nic není známo nebo nebyla odeslána země. Celkem nejvýše 1500 promítání. | | `results[].id` | integer | ID kina. | | `results[].name` | string | Název kina. | | `results[].chain` | object | `key` je klíč řetězce, `name` je název řetězce nebo `null`. | | `results[].city` | string nebo null | Město. | | `results[].region` | string nebo null | Region. | | `results[].address` | string nebo null | Ulice a číslo. | | `results[].postal_code` | string nebo null | PSČ. | | `results[].country` | string | Kód země kina. | | `results[].timezone` | string nebo null | Časové pásmo IANA, například `Europe/Moscow`. | | `results[].latitude`, `results[].longitude` | number nebo null | Poloha kina. | | `results[].phone` | string nebo null | Telefonní číslo. | | `results[].url` | string nebo null | Stránka kina. | | `results[].showtimes` | array | Promítání v daném kině, řazeno podle začátku. | | `results[].showtimes[].date` | string | Den jako `2026-10-18`. | | `results[].showtimes[].start` | string | Začátek v místním čase kina, například `2026-10-18T21:40`, bez posunu UTC. | | `results[].showtimes[].end` | string nebo null | Konec v místním čase kina. | | `results[].showtimes[].auditorium` | string nebo null | Název sálu. | | `results[].showtimes[].formats` | array of strings | Formáty, například `2D`. | | `results[].showtimes[].tags` | array of strings | Další štítky. Často prázdné. | | `results[].showtimes[].audio`, `subtitles`, `language` | string nebo null | Podrobnosti o zvuku, titulcích a jazyku, když jsou známé. | | `results[].showtimes[].price` | number nebo null | Cena vstupenky. | | `results[].showtimes[].currency` | string nebo null | Měna `price`. | | `results[].showtimes[].prices` | any nebo null | Podrobnosti o cenách, když kino má několik. | | `results[].showtimes[].booking_url` | string nebo null | Odkaz na rezervaci místa. | | `results[].showtimes[].sold_out` | boolean | `true`, když je promítání vyprodané. | | `countries` | array | Souhrn podle zemí, viz níže. | Klíče, které používáte, čtěte podle názvu a přebytečné klíče uvnitř objektu kina nebo promítání přeskočte. Mnoho polí je dnes `null`, protože ne každé kino je posílá. ### Příklad odpovědi ```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" } ] } ``` Seznam je zkrácen na 1 ze 2 kin a 2 ze 4 promítání. Promítání existují jen pro dny, které ještě nepominuly, takže se tato odpověď mění každý den. ## Získání souhrnu podle zemí Vynechte `country` a odpověď obsahuje jen počty. `results` zůstane prázdné a `country` je `null`. Pole `countries` uvádí až 60 zemí, které mají ještě nějaké promítání, na prvním místě tu s nejvíce promítáními. Použijte je, abyste zjistili, kde se titul promítá, než si vyžádáte 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 | Poznámky | | ----------------------------------------------- | ------- | --------------------------------------------------------------- | | `countries[].country` | string | Dvoupísmenný kód, připravený k použití jako parametr `country`. | | `countries[].name` | string | Anglický název země. | | `countries[].venues` | integer | Kina s promítáním. | | `countries[].cities` | integer | Města s promítáním. | | `countries[].showtimes` | integer | Promítání od dneška. | | `countries[].first_day`, `countries[].last_day` | string | První a poslední den s promítáním. | Kód země bez dat, například `country=US` pro tento film, odpoví `country` jako `US`, prázdným `results` a stejným seznamem `countries`. Titul bez promítání kdekoli, například seriál 1396, má `"countries": []`. ## Přidání promítacích časů k volání detailů `append_to_response=showtimes` sloučí stejný blok do odpovědi detailů pod klíčem `showtimes`. Kód `country` pošlete ve stejném požadavku. Blok si ponechává vlastní klíče `id`, `country`, `results` a `countries`. | Požadavek | Výsledek | | -------------------------------------------------------------- | -------------------------------------------- | | `/3/movie/550?append_to_response=showtimes&country=RU` | Záznam filmu plus blok `showtimes` pro Rusko | | `/3/movie/550?append_to_response=credits,showtimes&country=RU` | Přidá do stejného volání obsazení | Počítá se jako jeden požadavek, takže stránka filmu, která zobrazuje obsazení i promítání, potřebuje jediné volání. Stejný endpoint existuje pro seriály jako `GET /3/tv/{tv_id}/showtimes`. ## Kombinace s now_playing a region Seznam now playing dává tituly. Endpoint promítacích časů dává promítání jednoho titulu. Spojte je ve svém kódu. | Krok | Požadavek | Výsledek | | ---- | ----------------------------------------------------- | -------------------------------------- | | 1 | `GET /3/movie/now_playing?region=RU&page=1` | Až 20 filmů na stránku, cache 30 minut | | 2 | `GET /3/movie/{id}/showtimes?country=RU` pro každé ID | Kina a časy, kde jsou známé | Smyčka níže jednou nebo dvakrát opakuje pokus, když je dosažen limit tarifu, a čeká počet 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'); } ``` Stránka s 20 tituly je 20 požadavků na promítací časy. V tarifu s 20 požadavky za minutu to spotřebuje celé okno, výsledek proto cachujte u sebe. Parametry seznamu viz [trendy a seznamy](https://amodb.dev/cs/trending-lists/). ## Chyby Tělo chyby se řídí TMDB: `success`, `status_code` a `status_message`. Špatný klíč ukazuje `status_code` 7. | HTTP | status_code | Kdy | | ---- | ----------- | ------------------------------------------------------------------------------------- | | 401 | 7 | Klíč chybí nebo je nesprávný. | | 402 | 36 | Platnost tarifu skončila. | | 404 | 34 | Film s tímto ID neexistuje. | | 429 | 25 | Překročen počet požadavků za minutu. Počkejte tolik sekund, kolik říká `Retry-After`. | Žádné promítací časy nejsou chyba: počítejte se stavem 200 a prázdným polem `results`. Chybějící nebo neplatné `country` také není chyba. Viz [chyby](https://amodb.dev/cs/errors/) a [limity požadavků](https://amodb.dev/cs/rate-limits/). ## Praktické poznámky - Pokrytí se liší podle země a titulu. Prázdné pole `results` berte jako neznámé, ne jako nepromítá se. - Zobrazte `start` přesně tak, jak přišlo. Je to místní čas kina bez posunu UTC a hodiny kina jsou to, co návštěvníci očekávají. - Promítací časy se na edge cachují 30 minut. Nevyžadujte je při každém zobrazení stránky a vlastní cache držte krátkou. - Jeden seznam now playing znovu použijte pro všechny návštěvníky v regionu. Na edge se také cachuje 30 minut. - Použijte `booking_url` k odeslání návštěvníka na rezervační stránku kina. Je `null`, když kino odkaz neposkytuje. - Přehled případu užití viz [API promítacích časů kin](https://amodb.dev/cs/cinema-showtimes-api/) a další data filmu viz [filmy](https://amodb.dev/cs/movies/). ## Otázky a odpovědi ### Je parametr country povinný? Ne, ale potřebujete ho, abyste dostali kina. Pošlete dvoupísmenný kód, například RU nebo DE. Bez country, nebo s kódem, který nemá dvě písmena, je results prázdné a seznam countries ukazuje, kde promítací časy existují. Parametr region funguje jako alias. ### Co znamená prázdné pole results? Znamená to, že pro daný titul v dané zemi nejsou od dneška známy žádné promítací časy. Neprokazuje to, že film není v kinech. Seznam countries stále ukazuje další země s daty. Místo toho nabídněte datum vydání z detailu filmu. ### Jak najdu filmy, které jsou právě v kinech? Zavolejte GET /3/movie/now_playing s parametrem region a pak si vyžádejte promítací časy pro ID, která vás zajímají. Seznam se cachuje 30 minut, takže ho můžete znovu použít pro každého návštěvníka. ### Jsou časy v časovém pásmu mého návštěvníka? Ne. Hodnota start je místní čas v kině a nemá posun UTC. Každé kino má také timezone, například Europe/Moscow. Zobrazte start tak, jak přišlo, a nepřevádějte ho časovým pásmem návštěvníka. ## Související stránky - [API promítacích časů kin](https://amodb.dev/cs/cinema-showtimes-api/): API promítacích časů kin: GET /3/movie/{movie_id}/showtimes s kódem země vrací kina, začátky promítání a formáty, pokud jsou známé. Doplňte jej o 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ů. - [Hodnocení filmů a seriálů](https://amodb.dev/cs/ratings/): API hodnocení filmů, které vrací skóre z IMDb, Kinopoisk, Metacritic, Rotten Tomatoes a TMDB pro titul jedním voláním, s null u každého neznámého zdroje. - [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/showtimes/