# API orari dei cinema > L'API degli orari dei cinema è GET /3/movie/{movie_id}/showtimes?country=US. Restituisce i cinema con indirizzo e fuso orario, e ogni proiezione con orario di inizio, formati e link di prenotazione quando noti. Senza country ottieni solo i conteggi per paese. La copertura varia per titolo, e un array results vuoto significa che non si sa nulla. ## Ottenere le proiezioni di un film `GET /3/movie/{movie_id}/showtimes?country=US` restituisce i cinema che proiettano un film in un paese, ciascuno con un elenco di proiezioni. `country` è un codice di 2 lettere. Senza di esso `results` resta vuoto e ottieni solo i conteggi per paese. La copertura varia per paese e titolo, e un array `results` vuoto significa che per quella coppia non si sa nulla. Ottieni nome del cinema, catena, indirizzo e fuso orario, e per ogni proiezione l'orario di inizio, la sala, i formati, le etichette e un link di prenotazione, quando noti. Vengono restituite solo le proiezioni da oggi in poi. La risposta descrive proiezioni. Non è un servizio di biglietteria. ## Quali dati ottieni | Endpoint | Restituisce | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | `GET /3/movie/{movie_id}/showtimes` | Cinema e proiezioni di un film in `country`, oppure i conteggi per paese senza di esso | | `GET /3/movie/now_playing` | I film attualmente al cinema, ristretti da `region` | | `GET /3/movie/{movie_id}` con `append_to_response=showtimes` | Dettagli e proiezioni in una sola richiesta, vedi [orari delle proiezioni](https://amodb.dev/it/showtimes/) | Campi della risposta delle proiezioni: | Campo | Tipo | Significato | | ---------------------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------- | | `id` | intero | ID del film | | `country` | stringa o null | Il codice di 2 lettere richiesto, `null` se nessuno era valido | | `results` | array | Un elemento per cinema, vuoto quando non si sa nulla o manca `country` | | `countries` | array | Conteggi per paese: `country`, `name`, `venues`, `cities`, `showtimes`, `first_day`, `last_day` | | `results[].id`, `name`, `city`, `address` | intero, stringhe | ID, nome, città e indirizzo del cinema | | `results[].chain` | oggetto o null | `key` e `name` della catena di cinema | | `results[].timezone` | stringa o null | Fuso IANA del cinema, per esempio `Europe/Moscow` | | `results[].latitude`, `longitude` | numero o null | Posizione, quando nota | | `results[].region`, `postal_code`, `phone`, `url` | stringa o null | Altri dettagli del cinema, spesso null | | `results[].showtimes` | array | Proiezioni in quel cinema | | `showtimes[].date` | stringa | Giorno locale come `2026-10-18` | | `showtimes[].start` | stringa | Orario di inizio locale come `2026-10-18T21:40`, senza scarto | | `showtimes[].auditorium` | stringa o null | Nome o numero della sala | | `showtimes[].formats` | array | Formati di proiezione, per esempio `2D`, `IMAX` o `Dolby Atmos` | | `showtimes[].tags` | array | Etichette extra come `Reserved Seating` | | `showtimes[].booking_url` | stringa o null | Link per acquistare un biglietto, quando noto | | `showtimes[].sold_out` | booleano | `true` quando la fonte segna la proiezione come esaurita | | `showtimes[].end`, `audio`, `subtitles`, `language`, `price`, `currency`, `prices` | vari, spesso null | Compilati solo quando la fonte del cinema li fornisce | Una risposta contiene al massimo 1.500 proiezioni, ordinate per cinema e poi per orario di inizio. ## Parti in 3 passaggi 1. Apri la pagina dei [prezzi](https://amodb.dev/it/pricing/) e scegli un piano. Gli orari delle proiezioni sono inclusi in ogni piano. 2. Crea una chiave nella dashboard del tuo account. 3. Richiedi `/3/movie/{movie_id}/showtimes` con un codice `country`, e passa la chiave in `api_key` o come header Bearer. ## Esempio di richiesta L'esempio in bash legge le proiezioni di Fight Club (id `550`) in Russia, dove amodb ha oggi delle proiezioni. L'esempio in JS prende i primi cinque film della lista `now_playing` russa e stampa fino a tre proiezioni per cinema, o una nota quando non se ne conosce nessuna. ```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}`); } } ``` Risposta ridotta per `country=RU`: il primo cinema con 2 delle sue proiezioni. ```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" } ] } ``` ## Copertura e risultati vuoti I dati dei cinema non sono disponibili per ogni paese né per ogni titolo. Progetta la tua interfaccia tenendone conto. | Situazione | Cosa vedi | Cosa fare | | --------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------- | | Proiezioni note | `results` ha un elemento per cinema | Mostra l'elenco | | Nulla di noto per questo paese e titolo | `results` è un array vuoto, `countries` elenca dove esistono dati | Mostra una nota neutra, non una tabella vuota | | Nessun `country` inviato | `results` è vuoto, `country` è `null`, `countries` ha i conteggi | Lascia scegliere all'utente da `countries` | | ID del film sconosciuto | 404 con `status_code` 34 | Controlla l'ID | | Limite superato | 429 con `status_code` 25 | Attendi i secondi di `Retry-After` | Un array vuoto non è un errore e non afferma che il film manchi dai cinema. Significa che non si conoscono dati sulle proiezioni. Vedi [errori](https://amodb.dev/it/errors/) per il formato completo del corpo. ## Costruire una pagina di programmazione per le uscite attuali Combina due endpoint. La lista dice quali film sono in sala, e gli orari riempiono le proiezioni. | Passaggio | Richiesta | Note | | --------- | ---------------------------------------------- | --------------------------------------------- | | 1 | `GET /3/movie/now_playing?region=US&page=1` | Fino a 20 film per pagina, in cache 30 minuti | | 2 | `GET /3/movie/{movie_id}/showtimes?country=US` | Una chiamata per film, in cache 30 minuti | | 3 | Filtra nel tuo codice | Per `city`, `formats` o `tags` | Una pagina di 20 film costa 21 richieste. La risposta per una grande uscita può pesare diverse centinaia di kilobyte, perché contiene fino a 1.500 proiezioni. Con il piano da 20 richieste al minuto è un intero minuto di budget, quindi recupera i dati in un job in background e servi i visitatori dalla tua copia salvata. I piani da 40 e 120 richieste al minuto reggono lo stesso job con margine. Vedi [limiti di richieste](https://amodb.dev/it/rate-limits/) per la finestra e gli header, e [tendenze e liste](https://amodb.dev/it/trending-lists/) per gli altri endpoint di liste. ## Mantenere aggiornata la tua copia Gli orari cambiano di giorno in giorno, a differenza dei dettagli di un film. Salva ogni risposta con l'ID del film, il paese e l'ora del recupero. Un TTL da 30 minuti fino a qualche ora va bene per la maggior parte delle pagine di programmazione, e le proiezioni già iniziate si possono nascondere confrontando `start` con l'ora attuale nel `timezone` del cinema. Poiché `start` non ha scarto, non spostarlo nel fuso orario del visitatore. ## Confronto | Funzionalità | Fare scraping dei siti dei cinema | API di metadati senza orari | amodb | | ---------------------------- | ----------------------------------- | --------------------------- | ----------------------------------------------------- | | Configurazione | Uno scraper per ogni sito di cinema | Non disponibile | Un endpoint, una sola struttura JSON | | Collegamento a un ID di film | Abbinare dal testo del titolo | Non disponibile | ID del film nel percorso | | Copertura | Quello che riesci a estrarre | Nessuna | Varia per paese e titolo, array vuoto quando non noto | | Formati e prenotazione | Analizzare etichette e link | Non disponibile | Campi `formats`, `tags` e `booking_url` | | Manutenzione | Si rompe quando un sito cambia | Nessuna | Una sola struttura JSON per ogni paese | ## Prezzi I piani prepagati durano 1, 3, 6, 12 o 24 mesi, con uno sconto di 0, 10, 20, 30 o 40 per cento per quelli più lunghi. Nulla si rinnova automaticamente. I piani consentono 20, 40 e 120 richieste al minuto e ognuno include gli orari delle proiezioni insieme a tutti gli altri dati. Una pagina di programmazione aggiornata ogni 30 minuti per pochi paesi sta nella frequenza più bassa. Non esiste un piano gratuito. Scegli un piano nella pagina dei [prezzi](https://amodb.dev/it/pricing/). ## Domande e risposte ### Come ottengo gli orari delle proiezioni di un film? Invia GET /3/movie/{movie_id}/showtimes?country=US con la tua chiave. Il parametro country è un codice di 2 lettere, e region funziona come alias. La risposta elenca i cinema, e ogni cinema ha le sue proiezioni con orario di inizio, formati, etichette e link di prenotazione quando noti. ### Cosa significa un array results vuoto? Significa che amodb non ha dati sulle proiezioni di quel film in quel paese. Non è un errore, e non dice che il film manchi dai cinema. L'array countries nella stessa risposta elenca comunque dove esistono dati, così puoi proporre un altro paese. ### Quali paesi sono coperti? La copertura varia per paese e titolo. Ogni risposta contiene un array countries con i conteggi di sale, città e proiezioni, fino a 60 paesi, con prima quelli con più proiezioni. Leggilo per ogni film invece di scrivere un elenco nel codice. ### Posso elencare i film che sono al cinema adesso? Sì. GET /3/movie/now_playing con il parametro region elenca le uscite attuali, in cache per 30 minuti. Prendi l'ID di ogni film da quella lista e richiedi le sue proiezioni con lo stesso codice paese. ### Che fuso orario usano i valori start? Un valore start ha l'aspetto 2026-10-18T21:40 e non porta alcuno scarto UTC. Trattalo come ora locale segnata al cinema. Ogni sala ha anche un timezone come Europe/Moscow. Non convertire start nel fuso orario di chi guarda. ## Pagine correlate - [Orari delle proiezioni al cinema](https://amodb.dev/it/showtimes/): API orari delle proiezioni: restituisce cinema e orari di un film in un paese, o un riepilogo per paese. Uniscila ai dettagli o abbinala 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. - [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/cinema-showtimes-api/