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

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;
    
    // Konfigurace – umožňuje měnit standardní chování web-service, můžete ponechat prázdné
    Map<OracleConfigurationField, string> configuration;
    
    // Heslo - pokud jej nemáte, získáte ho v administraci na https://admin.smartform.cz
    string password;
}

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
}

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

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