Wander Movie Critic API

REST API pre prístup k databáze filmov na slovenskom kinovom trhu. Získaj dáta o filmoch, distribútoroch, hodnoteniach (CSFD, Rotten Tomatoes, TMDB) a scoring verdikty pre oba typy kín — Tulavé kino a Sterio kino.

https://api.tulavekino.sk/api/kompas

Formát odpovede

Všetky odpovede sú vo formáte JSON. Kódovanie: UTF-8. Dátumy sú vo formáte YYYY-MM-DD alebo ISO 8601.

Stránkovanie

Endpointy, ktoré vracajú zoznamy, podporujú stránkovanie cez parametre limit (max 500, default 50) a offset. Odpoveď obsahuje pole total s celkovým počtom záznamov.

Autentifikácia

Všetky API requesty vyžadujú platný API kľúč. Kľúč posielaj v hlavičke X-API-Key každého requestu.

Ako získať kľúč

API kľúče vydáva administrátor. Kontaktuj nás na maros.sollar@gmail.com s popisom tvojej aplikácie.

Formát kľúča

Kľúč má prefix wmc_ nasledovaný 32 hexadecimálnymi znakmi. Príklad: wmc_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Bezpečnosť

Nikdy nezdieľaj kľúč vo verejnom kóde alebo repozitári
Používaj HTTPS — kľúč sa prenáša v hlavičke requestu
Ak máš podozrenie na únik, kontaktuj admina pre revokáciu

curl -H "X-API-Key: wmc_your_key_here" \
  https://api.tulavekino.sk/api/kompas/stats

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/stats',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const data = await res.json();

Rate Limity

Každý API kľúč má nastavený limit requestov za minútu (default: 100 req/min). Po prekročení limitu server vráti 429 Too Many Requests.

Response headers

Header	Popis
X-RateLimit-Limit	Maximálny počet requestov za minútu
X-RateLimit-Remaining	Zostávajúci počet requestov v aktuálnom okne
Retry-After	Počet sekúnd do resetu (len pri 429)

Odporúčanie

Pri integrácii (napr. Google Sheets) pridaj pauzu medzi requestami. Pre väčšie dátové sady použi limit a offset namiesto mnohých malých requestov.

GET /api/kompas/films

Vráti stránkovaný zoznam filmov s hodnoteniami a scoring verdiktmi.

Query parametre

Parameter	Typ	Popis
distributor optional	string	Filter podľa distribútora (napr. `Continental Film`)
country optional	string	Filter podľa krajiny pôvodu (`SK`, `CZ`, `US`...)
from optional	string	Premiéra od dátumu (`YYYY-MM-DD`)
to optional	string	Premiéra do dátumu (`YYYY-MM-DD`)
updated_since optional	string	Len filmy aktualizované od tohto dátumu (`YYYY-MM-DD`)
limit optional	integer	Počet výsledkov (default: 50, max: 500)
offset optional	integer	Preskoč prvých N výsledkov (default: 0)

curl -H "X-API-Key: wmc_your_key_here" \
  "https://api.tulavekino.sk/api/kompas/films?limit=10&from=2026-01-01"

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/films?limit=10&from=2026-01-01',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const { total, films } = await res.json();

GET /api/kompas/films/:id

Vráti kompletný detail jedného filmu vrátane hodnotení, médií a scoring verdiktu.

URL parametre

Parameter	Typ	Popis
id required	integer	ID filmu v databáze

curl -H "X-API-Key: wmc_your_key_here" \
  https://api.tulavekino.sk/api/kompas/films/42

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/films/42',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const film = await res.json();

GET /api/kompas/films/search

Hľadanie filmov podľa názvu (slovenský alebo originálny). Vráti max 50 výsledkov.

Query parametre

Parameter	Typ	Popis
q required	string	Hľadaný text (min. 2 znaky)

curl -H "X-API-Key: wmc_your_key_here" \
  "https://api.tulavekino.sk/api/kompas/films/search?q=minecraft"

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/films/search?q=minecraft',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const films = await res.json();

GET /api/kompas/distributors

Vráti zoznam aktívnych slovenských filmových distribútorov s kategóriami.

Distribútori sú rozdelení do kategórií: velki (veľkí), stredni (strední), mali (malí).

curl -H "X-API-Key: wmc_your_key_here" \
  https://api.tulavekino.sk/api/kompas/distributors

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/distributors',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const distributors = await res.json();

GET /api/kompas/stats

Vráti súhrnné štatistiky databázy — počet filmov, pokrytie dát, rozdelenie podľa distribútorov.

curl -H "X-API-Key: wmc_your_key_here" \
  https://api.tulavekino.sk/api/kompas/stats

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/stats',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const stats = await res.json();

Dátový model — Film

Kompletný objekt filmu vrátený z endpointov /films a /films/:id.

Základné informácie

id integer Unikátne ID filmu

nazov_sk string Slovenský názov filmu

nazov_original string? Originálny názov

datum_sk_premiera string? Dátum SK premiéry (YYYY-MM-DD)

world_premiere string? Svetová premiéra (YYYY-MM-DD)

distributor string? Názov distribútora na Slovensku

origin_country string? Krajina pôvodu (SK, CZ, US...)

stopaz_min integer? Stopáž v minútach

vekova_kategoria string? Veková kategória (7+, 12+, 15+, 18+, bez obmedzenia)

jazyk string? Jazyková verzia (slovenský dabing, české titulky...)

Médiá

poster_url string? URL plagátu

backdrop_url string? URL pozadia (backdrop)

trailer_url string? YouTube trailer URL

images array Pole obrázkov (TMDB)

Tvorcovia

rezia string? Režisér

herci array Pole hercov (top 10)

zanre array Pole žánrov

Texty

overview string? Synopsa / popis

tagline string? Tagline

keywords array Kľúčové slová

Distribučné práva

prava_od string? Začiatok distribučných práv (YYYY-MM-DD)

prava_do string? Koniec distribučných práv (YYYY-MM-DD)

Hodnotenia — `ratings`

ratings.csfd number? CSFD hodnotenie (0-100%)

ratings.csfd_votes integer? Počet hlasov na CSFD

ratings.rotten_tomatoes_critics number? Tomatometer (0-100%)

ratings.rotten_tomatoes_audience number? Popcornmeter (0-100%)

ratings.tmdb_rating number? TMDB hodnotenie (0-10)

ratings.tmdb_votes integer? Počet hlasov na TMDB

ratings.tmdb_popularity number? TMDB index popularity

ratings.boxofficemojo_domestic number? US tržby (domáce)

ratings.boxofficemojo_worldwide number? Celosvetové tržby

Scoring — `scoring`

Výsledok scoring algoritmu pre Tulavé kino. Môže byť null ak film ešte nebol skórovaný.

scoring.percent number Celkové skóre (0-100%)

scoring.verdict string Verdikt: TRHAK, PRIEMER, alebo PREPADAK

scoring.phase string Fáza: PRED_PREMIEROU, TESNE_PRED, PREMIERA, BEZI, ARCHIV

scoring.confidence string Spoľahlivosť: high, medium, low

scoring.parameter_scores object Detailné skóre pre každý z 14 parametrov

scoring.calculated_at string Dátum výpočtu (ISO 8601)

Metadata

source_url string? Zdrojová URL (stránka distribútora)

created_at string Dátum vytvorenia záznamu

updated_at string Dátum poslednej aktualizácie

Chybové kódy

Všetky chyby vracajú JSON objekt s poľom error.

Kód	Význam	Popis
400	Bad Request	Chybný parameter (napr. query kratší ako 2 znaky)
401	Unauthorized	Chýbajúci alebo neplatný API kľúč
404	Not Found	Film s daným ID neexistuje
429	Too Many Requests	Prekročený rate limit — počkaj podľa Retry-After
500	Server Error	Interná chyba servera

Príklad chybovej odpovede

{
  "error": "Neplatny alebo deaktivovany API kluc"
}

Autentifikácia

curl -H "X-API-Key: wmc_your_key_here" \
  https://api.tulavekino.sk/api/kompas/stats

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/stats',
  {
    headers: {
      'X-API-Key': 'wmc_your_key_here'
    }
  }
);
const data = await res.json();

function getStats() {
  const url = 'https://api.tulavekino.sk/api/kompas/stats';
  const options = {
    headers: {
      'X-API-Key': 'wmc_your_key_here'
    }
  };
  const res = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(res.getContentText());
  Logger.log(data);
}

401 Chýbajúci kľúč

{
  "error": "Chybajuci API kluc. Posli X-API-Key header.",
  "docs": "/api/kompas — vyzaduje API kluc"
}

Rate Limit Response

        HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
Retry-After: 23

{
  "error": "Prekroceny limit requestov",
  "retry_after_seconds": 23,
  "limit": 100,
  "window": "1 minuta"
}
      

GET /api/kompas/films

curl -H "X-API-Key: wmc_your_key_here" \
  "https://api.tulavekino.sk/api/kompas/films?limit=10&from=2026-01-01"

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/films?limit=10&from=2026-01-01',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const { total, films } = await res.json();
console.log(`${total} filmov celkovo`);

function importFilmy() {
  const API_KEY = 'wmc_your_key_here';
  const BASE = 'https://api.tulavekino.sk/api/kompas';
  const options = { headers: { 'X-API-Key': API_KEY } };

  const res = UrlFetchApp.fetch(
    BASE + '/films?limit=500', options
  );
  const { films } = JSON.parse(res.getContentText());
  const sheet = SpreadsheetApp.getActiveSheet();
  sheet.clear();

  // Hlavicka
  sheet.appendRow([
    'ID', 'Nazov', 'Original', 'Premiera',
    'Distributor', 'CSFD', 'RT', 'TMDB',
    'Score %', 'Verdict'
  ]);

  films.forEach(f => {
    sheet.appendRow([
      f.id, f.nazov_sk, f.nazov_original,
      f.datum_sk_premiera, f.distributor,
      f.ratings?.csfd,
      f.ratings?.rotten_tomatoes_critics,
      f.ratings?.tmdb_rating,
      f.scoring?.percent,
      f.scoring?.verdict
    ]);
  });
}

200 Response

{
  "total": 342,
  "limit": 10,
  "offset": 0,
  "films": [
    {
      "id": 42,
      "nazov_sk": "Minecraft Film",
      "nazov_original": "A Minecraft Movie",
      "datum_sk_premiera": "2025-04-03",
      "distributor": "Continental Film",
      "origin_country": "US",
      "zanre": ["Dobrodružný", "Komédia"],
      "rezia": "Jared Hess",
      "ratings": {
        "csfd": 45,
        "rotten_tomatoes_critics": 33,
        "tmdb_rating": 6.8
      },
      "scoring": {
        "percent": 72.5,
        "verdict": "PRIEMER",
        "phase": "BEZI",
        "confidence": "high"
      }
    }
  ]
}

GET /api/kompas/films/:id

curl -H "X-API-Key: wmc_your_key_here" \
  https://api.tulavekino.sk/api/kompas/films/42

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/films/42',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const film = await res.json();
console.log(film.nazov_sk, film.scoring?.verdict);

404 Film nenájdený

{
  "error": "Film nenajdeny"
}

GET /api/kompas/films/search

curl -H "X-API-Key: wmc_your_key_here" \
  "https://api.tulavekino.sk/api/kompas/films/search?q=minecraft"

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/films/search?q=minecraft',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const films = await res.json();
films.forEach(f =>
  console.log(f.nazov_sk, f.scoring?.verdict)
);

400 Krátky query

{
  "error": "Query musi mat aspon 2 znaky"
}

GET /api/kompas/distributors

curl -H "X-API-Key: wmc_your_key_here" \
  https://api.tulavekino.sk/api/kompas/distributors

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/distributors',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const distributors = await res.json();

200 Response

[
  {
    "id": 1,
    "name": "Continental Film",
    "abbr": "CON",
    "country": "SK",
    "category": "velki",
    "website": "https://www.continental-film.sk"
  },
  ...
]

GET /api/kompas/stats

curl -H "X-API-Key: wmc_your_key_here" \
  https://api.tulavekino.sk/api/kompas/stats

const res = await fetch(
  'https://api.tulavekino.sk/api/kompas/stats',
  { headers: { 'X-API-Key': 'wmc_your_key_here' } }
);
const stats = await res.json();

200 Response

{
  "total_films": 342,
  "with_poster": 298,
  "with_trailer": 245,
  "with_score": 310,
  "distributors": [
    { "distributor": "Continental Film", "cnt": 52 },
    { "distributor": "CinemArt", "cnt": 48 }
  ],
  "last_updated": "2026-04-02T14:30:00.000Z"
}

Kompletný film objekt

        {
  "id": 42,
  "nazov_sk": "Minecraft Film",
  "nazov_original": "A Minecraft Movie",

  "poster_url": "https://image.tmdb.org/...",
  "backdrop_url": "https://image.tmdb.org/...",
  "trailer_url": "https://youtube.com/watch?v=...",
  "images": [],

  "datum_sk_premiera": "2025-04-03",
  "world_premiere": "2025-03-31",
  "prava_od": null,
  "prava_do": null,

  "jazyk": "slovenský dabing",
  "vekova_kategoria": "bez obmedzenia",
  "stopaz_min": 101,
  "origin_country": "US",
  "herci": ["Jason Momoa", "Jack Black"],
  "zanre": ["Dobrodružný", "Komédia"],
  "rezia": "Jared Hess",
  "distributor": "Continental Film",

  "overview": "Štvorica neočakávaných...",
  "tagline": "Postav si svet",
  "keywords": ["minecraft", "video game"],

  "ratings": {
    "csfd": 45,
    "csfd_votes": 12500,
    "rotten_tomatoes_critics": 33,
    "rotten_tomatoes_audience": 78,
    "boxofficemojo_domestic": 250000000,
    "boxofficemojo_worldwide": 580000000,
    "tmdb_rating": 6.8,
    "tmdb_votes": 8500,
    "tmdb_popularity": 245.3
  },

  "scoring": {
    "percent": 72.5,
    "verdict": "PRIEMER",
    "phase": "BEZI",
    "confidence": "high",
    "parameter_scores": {
      "tmdb_rating": { "raw": 3, "weighted": 6 },
      "tmdb_popularity": { "raw": 5, "weighted": 5 }
    },
    "calculated_at": "2026-04-01T10:00:00.000Z"
  },

  "source_url": "https://continental-film.sk/...",
  "created_at": "2025-12-15T...",
  "updated_at": "2026-04-01T..."
}
      

Príklady chýb

          401 Neplatný kľúč
        
          {
  "error": "Neplatny alebo deaktivovany API kluc"
}
        
          429 Rate limit
        
          {
  "error": "Prekroceny limit requestov",
  "retry_after_seconds": 23,
  "limit": 100,
  "window": "1 minuta"
}
        
          404 Nenájdené
        
          {
  "error": "Film nenajdeny"
}

Wander Movie Critic API

Formát odpovede

Stránkovanie

Autentifikácia

Ako získať kľúč

Formát kľúča

Bezpečnosť

Rate Limity

Response headers

Odporúčanie

Query parametre

URL parametre

Query parametre

Dátový model — Film

Základné informácie

Médiá

Tvorcovia

Texty

Distribučné práva

Hodnotenia — ratings

Scoring — scoring

Metadata

Chybové kódy

Príklad chybovej odpovede

Hodnotenia — `ratings`

Scoring — `scoring`