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.

REST API JSON HTTPS Cinema City CineMAX TMDB

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.

Base URL https://api.vatadezahar.com/API3
Autentificare X-API-Key: cheia-ta
Format răspuns 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.

GET /movies/cinema/ro/all

Returnează filmele care rulează acum în cinematografele suportate.

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

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

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

Film românesc
{
  "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.

ok

Indică dacă requestul a fost procesat cu succes.

meta

Include endpointul apelat, metoda și timestamp-ul răspunsului.

data

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

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

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

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

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

Afișare

title, description, poster, placeholder_poster, trailer, age_rating, duration_minutes

Disponibilitate

available_in, cinemas, formats, release_date

Metadata și linkuri

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"
}
Ce indică placeholder_poster? Dacă acest câmp este prezent, filmul nu are momentan un poster real disponibil nici din cinematograf și nici din TMDB. Poți folosi imaginea oferită de API sau poți trata prezența câmpului ca semnal pentru propriul design „No cover”.

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.

Câmp Sursă Descriere
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.

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

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

SOURCE release_date_info.by_source

Conține data de lansare raportată de fiecare sursă, de exemplu CineMAX sau Cinema City.

Important despre coming-soon

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
  }
}
401 missing_api_key

Cheia API lipsește din request.

401 invalid_api_key

Cheia API trimisă nu este validă.

403 api_key_disabled

Cheia API există, dar a fost dezactivată.

403 ip_not_allowed

IP-ul curent nu este permis pentru cheia API folosită.

429 rate_limit_exceeded

Limita de requesturi a fost depășită.

503 cache_not_ready

Cache-ul de filme nu este încă pregătit. Încearcă din nou mai târziu.

404 endpoint_not_found

Endpointul cerut nu există.

405 method_not_allowed

Metoda HTTP folosită nu este permisă pentru endpoint.

500 internal_server_error

A apărut o eroare internă. Stack trace-ul nu este expus în producție.

Recomandare: folosește 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”.