# Orari delle proiezioni al cinema > GET /3/movie/{movie_id}/showtimes?country=RU restituisce i cinema che proiettano un film in un paese, con le proiezioni datate di ciascuno. Senza country restituisce solo i conteggi per paese in una lista countries. La copertura varia per paese e titolo, e un array results vuoto significa che per quella coppia non si sa nulla. ## Endpoint `GET /3/movie/{movie_id}/showtimes` ```bash curl "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` Risposta: ```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" } ] } ``` ## Ottenere le proiezioni di un film `GET /3/movie/{movie_id}/showtimes?country=RU` restituisce i cinema che proiettano un film in un paese, con le proiezioni datate di ciascuno. Il parametro `country` accetta un codice di due lettere, maiuscolo o minuscolo. La copertura varia per paese e titolo, quindi i dati ci sono dove sono noti e mancano dove non lo sono. Vengono restituiti solo i giorni da oggi in poi. L'esempio chiede Fight Club in Russia e gestisce una risposta vuota. ```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, ",")) } } } ``` ### Parametri | Parametro | In | Obbligatorio | Descrizione | | ---------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------- | | `movie_id` | percorso | sì | ID numerico del film, per esempio `550`. | | `country` | query | no | Codice paese di due lettere come `RU`. Senza, ottieni solo il riepilogo per paese. `region` è un alias. | | `api_key` | query | uno dei due | La tua chiave. Usa questa o l'header `Authorization: Bearer`. | ### Campi della risposta | Campo | Tipo | Note | | ------------------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | intero | ID del film. | | `country` | stringa o null | Il codice maiuscolo richiesto, oppure `null` quando `country` manca o non è di due lettere. | | `results` | array | Un oggetto per cinema, ordinato per cinema. Vuoto quando non si sa nulla o non è stato inviato alcun paese. Al massimo 1500 proiezioni in tutto. | | `results[].id` | intero | ID del cinema. | | `results[].name` | stringa | Nome del cinema. | | `results[].chain` | oggetto | `key` è la chiave della catena, `name` è il nome della catena o `null`. | | `results[].city` | stringa o null | Città. | | `results[].region` | stringa o null | Regione. | | `results[].address` | stringa o null | Indirizzo. | | `results[].postal_code` | stringa o null | Codice postale. | | `results[].country` | stringa | Codice paese del cinema. | | `results[].timezone` | stringa o null | Fuso orario IANA come `Europe/Moscow`. | | `results[].latitude`, `results[].longitude` | numero o null | Posizione del cinema. | | `results[].phone` | stringa o null | Numero di telefono. | | `results[].url` | stringa o null | Pagina del cinema. | | `results[].showtimes` | array | Proiezioni in quel cinema, ordinate per inizio. | | `results[].showtimes[].date` | stringa | Giorno come `2026-10-18`. | | `results[].showtimes[].start` | stringa | Inizio nell'ora locale del cinema come `2026-10-18T21:40`, senza scarto UTC. | | `results[].showtimes[].end` | stringa o null | Fine nell'ora locale del cinema. | | `results[].showtimes[].auditorium` | stringa o null | Nome della sala. | | `results[].showtimes[].formats` | array di stringhe | Formati come `2D`. | | `results[].showtimes[].tags` | array di stringhe | Etichette extra. Spesso vuoto. | | `results[].showtimes[].audio`, `subtitles`, `language` | stringa o null | Dettagli su audio, sottotitoli e lingua quando noti. | | `results[].showtimes[].price` | numero o null | Prezzo del biglietto. | | `results[].showtimes[].currency` | stringa o null | Valuta di `price`. | | `results[].showtimes[].prices` | qualsiasi o null | Dettagli dei prezzi quando un cinema ne ha diversi. | | `results[].showtimes[].booking_url` | stringa o null | Link per prenotare il posto. | | `results[].showtimes[].sold_out` | booleano | `true` quando la proiezione è esaurita. | | `countries` | array | Riepilogo per paese, vedi sotto. | Leggi per nome le chiavi che usi e salta le chiavi in più dentro un oggetto cinema o proiezione. Molti campi oggi sono `null` perché non tutti i cinema li inviano. ### Risposta di esempio ```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" } ] } ``` L'elenco è tagliato a 1 cinema su 2 e a 2 proiezioni su 4. Le proiezioni esistono solo per i giorni non ancora passati, quindi questa risposta cambia ogni giorno. ## Ottenere il riepilogo per paese Ometti `country` e la risposta contiene solo conteggi. `results` resta vuoto e `country` è `null`. L'array `countries` elenca fino a 60 paesi che hanno ancora una proiezione, prima quello con più proiezioni. Usalo per sapere dove un titolo è in sala prima di chiedere i cinema. ```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" } ] } ``` | Campo | Tipo | Note | | ----------------------------------------------- | ------- | ---------------------------------------------------------------- | | `countries[].country` | stringa | Codice di due lettere, pronto da usare come parametro `country`. | | `countries[].name` | stringa | Nome del paese in inglese. | | `countries[].venues` | intero | Cinema con una proiezione. | | `countries[].cities` | intero | Città con una proiezione. | | `countries[].showtimes` | intero | Proiezioni da oggi in poi. | | `countries[].first_day`, `countries[].last_day` | stringa | Primo e ultimo giorno con una proiezione. | Un codice paese senza dati, come `country=US` per questo film, risponde `country` a `US`, un `results` vuoto e la stessa lista `countries`. Un titolo senza proiezioni da nessuna parte, come la serie 1396, ha `"countries": []`. ## Aggiungere le proiezioni a una chiamata di dettagli `append_to_response=showtimes` unisce lo stesso blocco in una risposta di dettagli sotto la chiave `showtimes`. Invia il codice `country` nella stessa richiesta. Il blocco mantiene le proprie chiavi `id`, `country`, `results` e `countries`. | Richiesta | Risultato | | -------------------------------------------------------------- | ------------------------------------------------------- | | `/3/movie/550?append_to_response=showtimes&country=RU` | Scheda del film più un blocco `showtimes` per la Russia | | `/3/movie/550?append_to_response=credits,showtimes&country=RU` | Aggiunge i crediti alla stessa chiamata | Conta come una sola richiesta, quindi una pagina di film che mostra cast e proiezioni ha bisogno di una sola chiamata. Lo stesso endpoint esiste per le serie come `GET /3/tv/{tv_id}/showtimes`. ## Combinare con now_playing e region La lista dei film in sala ti dà i titoli. L'endpoint delle proiezioni ti dà le proiezioni di un titolo. Uniscili nel tuo codice. | Passaggio | Richiesta | Risultato | | --------- | ---------------------------------------------------- | --------------------------------------------- | | 1 | `GET /3/movie/now_playing?region=RU&page=1` | Fino a 20 film per pagina, in cache 30 minuti | | 2 | `GET /3/movie/{id}/showtimes?country=RU` per ogni id | Cinema e orari, dove noti | Il ciclo qui sotto ritenta una o due volte quando si raggiunge il limite del piano, attendendo i secondi di `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'); } ``` Una pagina di 20 titoli sono 20 richieste di proiezioni. Con il piano da 20 richieste al minuto consuma l'intera finestra, quindi metti il risultato in cache dalla tua parte. Vedi [tendenze e liste](https://amodb.dev/it/trending-lists/) per i parametri delle liste. ## Errori Il corpo dell'errore segue TMDB: `success`, `status_code` e `status_message`. Una chiave sbagliata dà `status_code` 7. | HTTP | status_code | Quando | | ---- | ----------- | --------------------------------------------------------------------- | | 401 | 7 | La chiave manca o è sbagliata. | | 402 | 36 | Il periodo del piano è terminato. | | 404 | 34 | Nessun film con quell'ID. | | 429 | 25 | Oltre le tue richieste al minuto. Attendi i secondi di `Retry-After`. | Nessuna proiezione non è un errore: aspettati lo stato 200 e un array `results` vuoto. Nemmeno un `country` mancante o non valido è un errore. Vedi [errori](https://amodb.dev/it/errors/) e [limiti di richieste](https://amodb.dev/it/rate-limits/). ## Note pratiche - La copertura varia per paese e titolo. Tratta un array `results` vuoto come sconosciuto, non come «non in programmazione». - Mostra `start` esattamente come restituito. È l'ora locale del cinema senza scarto UTC, e l'orologio del cinema è ciò che i visitatori si aspettano. - Le proiezioni restano in cache sull'edge per 30 minuti. Non richiederle a ogni visualizzazione di pagina, e tieni breve la tua cache. - Riusa una stessa lista dei film in sala per tutti i visitatori di una regione. Anche questa resta in cache sull'edge per 30 minuti. - Usa `booking_url` per mandare un visitatore alla pagina di prenotazione del cinema. Vale `null` quando il cinema non dà alcun link. - Per la panoramica del caso d'uso, vedi l'[API orari dei cinema](https://amodb.dev/it/cinema-showtimes-api/), e per gli altri dati di un film, vedi [film](https://amodb.dev/it/movies/). ## Domande e risposte ### Il parametro country è obbligatorio? No, ma ti serve per ottenere i cinema. Invia un codice di due lettere come RU o DE. Senza country, o con un codice che non è di due lettere, results è vuoto e la lista countries mostra dove esistono delle proiezioni. Il parametro region funziona come alias. ### Cosa significa un array results vuoto? Significa che per quel titolo in quel paese non si conoscono proiezioni da oggi in poi. Non dimostra che il film non sia in sala. La lista countries mostra comunque altri paesi con dati. Proponi invece la data di uscita presa dai dettagli del film. ### Come trovo i film che sono al cinema adesso? Chiama GET /3/movie/now_playing con il parametro region, poi richiedi le proiezioni per gli ID che ti interessano. La lista resta in cache per 30 minuti, quindi puoi riusarla per ogni visitatore. ### Gli orari sono nel fuso orario del mio visitatore? No. Il valore start è l'ora locale del cinema e non ha scarto UTC. Ogni cinema ha anche un timezone come Europe/Moscow. Mostra start come restituito e non convertirlo con il fuso orario del visitatore. ## Pagine correlate - [API orari dei cinema](https://amodb.dev/it/cinema-showtimes-api/): API orari dei cinema: GET /3/movie/{movie_id}/showtimes con un codice paese restituisce cinema, orari e formati quando noti. Da abbinare a now_playing. - [Tendenze e endpoint delle liste](https://amodb.dev/it/trending-lists/): API tendenze con percorsi TMDB v3: classifiche giorno e settimana, più liste di film e serie in sala, popolari, più votati e in arrivo, cache di 30 minuti. - [API dei dettagli del film](https://amodb.dev/it/movies/): API dettagli film con gli stessi percorsi e JSON di TMDB v3. Ottieni un film per ID, aggiungi crediti, valutazioni e mood con append_to_response, in 14 lingue. - [Valutazioni di film e serie TV](https://amodb.dev/it/ratings/): API valutazioni film: punteggi IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB di un titolo in una chiamata, con null per le fonti non note. - [Limiti di richieste](https://amodb.dev/it/rate-limits/): amodb limita ogni chiave per richieste al minuto in una finestra scorrevole di 60 secondi: 20, 40 o 120 in base al piano. Leggi gli header, gestisci il 429. - [Avvio rapido](https://amodb.dev/it/quickstart/): Fai la prima chiamata ad amodb: ottieni una chiave, richiedi i dettagli di un film in curl, JavaScript, Python, PHP o Go, carica la locandina. Meno di 2 minuti. Aggiornato: 2026-10-18. Source: https://amodb.dev/it/showtimes/