API orari dei cinema

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

Campi della risposta delle proiezioni:

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 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.

curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -H "Authorization: Bearer $AMODB_KEY"

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.

{
  "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.

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 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.

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 per la finestra e gli header, e tendenze e liste 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

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.