API pentru program cinema

Obține programul de proiecții pentru un film

GET /3/movie/{movie_id}/showtimes?country=US întoarce cinematografele care proiectează un film într-o țară, fiecare cu o listă de proiecții. country este un cod de 2 litere. Fără el, results rămâne gol și primești doar totaluri pe țări. Acoperirea variază după țară și titlu, iar un array results gol înseamnă că nu se știe nimic pentru perechea respectivă.

Primești numele cinematografului, lanțul, adresa și fusul orar, iar pentru fiecare proiecție ora de început, sala, formatele, etichetele și un link de rezervare, unde se știu. Se întorc doar proiecțiile de azi încolo. Răspunsul descrie proiecții. Nu este un serviciu de vânzare de bilete.

Ce date primești

Câmpurile din răspunsul cu proiecții:

Un răspuns conține cel mult 1,500 de proiecții, ordonate după cinematograf și apoi după ora de început.

Începe în 3 pași

1. Deschide prețuri și alege un plan. Programul de proiecții este inclus în fiecare plan.
2. Creează o cheie în panoul contului tău.
3. Cere /3/movie/{movie_id}/showtimes cu un cod country și transmite cheia în api_key sau într-un antet Bearer.

Exemplu de cerere

Exemplul bash citește programul pentru Fight Club (ID 550) în Rusia, unde amodb are proiecții pentru el azi. Exemplul JS ia primele cinci filme din lista rusă now_playing și afișează până la trei proiecții pe cinematograf sau o notă când nu se știe nicio proiecție.

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

Răspuns scurtat pentru country=RU: primul cinematograf, cu 2 dintre proiecțiile sale.

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

Acoperire și rezultate goale

Datele de cinema nu sunt disponibile pentru fiecare țară sau titlu. Proiectează-ți interfața ținând cont de asta.

Un array gol nu este o eroare și nu afirmă că filmul lipsește din cinematografe. Înseamnă că nu se cunosc date de proiecție. Vezi erori pentru formatul complet al corpului.

Construiește o pagină de program pentru lansările curente

Combină două endpoint-uri. Lista îți spune ce filme rulează acum, iar programul completează proiecțiile.

O pagină de 20 de filme costă 21 de cereri. Un răspuns pentru o lansare mare poate avea câteva sute de kiloocteți, pentru că include până la 1,500 de proiecții. Pe planul de 20 de cereri pe minut asta înseamnă un minut întreg de buget, așa că adu datele într-un job de fundal și servește vizitatorii din copia ta stocată. Planurile de 40 și 120 de cereri pe minut încap în același job cu rezervă. Vezi limite de cereri pentru fereastră și antete, și tendințe și liste pentru celelalte endpoint-uri de liste.

Păstrează-ți copia proaspătă

Programul se schimbă de la o zi la alta, spre deosebire de detaliile unui film. Stochează fiecare răspuns împreună cu ID-ul filmului, țara și momentul preluării. Un TTL de la 30 de minute până la câteva ore merge pentru majoritatea paginilor de program, iar proiecțiile care au început deja pot fi ascunse comparând start cu ora curentă în timezone al cinematografului. Fiindcă start nu are decalaj, nu-l muta în fusul orar al vizitatorului.

Cum se compară

Prețuri

Planurile plătite în avans durează 1, 3, 6, 12 sau 24 de luni, cu reduceri de 0, 10, 20, 30 sau 40 la sută pentru cele mai lungi. Nimic nu se reînnoiește automat. Planurile permit 20, 40 și 120 de cereri pe minut, iar fiecare include programul de proiecții alături de toate celelalte date. O pagină de program reîmprospătată la fiecare 30 de minute pentru câteva țări încape în ritmul cel mai mic. Nu există nivel gratuit. Alege un plan la prețuri.