Dokumentace API – Našeptávaní adres

Toto je popis starší verze služby pro našeptávání adres. Doporučujeme používat aktuální verzi.

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

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

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

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, CITY, ZIP, COUNTRY
    //  * STREET_AND_NUMBER, CITY, ZIP, COUNTRY
    //  * WHOLE_ADDRESS, COUNTRY
    //  * MUNICIPALITY_AND_DISTRICT, COUNTRY 
    Map<InputOracleFieldType, string> values;
    
    // Které políčko se právě edituje
    InputOracleFieldType fieldType;
    
    // Kolik maximálně našeptaváných možností se má vrátit
    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 krajů, okresů a 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 (může obsahovat i část obce, poštu) 
    CITY,
    // obec a okres
    MUNICIPALITY_AND_DISTRICT,
    // PSČ
    ZIP,
    // celá adresa
    WHOLE_ADDRESS,
    // Stát – může nabývat hodnot "CZ" a "SK"
    COUNTRY
}

// 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