Program de proiecții în cinema

Obține programul de proiecții al unui film

GET /3/movie/{movie_id}/showtimes?country=RU întoarce cinematografele care proiectează un film într-o țară, cu proiecțiile datate de la fiecare. Parametrul country primește un cod de două litere, cu litere mari sau mici. Acoperirea variază după țară și titlu, deci datele sunt prezente acolo unde se cunosc și lipsesc unde nu. Se întorc doar zilele de azi încolo.

Exemplul cere Fight Club în Rusia și tratează un răspuns gol.

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_idcaleobligatoriu
  ID numeric de film, de exemplu 550.
• countryinterogare
  Cod de țară din două litere, precum RU. Fără el primești doar rezumatul pe țări. region este un alias.
• api_keyinterogareuna dintre cele două
  Cheia ta. Folosește-o pe aceasta sau antetul Authorization: Bearer.

Câmpurile răspunsului

Citește după nume cheile pe care le folosești și sari peste cheile suplimentare dintr-un obiect de cinematograf sau de proiecție. Multe câmpuri sunt azi null, pentru că nu toate cinematografele le trimit.

Exemplu de răspuns

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

Lista este tăiată la 1 din 2 cinematografe și 2 din 4 proiecții. Proiecțiile există doar pentru zilele care nu au trecut, deci acest răspuns se schimbă în fiecare zi.

Obține rezumatul pe țări

Lasă deoparte country și răspunsul conține doar totaluri. results rămâne gol, iar country este null. Array-ul countries listează până la 60 de țări care mai au o proiecție, cea cu cele mai multe proiecții prima. Folosește-l ca să afli unde rulează un titlu înainte să ceri cinematografele.

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 cod de țară fără date, precum country=US pentru acest film, răspunde cu country ca US, un results gol și aceeași listă countries. Un titlu fără proiecții nicăieri, precum serialul 1396, are "countries": [].

Adaugă programul la un apel de detalii

append_to_response=showtimes îmbină același bloc într-un răspuns de detalii sub cheia showtimes. Trimite codul country în aceeași cerere. Blocul își păstrează propriile chei id, country, results și countries.

Se numără ca o singură cerere, deci o pagină de film care arată distribuția și proiecțiile are nevoie de un singur apel. Același endpoint există pentru seriale ca GET /3/tv/{tv_id}/showtimes.

Combină cu now_playing și region

Lista now playing îți dă titlurile. Endpoint-ul de program îți dă proiecțiile pentru un singur titlu. Îmbină-le în codul tău.

Bucla de mai jos reîncearcă o dată sau de două ori când se atinge limita planului, așteptând numărul de secunde din 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');
}

O pagină de 20 de titluri înseamnă 20 de cereri de program. Pe planul de 20 de cereri pe minut asta folosește toată fereastra, deci pune rezultatul în cache la tine. Vezi tendințe și liste pentru parametrii listei.

Erori

Corpul de eroare urmează TMDB: success, status_code și status_message. O cheie greșită arată status_code 7.

Lipsa programului nu este o eroare: așteaptă-te la starea 200 și un array results gol. Nici un country lipsă sau invalid nu este o eroare. Vezi erori și limite de cereri.

Note practice

• Acoperirea variază după țară și titlu. Tratează un array results gol ca necunoscut, nu ca „nu rulează”.
• Arată start exact cum este întors. Este ora locală a cinematografului, fără decalaj UTC, iar ceasul cinematografului este ceea ce se așteaptă vizitatorii.
• Programul este ținut în cache la margine 30 de minute. Nu-l cere la fiecare afișare de pagină și ține-ți propriul cache scurt.
• Reutilizează o singură listă now playing pentru toți vizitatorii dintr-o regiune. Este ținută în cache 30 de minute și la margine.
• Folosește booking_url ca să trimiți un vizitator la pagina de rezervare a cinematografului. Este null când cinematograful nu dă niciun link.
• Pentru prezentarea cazului de utilizare, vezi API pentru program cinema, iar pentru celelalte date despre un film, vezi filme.