TARICSKbeta v.004

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