Návod

Úvod

Open Data portál mesta Žilina sprístupňuje údaje prostredníctvom samostatných datasetov. Každý dataset obsahuje konkrétne dáta z vybranej oblasti spolu s technickými informáciami potrebnými na ich používanie.

Portál je určený používateľom, ktorí chcú dáta zobrazovať, analyzovať alebo ich využívať vo vlastných aplikáciách a systémoch.

Čo dataset obsahuje

Pri každom datasete sú uvedené základné informácie, ktoré pomáhajú pochopiť, aké údaje poskytuje a ako sa k nim dá pristupovať. Spravidla ide najmä o:

• názov datasetu,

• stručný opis obsahu,

• API adresu datasetu,

• podporovanú metódu,

• vstupné parametre,

• ukážku dopytu,

• ukážku odpovede,

• opis položiek v odpovedi,

• prípadne dostupné výstupné formáty a ďalšie metadáta.

API adresa a metóda

Pri každom datasete je uvedená API adresa, teda internetová adresa, na ktorú sa odosiela požiadavka na získanie dát.

Zároveň je pri datasete uvedená aj metóda, najčastejšie GET alebo POST. Pri metóde GET sa parametre zvyčajne zapisujú priamo do adresy. Pri metóde POST sa posielajú samostatne v tele požiadavky.

Na správne odoslanie dopytu teda nestačí poznať len adresu datasetu. Vždy je potrebné zohľadniť aj použitú metódu.

Vstupné parametre

Niektoré datasety vyžadujú pri dopyte aj vstupné parametre. Tie určujú, aké údaje sa majú v odpovedi vrátiť.

Pri každom parametri býva uvedený jeho názov, dátový typ, informácia o tom, či je povinný alebo voliteľný, a stručný opis významu. Ak je parameter povinný, musí byť zadaný presne podľa popisu. V opačnom prípade dataset nemusí vrátiť požadované údaje alebo môže odpovedať chybou.

Napríklad pri datasete sčítačov cyklistov sa používa parameter classType s hodnotou bike.

Ako odoslať dopyt na dataset

Na získanie údajov je potrebné odoslať dopyt na API adresu datasetu spôsobom, ktorý je pri ňom uvedený.

Najskôr je potrebné skontrolovať adresu datasetu, použitú metódu a prípadné vstupné parametre. Pri metóde GET sa parametre zapisujú do adresy, pri metóde POST sa posielajú v tele požiadavky, najčastejšie vo formáte JSON.

Dopyt možno odoslať rôznymi nástrojmi, napríklad cez Postman, Curl, Python alebo JavaScript.

Výstupné formáty dát

Open Data portál mesta Žilina môže pri jednotlivých datasetoch poskytovať údaje vo viacerých formátoch. Výber formátu závisí od toho, ako chce používateľ s dátami ďalej pracovať.

JSON

Formát JSON je vhodný najmä na technické spracovanie dát v aplikáciách, systémoch alebo skriptoch. Umožňuje prehľadne zobraziť štruktúru odpovede vrátane vnorených údajov.

CSV

Formát CSV je vhodný najmä na otvorenie v tabuľkových programoch, napríklad v Exceli alebo LibreOffice Calc. Pri zložitejších datasetoch však môžu byť niektoré vnorené údaje zapísané ako text v jednom poli.

XML

Formát XML je určený najmä na výmenu dát medzi systémami. Využíva sa predovšetkým tam, kde cieľový systém očakáva práve tento formát.

GeoJSON

Formát GeoJSON sa používa pri datasetoch s geografickými údajmi a je vhodný na mapové zobrazenie objektov.

Príklady odoslania dopytu v rôznych nástrojoch

Nižšie sú uvedené ukážky použitia datasetu sčítačov cyklistov. V príkladoch sa používa metóda POST a parameter classType s hodnotou bike.

Curl

curl -X POST "https://opendata.zilina.sk/api/datasets/v1/city-dashboard/bicycles/list" \

-H "Content-Type: application/json" \

-d '{

"classType": "bike"

Ak chcete získať výstup vo formáte CSV alebo XML, upravte adresu datasetu pridaním parametra:

• ?outputType=csv

• ?outputType=xml

Príklad:

• https://opendata.zilina.sk/api/datasets/v1/city-da...

Python

import requests

url = "https://opendata.zilina.sk/api/datasets/v1/city-dashboard/bicycles/list"

payload = {

"classType": "bike"

}

response = requests.post(url, json=payload)

print(response.json())

Ak chcete získať výstup vo formáte CSV alebo XML, upravte adresu datasetu pridaním ?outputType=csv alebo ?outputType=xml. Zároveň je vhodné namiesto response.json() použiť response.text, pretože odpoveď bude textová.

JavaScript

fetch("https://opendata.zilina.sk/api/datasets/v1/city-dashboard/bicycles/list", {

method: "POST",

headers: {

"Content-Type": "application/json"

body: JSON.stringify({

classType: "bike"

})

.then(response => response.json())

.then(data => console.log(data));

Ak chcete získať výstup vo formáte CSV alebo XML, upravte adresu datasetu pridaním ?outputType=csv alebo ?outputType=xml. Zároveň je potrebné namiesto response.json() použiť response.text().

Postman

Pri použití nástroja Postman je potrebné:

• zvoliť metódu POST,

• vložiť adresu datasetu,

• v záložke Body zvoliť formát raw a typ JSON,

• vložiť parameter:

{

"classType": "bike"

}

Ak chcete získať výstup vo formáte CSV alebo XML, upravte adresu datasetu pridaním ?outputType=csv alebo ?outputType=xml.

Typické chybové stavy

Pri práci s API sa môžu vyskytnúť aj chybové odpovede. Najčastejšie ide o tieto stavy:

400 – Nesprávna požiadavka

Požiadavka nebola odoslaná v správnom tvare alebo chýba povinný parameter.

404 – Zdroj nebol nájdený

Zadaná adresa datasetu neexistuje alebo je nesprávna.

500 – Interná chyba servera

Pri spracovaní požiadavky nastal problém na strane servera.

Ak sa chyba opakuje, odporúča sa skontrolovať adresu datasetu, použitú metódu a zadané parametre.

Metadáta datasetu

Metadáta sú dostupné priamo v detaile konkrétneho datasetu. Obsahujú základné informácie o datasete, najmä jeho názov, popis, API adresu, podporovanú metódu, vstupné parametre, výstupné formáty a opis položiek v odpovedi.

Metadáta pomáhajú používateľovi pochopiť, čo dataset obsahuje, ako sa používa a aký význam majú jednotlivé údaje.

Záver

Open Data portál mesta Žilina sprístupňuje dáta štandardizovaným spôsobom a pri každom datasete uvádza základné technické informácie potrebné na jeho používanie.

Odporúča sa preto vždy najskôr skontrolovať adresu datasetu, metódu, parametre a dostupné výstupné formáty. Následne možno využiť pripravené príklady dopytov a prispôsobiť ich konkrétnej potrebe.