nastroj:ckan-api

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.

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"
   ]
}

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
frequency Periodicita aktualizace Řetězec dle EU slovníku pro frekvence Ano ANNUAL
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 Nehttp://eurovoc.europa.eu/171
maintainer_email Email Kurátora dat E-mail 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.

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:

  • nastroj/ckan-api.1542804498.txt.gz
  • Poslední úprava: 2020/06/03 09:36
  • (upraveno mimo DokuWiki)