Svůj API token najdeš https://www.hlidacstatu.cz/api.
curl -X GET https://api.hlidacstatu.cz/Api/v2/Smlouvy/204737 -H 'Authorization: Token docela1dlouhy2token3pro4tohle5api'
Autorizace je prováděna pomocí autentifikačního tokenu, který je Vám přidělen. Autorizační token je nutno odesílat v hlavičce každého požadavku na API.
Autorizační token: docela1dlouhy2token3pro4tohleHS5api
Příklad k použití:
Všechna volání API jsou monitorována a ukládána.
Dokumentaci jednotlivých API funkcí najdete na https://api.hlidacstatu.cz/swagger/index.html. Swagger file je na https://api.hlidacstatu.cz/swagger/v2/swagger.json
Na této stránce najdete podrobnější dokumentaci k datasetům - uživatelskýcm databázím Hlídače státu.
Data můžete zdarma stahovat, zpracovávat a dále publikovat pouze v souladu s licencí CC BY 3.0. Licence je jednoduchá a její pravidla také. Některá API a některá data nejsou v rámci volné licence dostupné
Nejdůležitější, nikoliv jediná pravidla licence:
Dílo a obsah smíte stáhnout, sdílet a libovolně upravit.
Musíte vždy a bezpodmínečně uvést původ dat a autorství zdrojových dat (na internetu plný, funkční internetový odkaz na Hlídač státu)
Nesmíte přidat žádná další technická či právní omezení nad rámec této licence.
Pokud vám tato licence nevyhovuje, napište na api@hlidacstatu.cz
Data můžete stahovat, zpracovávat a dále publikovat zcela volně, uvádět zdroj dat nemusíte. Všechna API a všechna data jsou dostupná v plném rozsahu.
Pro více informací o komerční licenci pište na api@hlidacstatu.cz
Registraci nové datové sady je potřeba udělat před prvním vkládáním dat do systému. Vrácený identifikátor datové sady se používá v dalších API
Povinnou součástí registrace je JSON schema jednoho zaznamu (objektu). Očekáváme datové schéma ve formátu JSON Schema Draft 7. Každý vkládaný object je proti tomuto schématu validován a nevalidní záznam není uložen.
POZOR - po registraci není možné provést změnu JSON Schematu
jsonSchema. Pokud potřebujete změnit JSON schema datové sady, musíte datovou sadu smazat, a zaregistrovat znovu. Smazáním datové sady se smažou i všechna data z datové sady.
POZOR - po registraci není možné provést změnu
datasetId. Pokud ho potřebujete , musíte datovou sadu smazat, a zaregistrovat znovu. Smazáním datové sady se smažou i všechna data z datové sady.
Ukázka datové struktury zde: https://github.com/HlidacStatu/API/blob/master/register.sample.json
{
"id": "rozhodnuti-uohs",
"name": "Rozhodnutí UOHS",
"datasetId": "rozhodnuti-uohs",
"origUrl": "http://www.uohs.cz/cs/verejne-zakazky/sbirky-rozhodnuti/",
"sourcecodeUrl": null,
"description": "Sbírka rozhodnutí Úřadu pro ochranu hospodářské soutěže od roku 1999 v oblastech hospodářská soutěž, veřejné zakázky, veřejná podpora a významná tržní síla.",
"jsonSchema": ".... JSON Schema, viz ukázka na odkazu výše ",
"createdBy": "michal@michalblaha.cz",
"created": "2018-09-22T10:44:38.7784317+02:00",
"betaversion": false,
"allowWriteAccess": false,
"hidden": false,
"searchResultTemplate": {
"body": "<!-- scriban {{ date.now }} --> .... scriban/liquid template",
"properties": null
},
"detailTemplate": {
"body": "<!-- scriban {{ date.now }} --> .... scriban/liquid template",
"properties": null
},
"orderList": [["Nabytí právní moci", "PravniMoc"], ["Účastníci", "Ucastnici.Jmeno.keyword"]]
}
datasetId - unikátní jméno datové sady. Má pouze několik omezení
#, \, /, *, ?, ", <, >, |, [, ]datasetId při registraci se může lišit od požadované hodnotynamename - je povinné
betaversion - pokud je true, pak se nezobrazuje v seznamu datových zdrojů na https://www.hlidacstatu.cz/data.
pokud zavoláš s parametrem https://www.hlidacstatu.cz/data?beta=1, pak se seznam zobrazí.
allowWriteAccess : pokud je true, pak data v datasetu může kdokoliv přepsat nebo smazat. Stejně tak údaje v registraci.
Pokud je false, pak kdokoliv může data přidat, ale nemůže je přepsat či smazat. Nemůže také měnit parametry registrace datasetu.
jsonSchema - je povinné. Struktura vkládaných dat (a popsaná tímto JSON schéma) musí splňovat pár pravidel:
Id v rootu objektu - unikátní identifikátor objektu. Musí být součástí JSON Schematu i vkládaného objektu, ve formátu string.DbCreated: obsahuje datum vložení objektu do db.DbCreatedBy: obsahuje info o uživateli, který objekt do db vložil. Tento údaj není poskytován veřejně.ICO kdekoliv (i ve vložených objektech) - pokud je typu string, pak Hlídač státu předpokládá, že se jedná IČ subjektu a propojí záznam s firmami v Hlídači státu.OsobaId kdekoliv (i ve vložených objektech) - pokud jde o string, pak Hlídač Státu předpokládá, že se jedná o identifikátor osoby z databáze Hlídače státu. Pro nalezení použijte endpoint FindOsobaIdUrl v rootu objektu - pokud dává smysl, měl by odkazovat na zdrojový záznam.HsProcessType kdekoliv, v kombinaci s dalšími atributy (viz dále), zajistí následné zpracování záznamu na serveru a doplnění údajů na straně Hlídače.searchResultTemplate - HTML template či seznam vlastností objektu, které se mají zobrazovat ve výsledku hledání. Podrobnější popis o kousek dál.
detailTemplate - HTML template či seznam vlastností objektu, které se mají zobrazovat na stránce s detailem objektu. Podrobnější popis o kousek dál.
Pokud libovolný objekt (v rootu, v poli či ve vložených objektech) obsahuje vlastnost HsProcessType
s některou z definovaných hodnot, je takový objekt následně a asynchronně zpracován a doplněn o další údaje na straně Hlídače.
"HsProcessType": "person" - definuje, že se jedná o objekt obsahující údaje o osobě, kterou chcete provázat s databází osob Hlídače.
Tento typ předpokládá, že je uveden u objektu obsahující tyto atributy:
Jmeno nebo Name (string)Prijmeni nebo Surname (string)
Jmeno a Prijmeni pouze jeden atribut CeleJmeno nebo FullnameNarozeni nebo Birthdate (date)OsobaId (string)
Hodnota OsobaId nemusí a neměla by být vyplněna. Při vložení záznamu do Datasetu Hlídač automaticky doplní OsobaId a prováže tak záznam s databází osob Hlídače.
Všechny uvedené atributy včetně OsobaId musí být uvedeny v JSONSchema datasetu.
"HsProcessType": "document" - definuje, že se jedná o objekt obsahující odkaz na dokument, který je potřeba stáhnout a umožnit jeho fulltextové prohledávání.
Tento typ předpokládá, že je uveden u objektu obsahující tyto atributy: DocumentUrl(string) a DocumentPlainText (string).
Hodnota DocumentPlainText nemusí a neměla by být vyplněna. Po vložení záznamu do Datasetu Hlídač automaticky dokument stáhne, vydoluje data a doplní DocumentPlainText. Tato operace se provede asynchronně během několika minut až hodin.
Všechny uvedené atributy včetně DocumentPlainText musí být uvedeny v JSONSchema datasetu.
Template je možné definovat dvěma způsoby:
pomocí seznamu vlastností - v takovém případě do properties dáš textové pole, které obsahuje seznam vlastností, které se mají vypsat.
O vhodný způsob zobrazení se postará Hlídač státu. To je snadná a jednoduchá cesta pro rychlý výpis údajů. Je to vhodné pro testování.
Doporučujeme v takovém případě nastavit v registraci datového zdroje betaversion = true.
Hodnota body musí být null.
{
"body": null,
"properties": ["Id","Cj","Rok","Vec"]
}
velmi detailně pomocí HTML. K tomu slouží vlastnost body. Je to volný template
{
"body": "<table><tr><td>Čj</td><td>{{item.Cj}}</td><tr>.....<table>",
"properties": null
}
Pokud jsou nastaveny jak body, tak properties nastaveny, properties se ignorují.
Pokud jsou obě null, zobrazí se chyba při renderování stránky.
Jedná se o template engine kompatibilní s liquid.
Stručny přehled najdete zde https://github.com/lunet-io/scriban, přehlednou dokumentaci na https://github.com/lunet-io/scriban/tree/master/doc
Hlídač státu zajiští, že se do templatu vloží vždy odpovídající datová struktura
Do template pro vyhledávání se vkládá .NET datová struktura obdobná dále uvedené struktuře.
Pro přehlednost je zde uvedena v JSON formě. V Result je pole nalezených zaznamů v jejich struktuře
{
"model" : {
"Total": 10,
"Page": 1,
"Q": "hledaný výraz"
"Result" : [{ "Id" = "id zaznamu" },{"nazev":"Pojmenování"}{"atribut2":"hodnota2"}]
}
Typický searchResultTemplate pro vyhledávání vypadá takto:
<table class="table table-hover">
<thead>
<tr>
<th>ID</th>
<th>Název</th>
<th>Další pole</th>
</tr>
</thead>
<tbody>
{{ for item in model.Result }}
<tr>
<td style="white-space: nowrap;">
<a href="{{fn_DatasetItemUrl item.Id}}">{{item.Id}}</a>
</td>
<td style="white-space: nowrap;">
{{item.Nazev}}
</td>
<td>
{{fn_FormatDate item.atribut2 "dd.MM.yyyy"}}
</td>
<td>
{{fn_ShortenText item.Vec 200}}
</td>
</tr>
{{end }}
</tbody></table>
Do template pro vyhledávání se vkládá .NET datová struktura obdobná dále uvedené struktuře.
V model obsahuje jeden záznam v jejo originál struktuře odpovídající JSON schema.
Pro přehlednost je zde uvedena v JSON formě.
{
"model" : {
{ "Id" = "id zaznamu" },
{"Nazev":"Pojmenování"},
{"atribut2":"hodnota2"}
}
}
Typický detailTemplate pro vyhledávání vypadá takto:
{{this.item = model #nepovinne, pouze sjednocení pojmenování záznamu s templatem pro jeden zaznam. Bez tohoto řádku by jste namísto 'item' psali 'model' }}
<table class="table table-hover">
<tbody>
<tr>
<td>Id</td>
<td>{{item.Id}}</td>
</tr>
<tr>
<td>Pojmenování</td>
<td>{{item.Nazev}}</td>
</tr>
{{ if item.atribut2}}
<tr>
<td>Další pole</td>
<td>{{fn_FormatDate item.atribut2 "dd.MM.yyyy"}}</td>
</tr>
{{end}}
</tbody>
</table>
Pozor! Rozlišují se velká a malá písmena.
V kódu je možné volat speciální funkce pro formátování hodnot.
V Scriban se funkce volají s parametry oddělenými mezerou
string {{fn_ShortenText "text" 50}} - zkrácení textu na max. 50 znaků, funkce vrací string
Dále uvádíme seznam dostupných funkcí nad rámec build-in funkcí Scribanu.
string fn_ShortenText(string value, int length) - zkrácení textu na maximální délku length znaků.
ke zkrácení dojde na nejbližším konci slova, odstavce či věty.
string fn_FixPlainText(string plaintext) - funkce, která upraví čistý text pro lepší čitelnost. Vhodné zejména pro delší texty či obsahy dokumentů.
V praxi se odstraní nadbytečné a příliš se opakující řádky a další speciální znaky. Ná
string fn_NormalizeText(dynamic text) - vymaže všechny HTML znáčky a přebytečné neviditelné znaky.
boolean fn_IsNullOrEmpty(object obj) - otestuje, zda je object null anebo retezec prazdny. Vhodne pro otestovani existence pole apod.
string fn_RenderPersonWithLink(string osobaId, string jmeno, string prijmeni, string rokNarozeni = "") - vyrendruje jméno, příjmení a rok narození osoby s odkazem na její profil
string fn_RenderPersonStatistic(string osobaId, bool twoLines = false, string prefix = "", string postfix = "") - pro existující osobu vrací základní statistiku vztahů na osobu navázaných firem se státem. Jinak prázdný řetezec.
string fn_RenderPersonWithLink2(string osobaId) - vrací jméno, příjmení a rok narození osoby s odkazem na její profil. Pokud osoba neexistuje, vrací prázdný string
`string fn_RenderPersonNoLink(string osobaId, string jmeno="", string prijmeni="", string rokNarozeni ="") - vrací jméno osoby podle osobaId. Pokud není nalezena, vrátí osobu v dalších parametrech nebo prázdný string
string fn_RenderCompanyWithLink(string ico) - pro existující firmu vrací její název a odkaz na její profil. Jinak vrátí pouze IČO.
string fn_RenderCompanyStatistic(string ico, bool twoLines = false, string prefix = "", string postfix = "") - pro existující firmu vrací základní statistiku vztahů firmy se státem. Pro neexistující IČO prázdný řetezec.
string fn_FormatDate(datetime value, string format) - zobrazení data podle určeného formátu.
Pokud není format určen, je null nebo prázdný, použije se formát d.M.yyyy. Pro formátování použijte syntaxi .NET c# custom date and time format.
string fn_FormatNumber(dynamic value, string format = null) - naformátuje číslo. Formát může mít hodnoty "cs" nebo "en". Podle toho je zvolen formát čísla.
string fn_FormatPrice(dynamic value, string mena = "Kč") - naformátuje číslo jako cenu s měnou Kč
string fn_FormatDurationInSec(dynamic value, string format = null) - naformátuje dobu trvání do formátu [-][d'.']hh':'mm':'ss['.'fffffff]. Formát může mít hodnoty podle Custom format TimeSpan.
string fn_Pluralize(dynamic pocet, string zeroText, string oneText, string twoText, string moreText) - slova/věty v závislosti podle počtu. příklad: fn_Pluralize total "žádné nové zakázky" "jednu novou zakázku" "{0} nové zakázky" "{0} nových zakázek"
Dostupné a zpřístupněné datasety (tzn. ty co nejsou v betaverzi) jsou k nalezení na https://www.hlidacstatu.cz/data
Konkrétní příklad použití včetně registrace Datasetu, nastavení templatů, parsování obsahu a uložení dat najdeš na https://github.com/HlidacStatu/Datasety/tree/master/Dataset-RozhodnutiUOHS-ukazka. Ukázka je v C#, ale snadno čitelná.
Vytvoření a správa datových sad je zdarma, volně dostupné a prakticky neomezené. Preferujeme vytváření datových sad s daty státu, samosprávy, státních úřadů a firem, které mají či mohou mít informační hodnotu pro širší veřejnost anebo vhodně doplňují informace poskytované Hlídačem státu.
Datová sada (dataset) je strukturovaná sada záznamů, která je dostupná
