https://api.vatadezahar.com/API3
Documentație Cinema România API.
Tot ce ai nevoie pentru a integra datele despre filmele care rulează acum și cele care urmează în cinematografele din România.
Documentație
Integrare simplă, date curate.
Cinema România API este un REST API care oferă filmele care rulează acum și filmele anunțate pentru cinematografele din România, într-un format JSON pregătit pentru site-uri, aplicații, boți sau proiecte personale.
X-API-Key: cheia-ta
JSON
Endpointuri
Filme care rulează acum sau urmează să apară.
Cele două endpointuri principale acoperă listele folosite cel mai des: filme disponibile acum și filme anunțate pentru perioada următoare.
/movies/cinema/ro/all
Returnează filmele care rulează acum în cinematografele suportate.
/movies/cinema/coming-soon
Returnează filmele anunțate sau programate să apară în cinematografe.
Media endpoints
Culori și detecție pentru filme românești.
Pe lângă listele de filme, API-ul oferă endpointuri media care pot fi folosite pentru interfețe adaptive sau pentru a evidenția filmele românești în aplicația ta.
/media/color/movie?id={movie_id}
Returnează culoarea dominantă și o paletă extrasă din posterul filmului. Este util pentru carduri, fundaluri dinamice, embeds Discord sau accente vizuale.
/media/origin/movie?id={movie_id}
Verifică dacă filmul este românesc. Endpointul folosește movie_id și întoarce un rezultat
simplu, pregătit pentru afișare în UI.
{
"ok": true,
"data": {
"media": {
"type": "movie",
"id": "movie_ro_6d6774e508968184",
"title": "Ziua adevărului",
"poster": "https://www.cine-max.ro/..."
},
"accent_color": {
"primary": "#202020",
"primary_int": 2105376,
"discord_recommended": "#204060",
"discord_recommended_int": 2113632,
"palette": [
"#202020",
"#202040",
"#204060"
]
},
"cache": {
"status": "hit",
"color_status": "ready",
"error": null
}
}
}
{
"ok": true,
"data": {
"media": {
"type": "movie",
"id": "movie_ro_1e469d7c894316a4",
"title": "De capul nostru"
},
"origin": {
"is_romanian": true
},
"cache": {
"status": "hit",
"expires_at": 1783567424
}
}
}
const colorResponse = await fetch(
`https://api.vatadezahar.com/API3/media/color/movie?id=${movie.movie_id}`,
{
headers: {
'X-API-Key': 'cheia-ta-api'
}
}
);
const colorData = await colorResponse.json();
const accent =
colorData.data.accent_color.discord_recommended ||
colorData.data.accent_color.primary;
card.style.setProperty('--movie-accent', accent);
const originResponse = await fetch(
`https://api.vatadezahar.com/API3/media/origin/movie?id=${movie.movie_id}`,
{
headers: {
'X-API-Key': 'cheia-ta-api'
}
}
);
const originData = await originResponse.json();
if (originData.data.origin.is_romanian) {
card.classList.add('is-romanian-movie');
}
Autentificare
Cheia API se trimite la fiecare request.
Recomandat este header-ul X-API-Key. Pentru teste rapide, cheia poate fi trimisă și prin query string.
const response = await fetch('https://api.vatadezahar.com/API3/movies/cinema/ro/all', {
headers: {
'X-API-Key': 'cheia-ta-api'
}
});
const data = await response.json();
console.log(data.data.movies);
$ch = curl_init('https://api.vatadezahar.com/API3/movies/cinema/ro/all');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: cheia-ta-api',
'Accept: application/json'
],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data['data']['movies']);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.vatadezahar.com/API3/movies/cinema/ro/all"))
.header("X-API-Key", "cheia-ta-api")
.header("Accept", "application/json")
.GET()
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Structura răspunsului
Fiecare request întoarce un răspuns JSON organizat.
Răspunsul este împărțit în informații despre request, cache și lista de filme.
Datele importante pentru integrare se află în data.
Indică dacă requestul a fost procesat cu succes.
Include endpointul apelat, metoda și timestamp-ul răspunsului.
Conține cache-ul, sursele, regiunea, tipul listei și filmele returnate.
{
"ok": true,
"api": "API3",
"version": "1.0 (vatadezahar.com)",
"meta": {
"timestamp": "2026-07-08T11:36:18+03:00",
"method": "GET",
"endpoint": "/movies/cinema/ro/all"
},
"data": {
"cache": {
"status": "fresh",
"cached_at": 1783479716,
"expires_at": 1783501316,
"ttl_seconds": 1538
},
"list_id": "cinema_ro_all_e7cbd2fe356fa8e0",
"sources": {
"cinemax": {
"name": "CineMAX",
"url": "https://www.cine-max.ro/filme/ruleaza"
},
"cinemacity": {
"name": "Cinema City",
"url": "https://www.cinemacity.ro/"
},
"metadata": {
"name": "TMDB"
}
},
"region": "RO",
"type": "now_playing",
"movies_count": 28,
"movies": []
}
}
Identitate și sincronizare
Listele și filmele pot fi urmărite ușor între refresh-uri.
API-ul oferă identificatori stabili și hash-uri de conținut, astfel încât aplicația ta poate vedea rapid dacă lista s-a schimbat, dacă un film este nou sau dacă datele unui film au fost actualizate.
list_id
Identifică versiunea curentă a listei. Se schimbă atunci când lista de filme se modifică: apare un film nou, dispare un film sau se schimbă informații relevante.
movie_id
ID-ul stabil intern al filmului. Este util când același film există în mai multe surse, dar vrei să îl tratezi ca un singur film în aplicația ta.
content_hash
Se schimbă atunci când se modifică date importante ale filmului, cum ar fi descrierea, posterul, trailerul, formatele, genurile, ratingul, actorii sau disponibilitatea în cinematografe.
function diffMovies(oldMovies, newMovies) {
const oldMap = new Map(oldMovies.map(movie => [movie.movie_id, movie]));
const newMap = new Map(newMovies.map(movie => [movie.movie_id, movie]));
const added = [];
const removed = [];
const updated = [];
for (const [id, movie] of newMap) {
if (!oldMap.has(id)) {
added.push(movie);
continue;
}
if (oldMap.get(id).content_hash !== movie.content_hash) {
updated.push(movie);
}
}
for (const [id, movie] of oldMap) {
if (!newMap.has(id)) {
removed.push(movie);
}
}
return { added, removed, updated };
}
function diffMovies(array $oldMovies, array $newMovies): array
{
$oldMap = [];
$newMap = [];
foreach ($oldMovies as $movie) {
$oldMap[$movie['movie_id']] = $movie;
}
foreach ($newMovies as $movie) {
$newMap[$movie['movie_id']] = $movie;
}
$added = [];
$removed = [];
$updated = [];
foreach ($newMap as $id => $movie) {
if (!isset($oldMap[$id])) {
$added[] = $movie;
continue;
}
if (($oldMap[$id]['content_hash'] ?? '') !== ($movie['content_hash'] ?? '')) {
$updated[] = $movie;
}
}
foreach ($oldMap as $id => $movie) {
if (!isset($newMap[$id])) {
$removed[] = $movie;
}
}
return compact('added', 'removed', 'updated');
}
Cinema + TMDB
Date locale completate cu metadata de film.
API-ul preferă datele din cinematografe atunci când sunt mai relevante pentru România, apoi completează filmul cu informații TMDB acolo unde ajută.
title, description, trailer, formats, cinemas
Titlul românesc, descrierea localizată, trailerul folosit de cinema, formatele disponibile și linkurile către cinematografe vin preferabil din sursele cinema.
tmdb.poster, tmdb.backdrop, tmdb.rating, featured_actors
TMDB este folosit pentru metadata suplimentară: imagini, rating, genuri, titlu original, actori principali și link către profilul filmului.
genres + combined_genres
Unele câmpuri sunt păstrate separat, iar altele sunt combinate pentru filtre mai bune. Astfel poți afișa date locale, dar poți avea și o listă mai completă pentru căutare.
{
"title": "Invitația vecinilor",
"original_title": "The Invite",
"description": "Descriere localizată în română...",
"poster": "https://www.cine-max.ro/...",
"trailer": "https://www.youtube.com/watch?v=...",
"formats": ["2D", "Laser Barco", "Subtitrat", "VIP"],
"genres": ["Comedie", "Dramă"],
"combined_genres": ["Comedie", "Dramă"],
"cinemas": [
{
"source": "cinemax",
"name": "CineMAX",
"url": "https://www.cine-max.ro/..."
},
{
"source": "cinemacity",
"name": "Cinema City",
"url": "https://www.cinemacity.ro/..."
}
],
"tmdb": {
"matched": true,
"id": 950028,
"url": "https://www.themoviedb.org/movie/950028",
"original_title": "The Invite",
"rating": {
"average": 7.9,
"count": 17
},
"poster": "https://image.tmdb.org/...",
"backdrop": "https://image.tmdb.org/...",
"featured_actors": []
}
}
const poster = movie.poster || movie.tmdb?.poster;
const backdrop = movie.tmdb?.backdrop;
const trailer = movie.trailer;
const displayGenres = movie.genres || [];
const filterGenres = movie.combined_genres || movie.genres || [];
const cinemas = movie.cinemas.map(cinema => cinema.name).join(', ');
console.log({
title: movie.title,
originalTitle: movie.tmdb?.original_title || movie.original_title,
poster,
backdrop,
trailer,
cinemas,
displayGenres,
filterGenres
});
Linkuri externe
Pagini externe pregătite pentru fiecare film.
Atunci când există o potrivire verificată, obiectul
external_links poate include linkuri directe către IMDb
și Cinemagia. Fiecare link este opțional și trebuie verificat înainte
de afișare.
external_links.imdb
Link direct către pagina filmului pe IMDb. Câmpul este prezent doar atunci când API-ul are o potrivire disponibilă.
external_links.cinemagia
Link direct către pagina filmului pe Cinemagia. Poate exista chiar și atunci când filmul nu are o potrivire TMDB.
external_links
Obiectul și linkurile din interiorul lui sunt opționale. Un film poate avea ambele linkuri, doar unul dintre ele sau niciunul.
{
"external_links": {
"imdb": "https://www.imdb.com/title/tt31170389/",
"cinemagia": "https://www.cinemagia.ro/filme/evil-dead-burn-3319097/"
}
}
const externalLinks = movie.external_links || {};
if (externalLinks.imdb) {
console.log('IMDb:', externalLinks.imdb);
}
if (externalLinks.cinemagia) {
console.log('Cinemagia:', externalLinks.cinemagia);
}
$externalLinks = $movie['external_links'] ?? [];
if (!empty($externalLinks['imdb'])) {
echo 'IMDb: ' . $externalLinks['imdb'] . PHP_EOL;
}
if (!empty($externalLinks['cinemagia'])) {
echo 'Cinemagia: ' . $externalLinks['cinemagia'] . PHP_EOL;
}
Structura unui film
Fiecare film vine cu date pregătite pentru afișare și filtrare.
Obiectul unui film include informații locale din cinema, identificatori stabili, formate, genuri, linkuri externe, imagini și metadata TMDB. Unele câmpuri sunt opționale și apar doar atunci când informația este disponibilă.
title,
description,
poster,
placeholder_poster,
trailer,
age_rating,
duration_minutes
available_in,
cinemas,
formats,
release_date
tmdb,
external_links,
genres,
combined_genres,
featured_actors
{
"movie_id": "movie_ro_792aa3cc7dac9844",
"content_hash": "movie_content_161f785575361fea",
"title": "Invitația vecinilor",
"original_title": "The Invite",
"description": "Descriere localizată în română...",
"poster": "https://www.cine-max.ro/...",
"trailer": "https://www.youtube.com/watch?v=...",
"age_rating": "AP12",
"duration_minutes": 108,
"formats": ["2D", "Laser Barco", "Subtitrat", "VIP"],
"genres": ["Comedie", "Dramă"],
"combined_genres": ["Comedie", "Dramă"],
"available_in": ["cinemax", "cinemacity"],
"cinemas": [
{
"source": "cinemax",
"name": "CineMAX",
"url": "https://www.cine-max.ro/..."
}
],
"tmdb": {
"matched": true,
"id": 950028,
"url": "https://www.themoviedb.org/movie/950028",
"poster": "https://image.tmdb.org/...",
"backdrop": "https://image.tmdb.org/...",
"rating": {
"average": 7.9,
"count": 17
},
"featured_actors": []
},
"external_links": {
"imdb": "https://www.imdb.com/title/tt950028/",
"cinemagia": "https://www.cinemagia.ro/filme/exemplu-film/"
}
}
function movieCard(movie) {
const hasRealPoster = Boolean(
movie.poster ||
movie.tmdb?.poster
);
const poster =
movie.poster ||
movie.tmdb?.poster ||
movie.placeholder_poster ||
null;
return {
title: movie.title,
originalTitle: movie.tmdb?.original_title || movie.original_title,
description: movie.description || movie.tmdb?.overview,
poster,
hasRealPoster,
backdrop: movie.tmdb?.backdrop,
trailer: movie.trailer,
cinemas: movie.cinemas.map(cinema => cinema.name).join(', '),
formats: movie.formats.join(', '),
genres: movie.genres.join(', '),
ageRating: movie.age_rating,
duration: movie.duration_minutes,
imdb: movie.external_links?.imdb || null,
cinemagia: movie.external_links?.cinemagia || null
};
}
function movieCard(array $movie): array
{
$hasRealPoster =
!empty($movie['poster'])
|| !empty($movie['tmdb']['poster']);
$poster =
$movie['poster']
?? $movie['tmdb']['poster']
?? $movie['placeholder_poster']
?? null;
return [
'title' => $movie['title'] ?? null,
'originalTitle' => $movie['tmdb']['original_title'] ?? $movie['original_title'] ?? null,
'description' => $movie['description'] ?? $movie['tmdb']['overview'] ?? null,
'poster' => $poster,
'hasRealPoster' => $hasRealPoster,
'backdrop' => $movie['tmdb']['backdrop'] ?? null,
'trailer' => $movie['trailer'] ?? null,
'cinemas' => implode(', ', array_column($movie['cinemas'] ?? [], 'name')),
'formats' => implode(', ', $movie['formats'] ?? []),
'genres' => implode(', ', $movie['genres'] ?? []),
'ageRating' => $movie['age_rating'] ?? null,
'duration' => $movie['duration_minutes'] ?? null,
'imdb' => $movie['external_links']['imdb'] ?? null,
'cinemagia' => $movie['external_links']['cinemagia'] ?? null,
];
}
Exemple practice
Integrarea începe cu câteva linii de cod.
Exemplele de mai jos ilustrează câteva scenarii întâlnite frecvent. Le poți adapta cu ușurință în funcție de proiectul tău.
Filme disponibile în Cinema City
Verifică rapid dacă un film rulează în Cinema City folosind câmpul
available_in.
const movies = data.data.movies;
const cinemaCityMovies = movies.filter(movie =>
movie.available_in.includes("cinemacity")
);
console.log(cinemaCityMovies);
$movies = $response['data']['movies'];
$cinemaCityMovies = array_filter(
$movies,
fn($movie) => in_array('cinemacity', $movie['available_in'])
);
print_r($cinemaCityMovies);
Filme subtitrate
Formatele provin din cinematografe și pot fi folosite pentru filtre sau afișare.
const subtitledMovies = movies.filter(movie =>
movie.formats.includes("Subtitrat")
);
$subtitledMovies = array_filter(
$movies,
fn($movie) => in_array('Subtitrat', $movie['formats'])
);
Poster recomandat și fallback
API-ul preferă posterul oferit de cinematograf, apoi posterul TMDB.
Dacă niciuna dintre surse nu are un poster real, câmpul
placeholder_poster oferă o imagine de rezervă.
const hasRealPoster = Boolean(
movie.poster ||
movie.tmdb?.poster
);
const poster =
movie.poster ||
movie.tmdb?.poster ||
movie.placeholder_poster ||
'/images/no-cover.png';
if (!hasRealPoster) {
card.classList.add('has-placeholder-poster');
}
image.src = poster;
$hasRealPoster =
!empty($movie['poster'])
|| !empty($movie['tmdb']['poster']);
$poster =
$movie['poster']
?? $movie['tmdb']['poster']
?? $movie['placeholder_poster']
?? '/images/no-cover.png';
if (!$hasRealPoster) {
echo 'Filmul nu are momentan un poster real.';
}
{
"title": "Teambuilding 2",
"poster": null,
"tmdb": {
"matched": false
},
"placeholder_poster": "https://data-erots.vatadezahar.com/vatadezahar/movies/0e0dc9c7-1673-48bd-b25a-10860cd8339c.png"
}
Trailer oficial
Trailerul este preferat din cinematografe deoarece, în majoritatea cazurilor, este versiunea oficială utilizată în România și include subtitrare.
if (movie.trailer) {
window.open(movie.trailer);
}
if (!empty($movie['trailer'])) {
echo $movie['trailer'];
}
Referință câmpuri
De unde provin informațiile?
Nu toate câmpurile provin din aceeași sursă. API-ul preferă datele locale atunci când acestea sunt mai relevante pentru România și completează informațiile cu metadata TMDB acolo unde este util.
title
Cinema
Titlul afișat utilizatorului. Se preferă varianta în limba română atunci când există.
original_title
TMDB
Titlul original al filmului.
description
Cinema
Descriere localizată în română. Dacă lipsește, poate fi completată din TMDB.
poster
Cinema
Posterul principal recomandat pentru afișare.
tmdb.poster
TMDB
Poster alternativ din TMDB.
placeholder_poster
API
Imagine de rezervă trimisă doar atunci când filmul nu are poster disponibil nici din cinematograf și nici din TMDB. Poate fi afișată direct sau folosită pentru detectarea filmelor fără poster real.
tmdb.backdrop
TMDB
Imagine wide, potrivită pentru bannere și fundaluri.
external_links
API
Obiect opțional care grupează linkurile externe disponibile pentru film.
external_links.imdb
IMDb
Link către pagina filmului pe IMDb, atunci când există o potrivire disponibilă.
external_links.cinemagia
Cinemagia
Link către pagina filmului pe Cinemagia, atunci când aceasta este disponibilă.
trailer
Cinema
Trailerul preferat este cel oferit de cinematograf deoarece, în majoritatea cazurilor, este versiunea oficială folosită în România și include subtitrare.
genres
Cinema
Genurile utilizate de cinematografe.
combined_genres
Cinema + TMDB
Genurile locale completate cu cele din TMDB pentru filtre mai complete.
formats
Cinema
Formatele disponibile precum IMAX, 4DX, VIP, Subtitrat sau Dublat.
featured_actors
TMDB
Actorii principali ai distribuției.
rating
TMDB
Ratingul și numărul de voturi disponibile în TMDB.
release_date
Cinema
Data principală de lansare în cinematografele din România.
cinemas
Cinema
Cinematografele în care rulează filmul și linkurile oficiale către paginile acestuia.
Release date
Datele de lansare pot fi comparate între surse.
Pentru filmele care urmează să apară, API-ul poate include data principală de lansare și, atunci când există informații suficiente, data raportată de fiecare cinematograf.
release_date
Data principală de lansare folosită pentru afișare. Este valoarea pe care o poți folosi cel mai simplu în carduri, liste sau notificări.
release_date_info.same_release_date
Indică dacă sursele disponibile raportează aceeași dată de lansare.
Dacă valoarea este false, datele pot fi verificate individual.
release_date_info.by_source
Conține data de lansare raportată de fiecare sursă, de exemplu CineMAX sau Cinema City.
Lista coming-soon reflectă întotdeauna informațiile disponibile în cinematografe la momentul respectiv.
Se întâmplă ocazional ca un film anunțat să fie retras temporar din secțiunea Coming Soon de către unul sau mai multe cinematografe. Motivele nu sunt întotdeauna publice și pot varia: modificări de program, amânări, actualizări interne, aspecte comerciale sau alte schimbări de ultim moment.
În aceste situații, API-ul va elimina automat filmul din listă până când acesta reapare în sursa oficială. Dacă filmul este publicat din nou după câteva zile sau săptămâni, el va reveni și în API.
Din acest motiv, este recomandat ca lista coming-soon să fie tratată ca o fotografie a programului curent, nu ca o confirmare definitivă că un film va avea premiera la data inițială.
Pentru filmele care rulează deja în cinematografe, endpointul /movies/cinema/ro/all, astfel de situații sunt foarte rare, iar disponibilitatea este în general mult mai stabilă.
{
"title": "Exemplu film",
"release_date": "2026-08-21",
"release_date_info": {
"same_release_date": true,
"release_date": "2026-08-21",
"by_source": {
"cinemax": "2026-08-21",
"cinemacity": "2026-08-21"
}
}
}
const releaseDate = movie.release_date_info?.release_date || movie.release_date;
if (movie.release_date_info?.same_release_date === false) {
console.log('Date diferite între cinematografe:');
console.log(movie.release_date_info.by_source);
}
console.log(`Data principală: ${releaseDate}`);
$releaseDate =
$movie['release_date_info']['release_date']
?? $movie['release_date']
?? null;
if (($movie['release_date_info']['same_release_date'] ?? true) === false) {
print_r($movie['release_date_info']['by_source']);
}
echo 'Data principală: ' . $releaseDate;
Erori
Erorile au același format peste tot.
HTTP status-ul descrie rezultatul requestului, iar error.code este identificatorul stabil
pe care îl poți folosi în aplicație.
{
"ok": false,
"error": {
"code": "invalid_api_key",
"message": "The provided API key is invalid."
},
"meta": {
"timestamp": 1783200000
}
}
missing_api_key
Cheia API lipsește din request.
invalid_api_key
Cheia API trimisă nu este validă.
api_key_disabled
Cheia API există, dar a fost dezactivată.
ip_not_allowed
IP-ul curent nu este permis pentru cheia API folosită.
rate_limit_exceeded
Limita de requesturi a fost depășită.
cache_not_ready
Cache-ul de filme nu este încă pregătit. Încearcă din nou mai târziu.
endpoint_not_found
Endpointul cerut nu există.
method_not_allowed
Metoda HTTP folosită nu este permisă pentru endpoint.
internal_server_error
A apărut o eroare internă. Stack trace-ul nu este expus în producție.
error.code în codul aplicației, nu message.
Mesajele pot fi îmbunătățite în timp, dar codurile de eroare rămân stabile.
FAQ
Întrebări frecvente.
Câteva clarificări despre felul în care sunt alese, verificate și expuse datele în API.
API-ul încearcă să afișeze titlul folosit în România atunci când acesta există.
De aceea, title poate fi diferit de titlul original din TMDB,
în timp ce original_title păstrează denumirea originală a filmului.
Descrierea este preluată preferabil din cinematografe deoarece este adaptată publicului din România. Dacă aceasta nu este disponibilă, API-ul poate folosi descrierea din TMDB ca alternativă.
În majoritatea cazurilor, trailerul furnizat de cinematograf este cel folosit oficial în România și include subtitrare. Din acest motiv, API-ul îl preferă atunci când este disponibil.
Filmele noi și modificările importante trec printr-un proces de verificare înainte să ajungă în API. Asta reduce riscul ca date greșite, duplicate sau potriviri incorecte să fie publicate automat.
genres conține genurile furnizate de cinematografe.
combined_genres completează aceste informații cu genurile disponibile în TMDB
și este util pentru filtre sau căutări mai complete.
Nu. Poți folosi doar câmpurile de care ai nevoie. O integrare simplă poate afișa titlul, posterul și descrierea, iar un proiect mai complex poate folosi ID-urile, hash-urile, formatele, cinematografele, actorii sau datele TMDB.
Uneori un film este anunțat înainte ca un poster oficial să fie
disponibil în cinematografe sau în TMDB. În această situație,
poster rămâne null, iar API-ul trimite
placeholder_poster.
Poți afișa imaginea oferită de API sau poți folosi existența câmpului pentru a detecta lipsa posterului real și a construi propriul design „No cover”.