# API pentru program cinema > API-ul pentru program cinema este GET /3/movie/{movie_id}/showtimes?country=US. Întoarce cinematografe cu adresă și fus orar, iar fiecare proiecție are ora de început, formate și link de rezervare, unde se știu. Fără country primești doar totaluri pe țări. Acoperirea variază după titlu, iar un array results gol înseamnă că nu se știe nimic. ## 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 | Endpoint | Întoarce | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `GET /3/movie/{movie_id}/showtimes` | Cinematografele și proiecțiile unui film în `country`, sau totaluri pe țări fără el | | `GET /3/movie/now_playing` | Filmele aflate acum în cinematografe, restrânse prin `region` | | `GET /3/movie/{movie_id}` cu `append_to_response=showtimes` | Detalii plus program de proiecții într-o singură cerere, vezi [programe de proiecții](https://amodb.dev/ro/showtimes/) | Câmpurile din răspunsul cu proiecții: | Câmp | Tip | Semnificație | | ---------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------- | | `id` | număr întreg | ID-ul filmului | | `country` | șir sau null | Codul de 2 litere cerut, `null` dacă niciunul nu a fost valid | | `results` | array | Un element pe cinematograf, gol când nu se știe nimic sau lipsește `country` | | `countries` | array | Totaluri pe țări: `country`, `name`, `venues`, `cities`, `showtimes`, `first_day`, `last_day` | | `results[].id`, `name`, `city`, `address` | număr întreg, șiruri | ID-ul, numele, orașul și adresa stradală ale cinematografului | | `results[].chain` | obiect sau null | `key` și `name` ale lanțului de cinematografe | | `results[].timezone` | șir sau null | Zona IANA a cinematografului, de exemplu `Europe/Moscow` | | `results[].latitude`, `longitude` | număr sau null | Poziția, când se știe | | `results[].region`, `postal_code`, `phone`, `url` | șir sau null | Alte detalii despre cinematograf, adesea null | | `results[].showtimes` | array | Proiecțiile de la acel cinematograf | | `showtimes[].date` | șir | Ziua locală, precum `2026-10-18` | | `showtimes[].start` | șir | Ora locală de început, precum `2026-10-18T21:40`, fără decalaj | | `showtimes[].auditorium` | șir sau null | Numele sau numărul sălii | | `showtimes[].formats` | array | Formatele proiecției, de exemplu `2D`, `IMAX` sau `Dolby Atmos` | | `showtimes[].tags` | array | Etichete suplimentare, precum `Reserved Seating` | | `showtimes[].booking_url` | șir sau null | Link pentru cumpărarea unui bilet, când se știe | | `showtimes[].sold_out` | boolean | `true` când sursa marchează proiecția ca epuizată | | `showtimes[].end`, `audio`, `subtitles`, `language`, `price`, `currency`, `prices` | diverse, adesea null | Completate doar când sursa cinematografului le oferă | 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](https://amodb.dev/ro/pricing/) ș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. ```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}`); } } ``` Răspuns scurtat pentru `country=RU`: primul cinematograf, cu 2 dintre proiecțiile sale. ```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" } ] } ``` ## Acoperire și rezultate goale Datele de cinema nu sunt disponibile pentru fiecare țară sau titlu. Proiectează-ți interfața ținând cont de asta. | Situație | Ce vezi | Ce faci | | --------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------- | | Proiecții cunoscute | `results` are un element pe cinematograf | Arată lista | | Nu se știe nimic pentru această țară și acest titlu | `results` este un array gol, `countries` listează unde există date | Arată o notă neutră, nu un tabel gol | | Nu s-a trimis `country` | `results` este gol, `country` este `null`, `countries` are totaluri | Lasă utilizatorul să aleagă din `countries` | | ID de film necunoscut | 404 cu `status_code` 34 | Verifică ID-ul | | Ai depășit limita | 429 cu `status_code` 25 | Așteaptă numărul de secunde din `Retry-After` | 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](https://amodb.dev/ro/errors/) 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. | Pas | Cerere | Observații | | --- | ---------------------------------------------- | ---------------------------------------------------- | | 1 | `GET /3/movie/now_playing?region=US&page=1` | Până la 20 de filme pe pagină, în cache 30 de minute | | 2 | `GET /3/movie/{movie_id}/showtimes?country=US` | Un apel pe film, în cache 30 de minute | | 3 | Filtrează în codul tău | După `city`, `formats` sau `tags` | 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](https://amodb.dev/ro/rate-limits/) pentru fereastră și antete, și [tendințe și liste](https://amodb.dev/ro/trending-lists/) 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ă | Capacitate | Extragi date de pe site-urile cinematografelor | API de metadate fără program de proiecții | amodb | | ------------------------ | ---------------------------------------------- | ----------------------------------------- | ----------------------------------------------------- | | Configurare | Câte un scraper pentru fiecare site de cinema | Indisponibil | Un endpoint, o singură structură JSON | | Legarea de un ID de film | Potrivești după textul titlului | Indisponibil | ID-ul filmului în cale | | Acoperire | Ce poți extrage | Niciuna | Variază după țară și titlu, array gol când nu se știe | | Formate și rezervare | Analizezi etichete și linkuri | Indisponibil | Câmpurile `formats`, `tags` și `booking_url` | | Întreținere | Se strică când un site se schimbă | Niciuna | O singură structură JSON pentru fiecare țară | ## 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](https://amodb.dev/ro/pricing/). ## Întrebări și răspunsuri ### Cum obțin programul de proiecții pentru un film? Trimite GET /3/movie/{movie_id}/showtimes?country=US cu cheia ta. Parametrul country este un cod de 2 litere, iar region funcționează ca alias. Răspunsul listează cinematografele, iar fiecare cinematograf are proiecțiile sale cu ora de început, formate, etichete și link de rezervare, unde se știu. ### Ce înseamnă un array results gol? Înseamnă că amodb nu are date de proiecție pentru filmul respectiv în țara respectivă. Nu este o eroare și nu spune că filmul lipsește din cinematografe. Array-ul countries din același răspuns listează în continuare unde există date, deci poți propune altă țară. ### Ce țări sunt acoperite? Acoperirea variază după țară și titlu. Fiecare răspuns conține un array countries cu numărul de cinematografe, orașe și proiecții, până la 60 de țări, cu cele mai multe proiecții primele. Citește-l pentru fiecare film, în loc să scrii o listă fixă în cod. ### Pot lista filmele care rulează acum în cinematografe? Da. GET /3/movie/now_playing cu parametrul region listează lansările curente, ținute în cache 30 de minute. Ia ID-ul fiecărui film din listă și cere programul lui cu același cod de țară. ### Ce fus orar folosesc valorile start? O valoare start arată ca 2026-10-18T21:40 și nu are decalaj UTC. Tratează-o ca oră locală de pe ceasul cinematografului. Fiecare sală are și un timezone precum Europe/Moscow. Nu converti start în fusul orar al spectatorului. ## Pagini conexe - [Program de proiecții în cinema](https://amodb.dev/ro/showtimes/): API program proiecții: cinematografe și ore ale unui film într-o țară, sau un rezumat pe țări. Îmbină-l în detalii sau combină-l cu now_playing. - [Endpoint-uri pentru tendințe și liste](https://amodb.dev/ro/trending-lists/): API filme în tendințe cu căi TMDB v3: topuri pe zi și săptămână, plus now playing, populare, bine cotate și viitoare pentru filme și TV, în cache 30 de minute. - [API detalii film](https://amodb.dev/ro/movies/): API detalii film cu aceleași căi și același JSON ca TMDB v3. Preia un film după ID, adaugă credite, evaluări și atmosferă cu append_to_response, în 14 limbi. - [Limite de cereri](https://amodb.dev/ro/rate-limits/): amodb limitează fiecare cheie în cereri pe minut, în fereastră glisantă de 60 de secunde: 20, 40 sau 120. Citește antetele și tratează 429 cu Retry-After. - [Ghid rapid](https://amodb.dev/ro/quickstart/): Fă primul apel amodb: ia o cheie, cere detaliile unui film în curl, JavaScript, Python, PHP sau Go, apoi încarcă posterul de pe img.amodb.dev. Sub 2 minute. Actualizat: 2026-10-18. Source: https://amodb.dev/ro/cinema-showtimes-api/