Dokumentace API – Našeptávaní adres (verze 1)

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 adresách:

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

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
    Map<OracleFieldType, string> values;
    
    // Které políčko se právě edituje
    OracleFieldType fieldType;
    
    // Kolik maximálně našeptaváných možností se má vrátit
    int limit;
    
    // Heslo - identifikace uživatele
    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 OracleFieldType
{
    // číslo domu 
    NUMBER,
    // ulice a číslo domu
    STREET_AND_NUMBER,
    // ulice
    STREET,
    // obec 
    CITY,
    // PSČ
    ZIP
}

// Jedna položka nabídky pro našeptávač.
class AddressSuggestion
{
    // Pro které políčko je návrh určen
    OracleFieldType fieldType;
    
    // Příznak, zda návrh obsahuje celou adresu
    boolean wholeAddress;
    
    // Hodnoty určené formulářovým políčkům.
    Map<OracleFieldType, String> values;
}

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