Dokumentace API – Validace adres (verze 1)

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

Webová služba pro validaci adres je k dispozici na adresách:

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

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 AnnounceRequest
{
    // Identifikace dotazu
    int id;
    
    // Obsah formulářových políček
    Map<OracleFieldType, string> values;
    
    // Heslo - identifikace uživatele
    string password;
}

Odpověď

class AnnounceResponse
{
    // 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;
    
    // Samotný výsledek validace
    AnnounceValidationResult result;
}

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
}

class AnnounceValidationResult
{
    // Kód výsledku validace
    ValidationType type;
    
    // Seznam vyhovujících adres - jedna pokud je type == HIT,
    // více adres pokud type == MANY nebo TOOMANY
    List<AnnounceAddress> addresses;
    
    // Doplňující informace k validaci (nápověda k optimálnímu zadání adresy) 
    string hint;
}    

enum ValidationType
{
    // Byla nalezena právě jedna adresa.
    HIT,
    /** Bylo nalezeno více adres, všechny tyto adresy jsou obsaženy ve výsledku validace. */
    MANY,
    /** Bylo nalezeno více adres, ve výsledku validace jsou jen některé. */
    TOOMANY,
    /** Nebyla nalezena žádná adresa. */
    NOTHING,
    /** Bylo zadáno příliš málo vstupních parametrů. */
    INSUFFICIENT_DATA,
}

// Jedna zvalidovaná adresa
class AnnounceAddress
{
    // Ulice
    AddressEntity street;
    
    // Část obce
    AddressEntity part;
    
    // Obec
    AddressEntity city;
    
    // Pošta + PSČ
    AddressEntity post;
    
    // Mestská část
    AddressEntity mcast;
    
    // Pražský obvod (Praha 1-10)
    AddressEntity pobvod;
    
    // Správní obvod Prahy (Praha 1-22)
    AddressEntity sobvod;
    
    // Okres
    string district;
    
    // Kraj
    string region;
    
    // Příznak, jestli je PSČ v adrese speciální
    boolean isPscSpecial;
    
    // Číslo objektu (popisné/evidenční, orientační)
    AnnounceNumber number;
    
    // Kód adresy v databázi RUIAN (drive UIR-ADR)
    int uiradrCode;
    
    // X-souřadnice adresy v systému S-JTSK v metrech. 
    int coordX;
    
    // Y-souřadnice adresy v systému S-JTSK v metrech.
    int coordY;
}

// Reprezentace části zvalidované adresy.
class AddressEntity
{
    // Typ entity
    AddressEntityType type;
    
    // Název entity
    string name;
    
    // Referenční ID entity v RUIAN (pro poštu je to PSČ)
    int id;
}

enum AddressEntityType
{
    // ulice
    STREET,
    
    // část obce
    PART,
    
    // obec
    CITY,
    
    // pošta
    POST,
    
    // PSČ
    ZIP,
    
    // městská část
    MCAST,
    
    // správní obvod
    SOBVOD,
    
    // pražský obvod
    POBVOD
}

// Číslo ve zvalidované adrese
class AnnounceNumber
{
    // Číslo domu (popisné/evidenční)
    int cisloDomu;
    
    // Typ čísla domu (popisné/evidenční)	
    NumberType type;
    
    // Orientační číslo
    int cisloOrient;
    
    // Orientační písmeno
    char pismenoOrient;
    
    // Pokud je true, musí se pro jednoznačnost této adresy označit čísla svým typem.
    // (např. když existuje Vodičkova čp.35 a Vodičkova or.č.35)
    boolean showNumberType;
    
    // Pokud je true, musí se pro jednoznačnost této adresy uvést část obce, do které náleží.
    // (např. když existují dvě adresy Vodičkova 35, každá v jiné části obce)	
    boolean showPart;
}

// Typ čísla ve zvalidované adrese
enum NumberType
{
	// popisné
	POPIS,
	
	// evidenční
	EVIDENT
}

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