Dokumentace API – Našeptávaní adres

Webová služba pro našeptávání adres je k dispozici na adrese

  • https://secure.smartform.cz/smartform-ws/oracle/v8

Dokumentaci starších verzí služby najdete na stránce Dokumentace API – Seznam verzí.

Autentizace

Služba využívá autentizační metodu Basic authentication. Jako jméno použijte uživatelské ID (clientId), které získáte po přihlášení do administrace v pravém horním rohu. Heslo si můžete zobrazit v administraci na záložce „Smartform Web Services“.

Při neúspěšné autentizaci vrací služba HTTP kód 401.

Vlastnosti dotazu

Dotazy musí být posílány metodou POST. Data jsou posílána ve formátu JSON s kódováním UTF-8.

Hlavička http requestu musí obsahovat následující položky:

název hodnota
Content-type application/json
Accept application/json

Změny oproti předchozím verzím

Novinky ve verzi 8

  • Používá nový slovenský registr. Tento registr je spravovaný slovenským ministerstvem vnitra a je denně aktualizovaný. Starší verze služby (v7 a starší) budou nadále používat stejný slovenský registr jako doposud.

  • Přidali jsme nový typ našeptávače – našeptávač pro obce – InputOracleFieldType.MUNICIPALITY.

    • Od dosavadního našeptávače pro obce (InputOracleFieldType.CITY) se liší tím, že našeptává vždy jen čisté názvy obcí. Našeptávač InputOracleFieldType.CITY umí našeptávat i pošty nebo části obce.

    • Od našeptávače pro obce a okresy (InputOracleFieldType.MUNICIPALITY_AND_DISTRICT) se liší tím, že je určen pro našeptávání celé adresy (ve spolupráci s našeptávači pro ulici a číslo domu a PSČ). Našeptávač InputOracleFieldType.MUNICIPALITY_AND_DISTRICT je určen pro našeptávání samostatného názvu obce (např. když se ve formuláři zadává místo narození).

  • Do těla dotazu jsme přidali nový prvek: country. Slouží pro zadání země, pro kterou se má našeptávat. Dříve se země zadávala v prvku values. Zrušili jsme položku InputOracleFieldType.COUNTRY.

Novinky ve verzi 7

  • K autentizaci se používá metoda Basic authentication (viz výše). Z těla dotazu byla odstraněna property password.

Struktura dotazu a odpovědi

Následuje referenční struktura dotazu a odpovědi. Objekty jsou zachyceny ve formě pseudokódu pro lepší pochopení struktury.

Dotaz

class OracleRequest
{
    // Identifikace dotazu
    int id;
    
    // Obsah formulářových políček
    // Očekává se jedna z těchto kombinací:
    //  * STREET, NUMBER, MUNICIPALITY (nebo CITY), ZIP
    //  * STREET_AND_NUMBER, MUNICIPALITY (nebo CITY), ZIP
    //  * WHOLE_ADDRESS
    //  * MUNICIPALITY_AND_DISTRICT 
    Map<InputOracleFieldType, string> values;
    
    // Které políčko se právě edituje
    InputOracleFieldType fieldType;
    
    // Stát – může nabývat hodnot "CZ" a "SK".
    // Pokud není vyplněné, našeptává se pro Česko
    public String country;
    
    // Kolik maximálně našeptaváných možností se má vrátit
    // Při zadání většího čísla než 21 je limit nastaven na 21
    int limit;
    
    // Seznam preferenčních nebo filtračních oblastí.
    // Umožňuje nastavit seznam obcí, okresů nebo krajů, na které se má našeptávání omezit,
    // popřípadě mají být při našeptávání upřednostněny.
    //
    // Při nastavování našeptávací oblasti se mohou hodit kódy českých krajů a okresů. 
    // Kódy obcí získáte v demu web-service s validací názvu obcí.
    SuggestContext suggestContext;
    
    // Konfigurace – umožňuje měnit standardní chování web-service, můžete ponechat prázdné
    Map<OracleConfigurationField, string> configuration;
}

Odpověď

class OracleResponse
{
    // Výsledek dotazu
    ResultCode resultCode;
    
    // Detailní popis chyby (pokud je resultCode == FAIL)
    string errorMessage;
    
    // Identifikace dotazu - pro kontrolu (mělo by být shodné s číslem v dotazu)
    int id;
    
    // Seznam návrhů našeptávače
    List<AddressSuggestion> suggestions;
}    

Další objekty

// Typy políček ve formuláři
enum InputOracleFieldType
{
    // číslo domu 
    NUMBER,
    // ulice a číslo domu
    STREET_AND_NUMBER,
    // ulice
    STREET,
    // obec
    MUNICIPALITY,
    // obec (na rozdíl od políčka může obsahovat i část obce, poštu)
    CITY,
    // obec a okres
    MUNICIPALITY_AND_DISTRICT,
    // PSČ
    ZIP,
    // celá adresa
    WHOLE_ADDRESS
}
// Našeptávací kontext. Umožňuje zúžení oblasti našeptávání.
//
// Kontexty jsou dvojího druhu:
//  - filtrační – pak lze zadat jen adresy ze zadané oblasti
//  - preferenční – daná oblast bude mít při našeptávání přednost
class SuggestContext {

    // typ kontextu
    SuggestContextType type;

    // vymezení oblasti našeptávání: seznam kódů obcí, okresů a krajů
    List<SuggestContextItem> items;
}
// Typ našeptávacího kontextu.
enum SuggestContextType {

    // Filtrační našeptávací kontext: našeptávají se jen adresy z oblasti zadané našeptávacím kontextem.
    FILTER,

    // Preferenční našeptávací kontext: adresy z oblasti našeptávacího kontextu jsou při našeptávání upřednostněny.
    PREFERENCE
}
// Položka našeptávacího kontextu.
class SuggestContextItem {

    // typ položky našeptávacího kontextu
    SuggestContextAreaCodeType codeType;

    // kód obce, kraje nebo okresu
    //
    // Při nastavování našeptávací oblasti se mohou hodit kódy českých krajů a okresů. 
    // Kódy obcí získáte v demu web-service s validací názvu obcí.
    int code;
}
// Typ položky našeptávacího kontextu
enum SuggestContextAreaCodeType {

    // Kód obce
    MUNICIPALITY_CODE,

    // Kód okresu
    DISTRICT_CODE,

    // Kód kraje
    REGION_CODE
}
// Seznam konfiguračních políček – tato políčka mění standardní chování našeptávácí web-service.
// Žádné z těchto políček není v konfiguraci povinné.
enum OracleConfigurationField
{
    
    // Když do konfigurace requestu přidáte položku "SK_BRATISLAVA_KOSICE_UNDIVIDED":"true",
    // budou při našeptávání obcí pomocí vstupního políčka MUNICIPALITY_AND_DISTRICT
    // slovenská města Bratislava a Košice považovány za jednu obec 
    // (v registru slovenských adres totiž obce Bratislava a Košice nejsou, 
    // jsou tam jen jejich části, např. „Košice – Džungla“).
    SK_BRATISLAVA_KOSICE_UNDIVIDED,
    
    // Když do konfigurace requestu přidáte položku "CZ_PRAHA_DIVIDED_INTO_10_PARTS":"true",
    // budou do našeptávání obcí pomocí vstupního políčka MUNICIPALITY_AND_DISTRICT
    // zahrnuty i pražské obvody (Praha 1 – Praha 10). Naopak se nenašeptává samotná Praha.
    CZ_PRAHA_DIVIDED_INTO_10_PARTS
    
}
// Jedna položka nabídky pro našeptávač.
class AddressSuggestion
{
    // Pro které políčko je návrh určen
    OutputOracleFieldType fieldType;
    
    // Hodnoty určené formulářovým políčkům.
    Map<OutputOracleFieldType, string> values;
    
    // Doplňující příznaky k našeptávané položce
    // Seznam příznaků a jejich defaultních hodnot najdete v AddressSuggestionFlag
    // Příznak může chybět, pokud nemá v daném kontextu smysl nebo pokud nabývá defaultní hodnoty
    Map<AddressSuggestionFlag, string> flags;

}
// Typy políček v AddressSuggestion
// Obsahuje všechna políčka z InputOracleFieldType plus některá navíc
enum OutputOracleFieldType
{
    // číslo domu 
    NUMBER,
    // ulice a číslo domu
    STREET_AND_NUMBER,
    // ulice
    STREET,
    // obec (může obsahovat i část obce, poštu) 
    CITY,
    // obec a okres
    MUNICIPALITY_AND_DISTRICT,
    // obec
    MUNICIPALITY,
    // okres
    DISTRICT,
    // kraj
    REGION,
    // PSČ
    ZIP,
    // celá adresa
    WHOLE_ADDRESS,
}
// Seznam možných příznaků v AddressSuggestion
enum AddressSuggestionFlag
{
    // zdali návrh obsahuje celou adresu
    // hodnoty: "false" (defaultní), "true"
    WHOLE_ADDRESS,
    // při našeptávání obcí značí, že u dané obce není třeba uvádět okres
    // hodnoty: "false" (defaultní), "true"
    UNIQUE_MUNICIPALITY,
}
/** Výsledek dotazu. */
enum ResultCode 
{
    /** Volání service proběhlo v pořádku. */
    OK,
    
    /** Při volání service došlo k chybě. */
    FAIL
}

Tabulka typů v pseudokódu

typ v pseudokódu typ v JSON
třída (class) vnořený objekt
výčet (enum) řetězec se jménem vybrané položky
List pole
Map objekt – klíče a hodnoty se stanou položkami objektu
string řetězec
int číslo
double číslo
boolean boolean
char (jeden znak) řetězec


Hlavní navigace: