Přejít k menu Přejít k obsahu

Základní informace pro použití API DataStatu

Důležité pojmy

  • Datová sada = rozsáhlá množina dat vymezená výčtem konkrétních ukazatelů a dimenzí. Kompletní datový obsah sady je poskytován pouze ke stažení jako soubor ve formátu CSV nebo JSON-STAT.
  • Výběr = vybraná podmnožina dat z konkrétní datové sady, určená k zobrazení ve formě tabulky online či pro poskytnutí přes API
    • Předdefinovaný výběr = oficiální výběr dat vytvořený pro webovou prezentační aplikaci DataStat, nabízí se jako výchozí tabulka dané datové sady. Datová sada může mít více předdefinovaných výběrů.
    • Vlastní výběr = výběr dat vytvořený uživatelem na základě výběru ukazatelů a dimenzí z dané datové sady
  • Ukazatele = základní entita pro identifikaci dat. Ukazatele jsou vytvářené nezávisle, ale hlavním smyslem je jejich použití v datových sadách a výběrech
  • Dimenze (varianty dimenze) = seznam konkrétních položek / kategorií, které identifikují data z určitého hlediska (územní, časové, věcné). Dimenze může obsahovat plochý seznam položek, nebo hierarchii (např. územní strukturu od ČR přes kraje, okresy až po obce). Dimenze jsou vytvářené nezávisle, ale hlavním smyslem je jejich použití v datových sadách a výběrech.

 

Vybrané služby API

Katalog

Poskytuje informace o existujících objektech DataStatu, pomocí kterých je možné sestavit požadavky na získání dat.

  1. Seznam datových sad (včetně verze a názvu)
  2. Seznam všech předdefinovaných výběrů
  3. Seznam všech ukazatelů, které jsou vytvořené v DataStatu
  4. Seznam všech dimenzí, které jsou vytvořené v DataStatu
  5. Informace o konkrétní datové sadě s texty a kódy ukazatelů, dimenzí
  6. Seznam předdefinovaných výběrů, které jsou nabízené k jedné konkrétní datové sadě
  7. Seznam ukazatelů, které jsou použité v jedné konkrétní datové sadě
  8. Seznam dimenzí, které jsou použité v jedné konkrétní datové sadě
  9. Informace o konkrétním předdefinovaném výběru včetně datové sady, ze které čerpá data
  10. Seznam datových sad (všechny jejich verze), které obsahují daný ukazatel
  11. Seznam položek jedné konkrétní dimenze
  12. Seznam datových sad (všechny jejich verze), které obsahují danou dimenzi

Datový obsah

DataStat umožňuje získání dat pomocí API několika způsoby.

  1. Všechna data zvoleného předdefinovaného výběru, např. CRUHVD1T2
  1. Výběr dat ze zvolené datové sady pomocí požadavku typu POST

Poskytuje data ve formátech CSV, JSON-STAT, XLSX, HTML.

Volání se provádí metodou POST: https://data.csu.gov.cz/api/dotaz/v1/data/sady/{sadaKod}/vlastni

Požadované ukazatele a položky dimenzí se zadávají do JSON objektu, do těchto povinných prvků (polí):

  • sloupce
  • radky
  • filtryTabulky

Ukazatele jsou zadávány vždy jako IndicatorType. Dimenze jsou zadávány svými kódy, např. Uz0.

Pro formáty CSV a JSON-STAT není důležité, do kterého z uvedených polí jsou kódy zadány.

Pro formát XLSX a HTML je umístění ukazatelů a dimenzí do sloupců, řádků a filtrů tabulky důležité.

Příklady volání s URL parametry pro sadu KPR01, verze sady 1:

Příklady zadání ukazatelů a dimenzí v JSON objektu do těla HTTPS požadavku

  • Vybrané ukazatele a všechny položky dimenzí (bez omezení):

{

"sloupce":[{"kodDimenze":"IndicatorType","filtr":[{"zobrazitPolozky":["5860","5865","5866"]}]}, {"kodDimenze":"CasM","filtr":[]}, {"kodDimenze":"Uz0","filtr":[]}],

"radky":[], "filtryTabulky":[]

}

  • Vybrané ukazatele a vybrané měsíce, všechny položky území (bez omezení):

{

"sloupce":[

  {"kodDimenze":"IndicatorType","filtr":[{"zobrazitPolozky":["5860","5865","5866"]}]}, {"kodDimenze":"CasM","filtr":[{"zobrazitPolozky":["2025-01","2024-12","2024-11","2024-10","2024-09","2024-08","2024-07","2024-06","2024-05","2024-04","2024-03","2024-02","2024-01"]}]}, {"kodDimenze":"Uz0","filtr":[]}],

"radky":[], "filtryTabulky":[]

}

  • Umístění ukazatelů a dimenzí pro XLSX a HTML export – všechny položky území (bez omezení) ve sloupcích, vybrané měsíce v řádcích, ukazatele jako filtr tabulky, výchozí ukazatel 5860:

{

"sloupce":[{"kodDimenze":"Uz0","filtr":[]}],

"radky":[{"kodDimenze":"CasM","filtr":[{"zobrazitPolozky":["2025-01","2024-12","2024-11","2024-10","2024-09","2024-08","2024-07","2024-06","2024-05","2024-04","2024-03","2024-02","2024-01"]}]}],

"filtryTabulky":[{"kodDimenze":"IndicatorType","filtrTabulkyKod":"5860"}]

}

 

Příklady spuštění celého dotazu pomocí příkazu curl ve Windows

  • curl -X POST "https://data.csu.gov.cz/api/dotaz/v1/data/sady/KPR1/vlastni?verzeSady=1&format=CSV" -H "accept: application/json" -H "Accept-Language: cs" -H "Content-Type: application/json" -d "{\"sloupce\":[{\"kodDimenze\":\"IndicatorType\",\"filtr\":[{\"zobrazitPolozky\":[\"5860\",\"5865\",\"5866\"]}]}],\"radky\":[{\"kodDimenze\":\"CasM\",\"filtr\":[{\"zobrazitPolozky\":[\"2025-01\",\"2024-12\",\"2024-11\",\"2024-10\",\"2024-09\",\"2024-08\",\"2024-07\",\"2024-06\",\"2024-05\",\"2024-04\",\"2024-03\",\"2024-02\",\"2024-01\"]}]}],\"filtryTabulky\":[{\"kodDimenze\":\"Uz0\",\"filtrTabulkyKod\":\"CZ\"}]}" -o KPR1_data.csv
  • curl -X POST "https://data.csu.gov.cz/api/dotaz/v1/data/sady/KPR1/vlastni?verzeSady=1&format=XLSX&kodZvlast=true&formatPoznamek=KOMENTAR" -H "accept: application/json" -H "Accept-Language: cs" -H "Content-Type: application/json" -d "{\"sloupce\":[{\"kodDimenze\":\"IndicatorType\",\"filtr\":[{\"zobrazitPolozky\":[\"5860\",\"5865\",\"5866\"]}]}],\"radky\":[{\"kodDimenze\":\"CasM\",\"filtr\":[{\"zobrazitPolozky\":[\"2025-01\",\"2024-12\",\"2024-11\",\"2024-10\",\"2024-09\",\"2024-08\",\"2024-07\",\"2024-06\",\"2024-05\",\"2024-04\",\"2024-03\",\"2024-02\",\"2024-01\"]}]}],\"filtryTabulky\":[{\"kodDimenze\":\"Uz0\",\"filtrTabulkyKod\":\"CZ\"}]}" -o KPR1_data_kody.xlsx
  • curl -X POST "https://data.csu.gov.cz/api/dotaz/v1/data/sady/KPR1/vlastni?verzeSady=1&format=XLSX&formatPoznamek=KOMENTAR" -H "accept: application/json" -H "Accept-Language: cs" -H "Content-Type: application/json" -d "{\"sloupce\":[{\"kodDimenze\":\"IndicatorType\",\"filtr\":[{\"zobrazitPolozky\":[\"5860\",\"5865\",\"5866\"]}]}],\"radky\":[{\"kodDimenze\":\"CasM\",\"filtr\":[{\"zobrazitPolozky\":[\"2025-01\",\"2024-12\",\"2024-11\",\"2024-10\",\"2024-09\",\"2024-08\",\"2024-07\",\"2024-06\",\"2024-05\",\"2024-04\",\"2024-03\",\"2024-02\",\"2024-01\"]}]}],\"filtryTabulky\":[{\"kodDimenze\":\"Uz0\",\"filtrTabulkyKod\":\"CZ\"}]}" -o KPR1_data_texty.xlsx

 

  1. Využití URL odkazu na vlastní výběr, který je vytvořený ve webové aplikaci DataStat

V aplikaci DataStat [https://data.csu.gov.cz] si přihlášený uživatel může sestavit a uložit svůj vlastní výběr. Pro vlastní výběr lze nastavit požadovaný režim Aktualizace časové řady:

  • Nepřidávat novější období
  • Přidávat novější období se zachováním počátku
  • Vždy vybrat data za posledních X období – s možností nastavení vlastního počtu období

Vlastní výběr je uložen pod unikátním identifikátorem, pod kterým je dostupný komukoliv na příslušné URL adrese,

např. https://data.csu.gov.cz/datastat/data/UZIVATELSKY_VYBER/90afdb36-9165-4f41-a784-e0130e712ca6

Obsah vlastního výběru je možné stáhnout bez přihlášení použitím API odkazu pro požadovaný formát:

Tabulku lze případně vložit do vlastní webové stránky pomocí IFRAME (nutné upravit jeho velikost):

<iframe src="https://data.csu.gov.cz/compact/UZIVATELSKY_VYBER/90afdb36-9165-4f41-a784-e0130e712ca6" title="DataStat"></iframe>

 

  1. Jedna vybraná hodnota pro zvolenou sadu, verzi sady, ukazatel, dimenze a jejich konkrétní položky

Vrací vždy JSON objekt.

 

Příklady:

  1. Počet přenocování (ukazatel = 2655) v roce 2023 (CasR = 2023) v ČR (Uz012 = CZ)

 

  1. Počet hostů (ukazatel = 2654) v roce 2023 (CasR = 2023) v ČR (Uz012 = CZ)

 

  1. Počet hostů (ukazatel = 2654) v roce 2023 (CasR = 2023) v ČR (Uz012 = CZ), jen rezidenti (REZIDENCE = 203)

 

  1. Počet hostů (ukazatel = 2654) v roce 2023 (CasR = 2023) v ČR (Uz012 = CZ), z Belgie (REZIDENCE = 056)

 

Postup pro získání 1 konkrétní hodnoty

Požadovaná hodnota: „Počet hostů v roce 2023 v ČR, z Belgie“

  1. Výběr konkrétní datové sady ze seznamu: https://data.csu.gov.cz/api/katalog/v1/sady
  • Sada: "Návštěvnost hromadných ubytovacích zařízení podle rezidence" = kód CRUHVD1
  • Verze: 2
  1. Výběr ukazatelů a dimenzí z dané sady: https://data.csu.gov.cz/api/katalog/v1/sady/CRUHVD1
  • Ukazatel: „Počet hostů“ = kód 2654
  • Ukazatel: „Počet přenocování“ = kód 2655
  • Dimenze: "Roky" = kód CasR
  • Dimenze: "Rezidence" = kód REZIDENCE
  • Dimenze: " ČR, Reg. soudržnosti, Kraje" = kód Uz012
  1. Zjištění kódů položek z dimenzí, pro které chci konkrétní hodnotu:
  1. Sestavení URL s parametry pro 1 konkrétní hodnotu:


Podrobná dokumentace ve Swagger UI


Formát JSON-STAT [https://json-stat.org/]

  • Plná specifikace formátu JSON-STAT: https://json-stat.org/full/
  • Nástroje pro načtení, transformaci a zobrazení dat ve formátu JSON-STAT: https://json-stat.org/tools/