Návod na použitie

Štatistický úrad SR ponúka aplikačné programové rozhranie (API) poskytujúce prístup k údajom z vybraných tabuliek dostupných v databáze DATAcube. Ide o nástroj určený prevažne pre vývojárov a dátových analytikov, ktorí potrebujú údaje v strojovo spracovateľnej forme. Tie sú dostupné vo formátoch JSON-stat, CSV, XML, XLSX a ODS. V stĺpci Kompletné údaje tabuľky na úveodnej stránke sú uvedené REST API odkazy umožňujúce hromadné stiahnutie údajov (tzv. bulk download). Pre tabuľky s veľkým rozsahom údajov sú k dispozícií len odkazy na vygenerované súbory vo formáte CSV a JSON.

Prístup k údajom je bezplatný a nevyžaduje si registráciu. Na všetky údaje sa vzťahujú podmienky licencie Creative Commons Attribution License (cc-by) 4.0. Bližšie informácie sú uvedené na stránke Podmienky pre využívanie a ďalšie zverejňovanie štatistických informácii ŠÚ SR.

Údaje sú aktualizované každý pracovný deň o 10:00 a 22:00.

Čo je JSON-stat?

JSON-stat je jednoduchý JSON (JavaScript Object Notation) formát, ktorý bol špeciálne vytvorený pre štatistické tabuľky, ktoré môžu mať mnoho rozmerov (dimenzií). Táto iniciatíva vychádza z faktu, že tabuľka je najčastejšia forma šírenia údajov. JSON-stat je hierarchická štruktúra, ktorá obsahuje metaúdaje tabuľky, dimenzie a ich popis a údaje. Bližšie informácie o tomto formáte nájdete na stránke https://json-stat.org/ (dostupné v anglickom jazyku).

Ako získam údaje?

Pre jednoduchší prístup k údajom sme vytvorili webové rozhranie, v ktorom nájdete zoznam všetkých dostupných tabuliek. V zozname je možné vyhľadávať tabuľky podľa ich názvu alebo jedinečného kódu, prípadne filtrovať podľa štatistickej oblasti a okruhu. V stĺpci Kompletné údaje sa nachádzajú URL odkazy na súbory obsahujúce všetky údaje tabuľky. Tieto odkazy sú dostupné len pre menšie tabuľky. Pre väčšie tabuľky je potrebné z dostupných údajov vytvoriť čiastočný výber.

Čiastočný výber je možné vytvoriť v detaile tabuľky, ten sa zobrazí po kliknutí na názov tabuľky. V detaile tabuľky si viete prostredníctvom formulára zostaviť vlastný výber z položiek dimenzii, nastaviť požadovaný jazyk a výstupný formát údajov. Za názvom každej dimenzie sa nachádza kódové označenie dimenzie, ktoré je odkazom na zoznam jej položiek vo formáte JSON-stat. Prístup k údajom podľa vášho vlastného výberu získate po stlačení tlačidla Generovať a následnom zobrazení vygenerovaného URL odkazu.

API umožňuje získať 3 typy údajov.

  1. Prehľad všetkých dátových tabuliek dostupných v API prostredníctvom URL odkazu https://data.statistics.sk/api/v2/collection?lang=sk vo formáte JSON-stat.
  2. Zoznam elementov dimenzie tabuľky vo formáte JSON-stat prostredníctvom URL odkazu, ktorý vytvoríme podľa vzoru https://data.statistics.sk/api/v2/dimension/cube_code/dim_code?lang=lang_code, kde cube_code je osemmiestny kód tabuľky, dim_code je kód dimenzie tabuľky a lang_code je kód jazyka (sk alebo en) – nepovinné (predvolené sk). Napríklad elementy dimenzie np3106rr_dim1 získame prostrednícrvom URL odkazu https://data.statistics.sk/api/v2/dimension/np3106rr/np3106rr_dim1.
  3. Požiadavka na údaje má formu URL odkazu, ktorý vytvoríme podľa vzoru https://data.statistics.sk/api/v2/dataset/cube_code/PARAM1/PARAM2/PARAM3...?lang=lang_code&type=file_type, kde cube_code je osemmiestny kód tabuľky, PARAM1, PARAM2 .... sú kódy elementov dimenzií vybranej tabuľky, lang_code je kód jazyka (sk alebo en) – nepovinné (predvolené sk), file_type je typ súboru (json, csv, xml, xlsx, ods) – nepovinné (predvolené json). Na zostavenie linky môžete použiť formulár dostupný po kliknutí na detail tabuľky.

Príklad: Z tabuľky Hrubá mzda podľa zamestnania s kódom np3106rr chceme získať údaje o priemernej hrubej nominálnej mesačnej mzde kvalifikovaných pracovníkov a remeselníkov v Trnavskom kraji za roky 2016, 2017 a 2018. Použitím formulára získame URL odkaz v takomto tvare: https://data.statistics.sk/api/v2/dataset/np3106rr/SK021/2016,2017,2018/E_PRIEM_HR_MZDA/7?lang=sk a údaje vo formáte JSON-stat v tvare: 

	        {
	        	"version":	"2.0",
	        	"class":	"dataset",
	        	"label":	"Hrubá mzda podľa zamestnania",
	        	"update":	"2019-07-09",
	        	"note":		"Výberové zistovanie o štruktúre miezd.\n",
	        	"href":		"http://datacube.statistics.sk/#!/view/sk/VBD_SK_WIN/np3106rr/v_np3106rr_00_00_00_sk",
	        	"id":		["nuts13","np3106rr_rok","np3106rr_ukaz","np3106rr_dim1","np3106rr_data"],
	        	"size":		[1,3,1,1,1],
	        	"role":{
	        		"time":		["np3106rr_rok"],
	        		"geo":		["nuts13"],
	        		"metric":	["np3106rr_data"]
	        	},
	        	"dimension":{
	        		"nuts13":{
	        			"label":	"nuts13",
	        			"note":		"0 SR + Oblasti + Kraje",
	        			"category":{
	        				"index":{
	        					"SK021":	0
	        				},
	        				"label":{
	        					"SK021":	"Trnavský kraj"
	        				}
	        			}
	        		},
	        		"np3106rr_rok":{
	        			"label":	"np3106rr_rok",
	        			"note":		"Rok",
	        			"category":{
	        				"index":{
	        					"2016":		0,
	        					"2017":		1,
	        					"2018":		2
	        				}
	        			}
	        		},
	        		"np3106rr_ukaz":{
	        			"label":"np3106rr_ukaz",
	        			"note":"Ukazovateľ",
	        			"category":{
	        				"index":{
	        					"E_PRIEM_HR_MZDA":0
	        				},
	        				"label":{
	        					"E_PRIEM_HR_MZDA":"Priemerná hrubá nominálna mesačná mzda (Eur)"
	        				}
	        			}
	        		},
	        		"np3106rr_dim1":{
	        			"label":"np3106rr_dim1",
	        			"note":"Klasifikácia zamestnaní (SKISCO-08) - triedy",
	        			"category":{
	        				"index":{
	        					"7":0
	        				},
	        				"label":{
	        					"7":"Kvalifikovaní pracovníci a remeselníci"
	        				}
	        			}
	        		},
	        		"np3106rr_data":{
	        			"label":"np3106rr_data",
	        			"note":"Data",
	        			"category":{
	        				"index":{
	        					"NUM_VALUE":0
	        				},
	        				"label":{
	        					"NUM_VALUE":"hodnota"
	        				}
	        			}
	        		}
	        	},
	        	"value":[992,1077,1154]
	        }

Pri zápise väčšieho počtu elementov môžu byť použité nasledujúce kľúčové slová a špeciálne symboly:

Obmedzenia

Pri používaní API sa môžete stretnúť s nasledujúcimi obmedzeniami:

  1. Dĺžka URL odkazu môže mať najviac 2000 znakov.
  2. Množstvo údajov prenesených jedným URL odkazom je maximálne 10000 položiek.

Neexistujúce údaje

Pre niektoré kombinácie elementov dimenzií sa môže stať, že údaje neexistujú. V takomto prípade na mieste hodnoty bude uvedená hodnota null.