Orari delle proiezioni al cinema

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.

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

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);
  }
}

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
$url = 'https://api.amodb.dev/3/movie/550/showtimes?country=RU';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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;
    }
}

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

• movie_idpercorsoobbligatorio
  ID numerico del film, per esempio 550.
• countryquery
  Codice paese di due lettere come RU. Senza, ottieni solo il riepilogo per paese. region è un alias.
• api_keyqueryuno dei due
  La tua chiave. Usa questa o l'header Authorization: Bearer.

Campi della risposta

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

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

curl -sf "https://api.amodb.dev/3/movie/550/showtimes" \
  -H "Authorization: Bearer $AMODB_KEY"

{
  "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"
    }
  ]
}

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.

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.

Il ciclo qui sotto ritenta una o due volte quando si raggiunge il limite del piano, attendendo i secondi di Retry-After.

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

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 e limiti di richieste.

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, e per gli altri dati di un film, vedi film.