Toto je starší verze dokumentu!
Technické standardy pro aplikační rozhraní lokálních katalogů
Aby mohl být lokální katalog registrován v NKOD, musí nabízet aplikační rozhraní (API) splňující následující specifikaci. API je webová služba obsahující funkce package_list a package_show ze specifikace CKAN API verze 3. Výstup funkce package_show je rozšířen o dodatečná metadata. Výstupy obou funkcí jsou ve formátu JSON (ECMA-404).
Obě funkce musí být přístupné na adrese lokálního katalogu pod pevně stanovenými URL.
Příklad: lokální katalog běží na adrese https://data.organizace.cz. Funkce package_list je pak přístupná na adrese https://data.organizace.cz/api/3/action/package_list a funkce package_show je pak přístupná na adrese https://data.organizace.cz/api/3/action/package_show?id=datova-sada-1 kde „datova-sada-1“ je ID konkrétní datové sady v lokálním katalogu sestávající z malých písmen bez diakritiky, čísel, podtržítek a pomlček.
package_list
Odpověď na volání funkce package_list obsahuje v poli result seznam ID všech datových sad obsažených v katalogu. Tato ID se pak použijí pro volání funkce package_show. Odpověď má tvar:
{
"success": true,
"result": [
"datova-sada-1",
"datova-sada-2",
"datova-sada-3"
]
}
package_show
Odpověď na volání funkce package_show s parametrem id obsahujícím ID datové sady obsahuje mimo jiné kompletní metadata datové sady a všech jejích distribucí. Pole result obsahuje mimo jiné následující parametry:
| Název pole | Název položky | Datový typ | Povinnost | Příklad hodnoty |
|---|---|---|---|---|
| title | Název datové sady | Řetězec | Ano | Kontroly |
| notes | Popis datové sady | Řetězec | Ano | Seznam kontrol od 1.1.2012 |
| frequency | Periodicita aktualizace | Řetězec dle ISO 8601 | Ano | R/P3M |
| ruian_type | Související geografické území - typ prvku RÚIAN | Typ prvku RÚIAN | Ano | ST |
| ruian_code | Související geografické území - kód prvku RÚIAN | Řetězec | Ano | 1 |
| theme | Klasifikace dle EuroVoc | Seznam URL oddělený mezerou | Ne | http://eurovoc.europa.eu/171 |
| maintainer_email | Email Kurátora dat | Ne | verejnadata@INSTITUCE.cz | |
| maintainer | Jméno Kurátora dat | Řetězec | Ne | Jan Novák |
| schema | Odkaz na dokumentaci datové sady | URL | Ne | https://www.INSTITUCE.cz/open-data/dokumentace-ds1.html |
| tags | Klíčová slova | pole objektů | Ano | viz níže |
| temporal_start | Dotčené časové období od | datum ve formátu xsd:date | Ne | 2012-01-01 |
| temporal_end | Dotčené časové období do | datum ve formátu xsd:date | Ne | 2014-12-31 |
| publisher_uri | URL poskytovatele dat | URL | Ano | https://www.INSTITUCE.cz |
| publisher_name | Název poskytovatele dat | Řetězec | Ano | INSTITUCE |
| resources | Datové zdroje | pole objektů | Ano | viz níže |
Navíc pole result obsahuje:
- položku name obsahující ID datové sady použité jako parametr funkce package_show a zobrazené v seznamu vráceném funkcí package_list.
Příklad:
"name": "coi-kontroly"
- Pole klíčových slov, kde každé je reprezenováno objektem o dvou položkách se stejným obsahem name a display_name.
Příklad:
"tags": [{
"display_name": "kontroly",
"name": "kontroly"
}],
- Pole obsahující metadata jednotlivých datových zdrojů resources, viz popis distribuce.
V poli resources má každá distribuce (datový zdroj) mimo jiné následující parametry:
| Název pole | Název položky | Datový typ | Povinnost | Příklad hodnoty |
|---|---|---|---|---|
| url | Odkaz na stažení datového zdroje | URL | Ano | https://www.INSTITUCE.cz/open-data/kontroly.trig |
| format | Formát datového zdroje | MIME typ | Ano | application/trig |
| license_link | Odkaz na podmínky užití | URL | Ano | https://data.gov.cz/podmínky-užití/volný-přístup/ |
| name | Název datového zdroje | Řetězec | Ne | Kontroly |
| describedBy | Odkaz na strojově čitelné schéma datového zdroje | URL | Ne | https://www.INSTITUCE.cz/open-data/ontologie.trig |
| describedByType | Formát schématu datového zdroje | MIME typ | Ne | application/trig |
| temporal_start | Dotčené časové období od | datum ve formátu xsd:date | Ne | 2015-01-01 |
| temporal_end | Dotčené časové období do | datum ve formátu xsd:date | Ne | 2015-12-31 |
Kompletní příklad výstupu funkce package_show
Dle standardu DCAT jsou podmínky užití vlastností datového zdroje, jelikož každý datový zdroj může mít podmínky jiné. Položku license_link lze uvést i v poli datové sady result, pak se interpretuje jako že jsou podmínky užití stejné pro všechny datové zdroje.
Příklady existujících rozhraní
Zde uvádíme příklady existujících rozhraní pro harvestaci NKOD. Upozorňujeme ale, že ne všechny zcela splňují specifikaci uvedenou výše:
- Český statistický úřad: package_list, package_show