Dokumentace API V2 REST API V2 Hlídače státu

Svůj API token najdeš https://www.hlidacstatu.cz/api.

curl -X GET https://www.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í:

Autorizace

Všechna volání API jsou monitorována a ukládána.


API a Swagger

Dokumentaci jednotlivých API funkcí najdete na https://www.hlidacstatu.cz/api/v2/swagger/index. Swagger file je na https://www.hlidacstatu.cz/api/v2/swagger/

Na této stránce najdete podrobnější dokumentaci k datasetům - uživatelskýcm databázím Hlídače státu.


Licence volná

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:

  1. Dílo a obsah smíte stáhnout, sdílet a libovolně upravit.

  2. 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)

  3. Nesmíte přidat žádná další technická či právní omezení nad rámec této licence.

  4. Pokud vám tato licence nevyhovuje, napište na api@hlidacstatu.cz

Přečtěte si ji prosím.

Licence komerční

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


Datasety

Parametry nové datové sady

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.

Popis struktury registrace 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"]]
}
HsProcessType - doplnění objektu o další údaje ze strany Hlídače

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.


HTML Template pro datasety - syntaxe a speciální funkce

HTML template pro searchResultTemplate a detailTemplate

Template je možné definovat dvěma způsoby:

  1. 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"]
    }
    
  2. 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.

Syntaxe HTML Template - Scriban

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

Vyhledávání

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>

Detail záznamu

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.

Dostupné funkce pro formátování výstupu

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

Zobrazení dat na webu

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á

Pomozte nám udržovat český stát transparentní

Za tři roky nám 732 lidí darovalo 2 053 880 Kč .

  • Kontrolujeme politiky a úředníky, zda s našimi penězi zacházejí správně.
  • Stali jsme se důležitým zdrojem informací pro novináře.
  • Zvyšujeme transparentnost českého státu.
  • Pomáháme státu zavádět moderní e-government.

Pomozte nám i vy