API pro vývojáře

Jak začít

1. Požádej o klíč – po přihlášení vyplň krátký formulář (název projektu a k čemu data použiješ).
2. Počkej na schválení – žádost projde moderátor, o výsledku dostaneš upozornění.
3. Posílej klíč v hlavičce X-Api-Key u každého dotazu.

curl -H "X-Api-Key: dabdb_…" "https://www.dabdb.cz/api/v1/hledat?q=simpsonovi"

const r = await fetch('https://www.dabdb.cz/api/v1/dilo/123', {
  headers: { 'X-Api-Key': process.env.DABDB_KLIC },
});
const { data } = await r.json();

Klíč patří na server – nedávej ho do kódu webové stránky, kde by ho mohl kdokoli zkopírovat.

Endpointy

Základní adresa https://www.dabdb.cz/api/v1. Úvod se seznamem endpointů na /api/v1 funguje i bez klíče.

• GET /hledat

  Hledání v dílech, osobách, postavách a firmách bez ohledu na diakritiku.

  Parametry: q (min. 2 znaky), typ = dilo | osoba | postava | firma, limit (1–50)

• GET /dila

  Seznam děl s filtrováním (60 na stránku).

  Parametry: q, druh, dekada, dabing = s | bez, pismeno, razeni = nazev | rok | rok- | dabingu, strana

• GET /dilo/{id}

  Dílo se všemi verzemi dabingu, obsazením, tvůrci, studii a uvedeními.

• GET /daberi

  Seznam dabérů (60 na stránku).

  Parametry: q, stav = zijici | zemreli, dekada, min, pismeno, razeni = jmeno | role | krestni | nejstarsi | nejmladsi, strana

• GET /osoba/{id}

  Osoba s filmografií jako dabér, herec a tvůrce dabingu.

• GET /postavy

  Seznam animovaných postav (60 na stránku).

  Parametry: q, druh, dekada, hlasu, razeni = jmeno | hlasu | nejnovejsi | nejstarsi, strana

• GET /postava/{id}

  Animovaná postava a všechny její české hlasy.

• GET /firmy

  Studia, televize, distributoři (celý seznam najednou).

  Parametry: q, typ, stav = aktivni | zanikle, dabing = s | bez, razeni = nazev | zalozeno | dabingu

• GET /firma/{id}

  Firma s dabingy a uvedeními.

• GET /premiery

  Premiéry děl a dabingů na jednotlivých stanicích (60 na stránku).

  Parametry: q, kdy = ohlasene | probehle, stanice, druh, dekada, rok, dabing = znamy | neznamy, razeni = nejblizsi | nejnovejsi | nejstarsi | nazev | stanice, strana

• GET /statistiky

  Souhrnná čísla databáze a počet dabingů podle roku vzniku.

Odpovědi, limity a chyby

• Seznamy vracejí { data: [...], meta: { celkem, strana, na_stranku, stran } }, detail { data: {...} }. Každý záznam má i url na stránku na webu.
• Limity: výchozí 5 000 dotazů za den (vynuluje se o půlnoci našeho času) a 120 za minutu. Kolik zbývá, říká hlavička X-RateLimit-Remaining. Potřebuješ víc? Napiš nám.
• Chyby mají tvar { chyba: { kod, zprava } }: 400 špatný parametr, 401 chybějící nebo neplatný klíč, 403 klíč čeká nebo je zablokovaný, 404 nenalezeno, 429 překročený limit.
• CORS je povolený, ale kvůli ochraně klíče doporučujeme volat API ze serveru.
• Podmínky: uveď u dat zdroj „DabDB“ s odkazem na stránku záznamu. Data neprodávej a nestahuj celou databázi hromadně – kvůli tomu jsou limity. Fotografie a plakáty z TMDB podléhají jejich podmínkám.