JSON API

Rozhranie poskytujúce dáta a funkcie tejto aplikácie pre aplikácie tretích strán, sekcia pre vývojárov.

Formát vstupných dát (JSON), HTTP metóda GET:

hodnoty uvedené v kľúči na dopyt dát sú zároveň štandartne prednastavenými hodnotami, ktoré budú použité ak bude daný parameter z dopytu vynechaný

{
    hscode: "",             // text
    description: "",        // text
    page: 1,                // kladné celé číslo,
    per_page: 25,           // kladné celé číslo,
    load_depth_limit: 1     // 1 alebo 0 - pravda/nepravda
    load_ancestors: 1       // 1 alebo 0 - pravda/nepravda
}

hscode	hľadaný TARIC kód (vyberá výsledky začínajúce na hľadaný výraz)
description	popisný text TARIC kódu (vyberá výsledky obsahujúce textový reťazec, nedbá na diakritiku - pri zadaní výrazu s diakritikou vyhľadá aj varianty bez a opačne)
page	načítať ďalšiu sadu výsledkov (ak k dispozící)
per_page	počet výsledkov na jednu sadu (stránku) - maximálny povolený parameter je nastavený na 100 výsledkov, akákoľvek vyššia hodnota bude automaticky obmedzená na 100. Do počtu načítaných výsledkov sa ale nezarátavajú položky, ktoré sú rodičovskými položkami pre daný výsledok ak je aktívna konfigurácia load_ancestors
load_depth_limit	inteligentné obmedzenie načítavania podpoložiek do určitej hierarchickej úrovne. Aplikuje sa len v prípade že je na vyhľadávanie poskytnutý len TARIC kód - parameter hscode a to nasledovným spôsobom: 1 číselný znak: načítané sú iba kapitoly (1-99) začínajúce týmto číslom 2-3 číselné znaky: načítaná je kapitola a jej podkapitoly 4 číselné znaky: načítaná je kapitola, jej podkapitoly a položky 5-10 číselných znakov: prehľadáva sa strom vo všetkých hierarchických úrovniach
load_ancestors	načítať aj hierarchicky nadradené (rodičovské) položky až po koreňovú položku. Opakujúce sa rodičovské položky v prípade že niektoré výsledky vyhľadávania zdieľajú niektorú spoločnú vetvu nebudú načítané

Formát odpovede

formát hlavičky s vlastnosťami je zhodný pre všetky použité verzie API

{
    props: {
        page:               < celé kladné číslo >,
        total_pages:        < celé kladné číslo >,
        items_total:        < 0 alebo celé kladné číslo >,
        items_per_page:     < celé kladné číslo >,
        items_loaded:       < 0 alebo celé kladné číslo >,
        load_ancestors:     < true alebo false >,
        load_depth_limit:   < true alebo false >
    },
    data: ... // výstup sa bude líšiť podľa verzie použitého API
}

page	číslo aktuálnej sady (strany)
total_pages	sád (strán) celkom
items_total	celkový počet výsledkov
items_per_page	výsledkov na sadu (stranu)
items_loaded	počet už načítaných výsledkov (počet na stranu x číslo strany)
load_ancestors	načítavanie rodičovských položiek
load_depth_limit	limit pre načítavanie položiek iba do určitej generácie (viac info o tomto nastavení v sekcii o vstupných dátach vyššie)

api_v1

rozhranie vracajúce dáta "plochého" typu

http://taric.sk/api_v1/taric.json

{
    props: {
        ...
    },
    data: [
        {
            // atribúty jednotlivej položky,
            // viď podsekciu "atribúty položky" nižšie
        },
        {
            // dalšia položka atď.
        }
    ]
}

api_v2

rozhranie vracajúce dáta usporiadané v stromovej štruktúre

http://taric.sk/api_v2/taric.json

{
    props: {
        ...
    },
    data: {
        < id položky >: {
            < id položky >: { ... },
            < id položky >: { ... }
            ...
            self: {
                // atribúty jednotlivej položky,
                // viď podsekciu "atribúty položky" nižšie
            }
        }
    }
}

atribúty položky

zoznam atribútov samotnej položky

...
    id:                     < celé kladné číslo >,
    nomenclature:           < text >,
    description:            < text >,
    indent:                 < nula alebo celé kladné číslo >,
    date_start:             < NULL alebo textová reprezentácia dátumu**[1] >,
    date_end:               < NULL alebo textová reprezentácia dátumu**[1] >,
    ancstr:                 < NULL alebo text >,
    childrens_count:        < nula alebo celé kladné číslo >,
    childrens_actual_count: < nula alebo celé kladné číslo >

    // **[1] formát dátumu podľa kľúča RRRR-MM-DD
...

id	unikátny identifikátor záznamu
nomenclature	TARIC kód
description	popis TARIC kódu
indent	hierarchická úroveň záznamu, 0 znamená najvyššia úroveň, koreňové položky (kapitola)
date_start	dátum, kedy záznam vstúpil v platnosť
date_end	dátum, kedy záznamu končí platnosť
ancstr	textový reťazec reprezentujúci identifikátory položiek oddelené '-', ktoré sú položke nadradené, hierarchicky zoradené až ku koreňovej položke. Hodnota NULL sa vyskytuje pri koreňových položkách
childrens_count	počet všetkých potomkov v prvej nižšej hierarhickej úrovni
childrens_actual_count	počet potomkov v prvej nižšej hierarhickej úrovni platných pre aktuálne časové obdobie