Dokumentace API – Validace adres

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 adrese:

  • https://secure.smartform.cz/smartform-ws/validateAddress/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

/** Dotaz validace adres */
class ValidateAddressRequest 
{
    /** Identifikace dotazu, slouží jen pro spárování dotazu a odpovědi, pro validaci není důležité. */
    int id;

    /** Heslo - pokud jej nemáte, získáte ho v administraci na https://admin.smartform.cz */
    string password;

    /** Vstupní hodnoty, podle kterých se adresa bude hledat */
    Map<InputAddressFieldType, string> values;

    /** 
     * Seznam kódů států, ve kterých se bude adresa hledat.
     * Kódy mohou nabývat hodnot "CZ" a "SK"       
     */
    List<string> countries;

    /** Konfigurace – umožňuje měnit standardní chování web-service, můžete ponechat prázdné */
    Map<ValidateAddressConfigurationField, string> configuration;
}

Odpověď

/** Odpověď validace adres */
class ValidateAddressResponse 
{
    /** Identifikace odpovědi, odpovídá id dotazu */
    int id;

    /** Zdali vůbec došlo k validaci a zda validace proběhla v pořádku */
    ResultCode resultCode;

    /** 
     * Pokud došlo k nějaké chybě, popisuje k jaké. 
     * Může obsahovat upozornění na nějaký nekritický problém, i když validace proběhne korektně. 
     */
    string errorMessage;

    /** Výsledek validace */
    ValidateAddressResult result;
}

Další objekty

/** Typ vstupních políček */
enum InputAddressFieldType
{
    /** 
     * Ulice (nebo část obce) a číslo.
     * Např. "Smetanova 11", "Rychlonožkova 1567/4a" nebo "Horní Lhota 17"       
     */
    FIRST_LINE, 
    
    /** 
     * Celý řádek s městem. 
     * Např. "České Budějovice", "Praha", "Praha 4", "Praha - Podolí", "Praha 4 - Podolí", "Praha 4, Podolí" 
     */
    SECOND_LINE, 

    /** 
     * Obec a (nepovinně) okres. 
     * Obec a okres mohou být spojeny libovolně (např. čárkou, závorkami, středníkem) 
     */
    MUNICIPALITY_AND_DISTRICT, 
    
    /** Psč. */
    ZIP,
    
    /** Jméno ulice. */
    STREET,
    
    /** Celé číslo domu (popisné a/nebo orientační a/nebo orientační písmeno). */
    NUMBER_WHOLE,
    
    /** Celá adresa. */
    WHOLE_ADDRESS,

    /** Nějaké jedno číslo domu. */
    NUMBER_1,
    /** Nějaké jedno číslo domu. */
    NUMBER_2,
    /** Nějaké jedno číslo domu. */
    NUMBER_3,
    
    /** Číslo popisné. */
    NUMBER_POPIS,
    
    /** Číslo evidenční. */
    NUMBER_EVIDENT,
    
    /** Číslo orientační. */
    NUMBER_ORIENT,
    /** Písmeno u orientačního čísla. */
    CHAR_ORIENT,
    
    /** Kód adresy (např RÚIAN kód). */
    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 ValidateAddressConfigurationField
{
    
    // Když do konfigurace requestu přidáte položku "SK_BRATISLAVA_KOSICE_UNDIVIDED":"true",
    // budou při validaci 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
    
}

/** Výsledek validace adres */
class ValidateAddressResult 
{
    /** Typ výsledku */
    ResultType type;

    /** Seznam nalezených adres */
    List<Address> addresses;

    /** Doplňující informace k validaci */
    string hint;
}

/** Typ výsledku validace */
enum ResultType 
{
    /** Byla nalezena právě jedna přesná adresa*/
    HIT,
    
    /** Byla nalezena právě jedna částečná adresa */
    PARTIAL_HIT,
    
    /** Nebyla nalezena žádna adresa */
    NOTHING,
    
    /** Bylo nalezeno více adres (ať už přesných či částečných) */
    MANY,
    
    /** Bylo nalezeno více adres (ať už přesných či částečných) 
        – ve výsledku validace nejsou uvedeny všechny nalezené adresy */    
    TOO_MANY
}

/** Adresa */
class Address 
{
    /** Typ adresy - přesná nebo částečná */
    AddressType type;

    /** 
     * Mapa výstupních políček zvalidované adresy.
     * Je-li adresou přesná adresa, bude mapa obsahovat všechna políčka
     * Je-li adresou částečná adresa, bude mapa obsahovat jen políčka, která se podařilo určit.
     * 
     * V mapě ovšem mohou být i hodnoty null: 
     * Když bude výsledkem částečná adresa - např. malá obec, ve které nejsou ulice, 
     * bude v mapě i dvojice "STREET_NAME: null"                          
     */
    Map<OutputAddressFieldType, string> values;

    /** Souřadnice — pokud nejsou známé, je hodnota null. */
    Coordinates coordinates;
	
    /** Informace o nemovitosti — pokud nejsou známé, je hodnota null. */
    Map<OutputRealEstateField, string> realEstateDetails;
}

/** Typ adresy */
enum AddressType 
{
    /** Přesná adresa – obsahuje číslo domu */
    EXACT

    /** Částečná adres - např. část obce, ulice, obec */
    PARTIAL
}

/** Typy výstupních políček zvalidované adresy */
enum OutputAddressFieldType 
{
    /** Kód v registru RUIAN */
    CODE,

    /** Jméno ulice. Může být null, když adresní místo nemá ulici (v menších obcích) */
    STREET_NAME,

    /** Kód ulice v RUIAN. Může být null. */
    STREET_CODE,

    /** Název obce */
    MUNICIPALITY_NAME,

    /** Kód obce v RUIAN */
    MUNICIPALITY_CODE,

    /** Název pošty */
    POST_NAME,

    /** PSČ */
    ZIP,

    /** Obec a (pokud je to potřeba tak i) okres */
    MUNICIPALITY_AND_OPTIONAL_DISTRICT,
	
    /** Jméno části obce. */
    MUNICIPALITY_PART_NAME,

    /** Kód části obce v RUIAN */
    MUNICIPALITY_PART_CODE,

    /** Název městské části - např. "Praha 13" */
    CITY_AREA_1_NAME,

    /** Kód městské části v RUIAN */
    CITY_AREA_1_CODE,

    /** Pražský obvod - jen pro Prahu ("Praha 1" - "Praha 10) */
    CITY_AREA_2_NAME,

    /** Kód pražského obvodu v RUIAN */
    CITY_AREA_2_CODE,

    /** Správní obvod - v Praze je "Praha 1" - "Praha 22" */
    CITY_AREA_3_NAME,

    /** Kód správního obvodu v RUIAN */
    CITY_AREA_3_CODE,

    /** Okres - např. "Hlavní město Praha" nebo "Liberec" */
    DISTRICT_NAME,

    /** Kód okresu */
    DISTRICT_CODE,

    /** Kraj - např. "Hlavní město Praha" nebo "Liberecký kraj" */
    REGION_NAME,

    /** Kód kraje */
    REGION_CODE,

    /** Název státu */
    COUNTRY_NAME,

    /** Dvoupísmenný ISO kód státu */
    COUNTRY_CODE,

    /** Číslo popisné */
    NUMBER_POPISNE,

    /** Číslo evidenční */
    NUMBER_EVIDENCNI,

    /** Číslo orientační */
    NUMBER_ORIENT,

    /** Písmeno u orientačního číslo */
    CHAR_ORIENT,

    /** Zformátované celé číslo - např. "154", "622/37" nebo i "č.p. 35" */
    NUMBER_WHOLE,

    /** První řádka v adrese (ulice nebo část obce + celé číslo domu) */
    FIRST_LINE,

    /** První řádka v adrese bez čísla (ulice nebo část obce) */
    FIRST_LINE_NO_NUMBER,

    /** Druhá řádka v adrese - např. "Plzeň 1" nebo "Praha 4 - Nusle" */
    SECOND_LINE,

    /** Celé jméno nalezené adresy */
    WHOLE_NAME
}

/** Souřadnice */
class Coordinates 
{
    /** Typ souřadnic */
    CoordinatesType type;

    /** Souřadnice JTSK – osa X */
    double jtskX;

    /** Souřadnice JTSK – osa Y */ 
    double jtskY;

    /** GPS – šířka */
    double gpsLat;

    /** GPS – délka */
    double gpsLng;
}

/** Typ souřadnic */
enum CoordinatesType 
{
    /** Souřadnice jsou přesné (ukazují na konkrétní adresu) */
    EXACT,
    
    /** Souřadnice ukazují na střed oblasti (např. střed obce) */
    CENTER,
    
    /** Výsledná souřadnice je dána výpočtem (např. průměr souřadnic adres z jedné ulice) */
    APPROXIMATE
}

/** Typy výstupních políček obsahujících informace o nemovitosti */
enum OutputRealEstateField 
{
    /** Kmenové číslo parcely */
    LAND_LOT_NUMBER_1;

    /** Poddělení (pořadové číslo nové parcely v rámci původní parcely). Pokud není, má hodnotu null */
    LAND_LOT_NUMBER_2;

    /** Název katastrálního území */
    CADASTRAL_DISTRICT_NAME;

    /** Číslo katastrálního území */
    CADASTRAL_DISTRICT_CODE;
    
    /** Informace o výtahu. Může mít hodnoty: "true", "false", null */
    BUILDING_WITH_LIFT;

    /** Počet podlaží */
    NUMBER_OF_STOREYS;

    /** Počet bytů */
    NUMBER_OF_FLATS;
	
    /** Podlahová plocha [m2] */
    FLOOR_AREA;
}

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