Dokumentace API – Hledání objektů podle souřadnic

Toto je popis starší verze služby pro hledání podle souřadnic. Doporučujeme používat aktuální verzi.

Webová služba pro hledání adres, parcel a lokalit podle souřadnic je k dispozici na adrese:

  • https://secure.smartform.cz/smartform-ws/reverseGeocode/v2

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

/** Dotaz hledání objektů podle souřadnic */
class ReverseGeocodeRequest 
{
    /** Zeměpisná šířka */
    double latitude;

    /** Zeměpisná délka */
    double longitude;

    /** Vstupní souřadnicový systém */
    CoordinateSystem inputCoordinateSystem;
}

Odpověď

/** Odpověď hledání objektů podle souřadnic */
class ReverseGeocodeResponse 
{
    /** 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é */
    String errorMessage;

    /** Výsledek hledání objektů podle souřadnic */
    ReverseGeocodeResult result;
}

Další objekty

/** Souřadnicový systém */
enum CoordinateSystem 
{
    /** Systém, který se používá v GPS */
    WGS84,
    
    /** 
     * Systém, který je používán českými úřady.  
     * Při zadávání JTSK souřadnic vložte souřadnici X do pole latitude a souřadnici Y do pole longitude. 
     * */
    JTSK
}

/** Výsledek hledání objektů podle souřadnic */
class ReverseGeocodeResult 
{
    /** Seznam nejbližších adres. */
    List<AddressWithDistance> addresses;

    /** Seznam nejbližších parcel. */
    List<ParcelWithDistance> parcels;
    
    /** Seznam nejbližších ulic/částí obce. */
    List<AddressWithDistance> localities;
}

/** Adresa a vzdálenost od zadaných souřadnic */
class AddressWithDistance 
{
    /** Vzdálenost od zadaných souřadnic (v m) */
    double distance;

    /** Adresa */
    Address address;
}

/** Parcela a vzdálenost od zadaných souřadnic */
class ParcelWithDistance  
{
    /** Vzdálenost od zadaných souřadnic (v m) */
    double distance;

    /** Parcela */
    Parcel parcel;
}

/** 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,
    
    /** Název volebního okrsku. V Česku číslo volebního okrsku (unikátní v rámci obce). */
    ELECTORAL_AREA_NAME,

    /** Kód volebního okrsku. */
    ELECTORAL_AREA_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
}

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

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

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

    /** Číslo katastrálního území */
    CADASTRAL_UNIT_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;
}

/** Parcela */
class Parcel 
{
    /** ID parcely. (V Česku ID podle databáze RÚIAN) */
    int id;

    /** Dvoupísmenný ISO kód státu */
    string countryCode;

    /** První číslo parcely. */
    int number1;

    /**
     * Druhé číslo parcely.
     * V Česku se jmenuje poddělení čísla a udává se za lomítkem (nepovinné).
     */
    int number2;

    /**
     * Typ číslování.
     * 
     * V Česku některé katastrální území používají dvě číselné řady: pro stavební pozemky a pro
     * ostatní pozemky.
     */
    ParcelNumberingType numberingType;

    /** Typ parcely */
    ParcelType type;

    /** Katastrální území – kód */
    int cadastralUnitCode;

    /** Katastrální území – název */
    string cadastralUnitName;

    /** Kód obce */
    int municipalityCode;

    /** Název obce */
    string municipalityName;

    /** Výměra v m2 */
    double area;

    /** Hranice ve formátu geoJSON v souřadnicovém systému WGS84 (GPS) */
    json border;

    /** Souřadnice */
    Coordinates coordinates;
    
    /** Seznam adresích míst na parcele */
    List<AddressReference> addresses;
}

/**
 * Číselné řady parcel.
 * 
 * V Česku existují v některých katastrálních územích dvě číselné řady parcel, 
 * jedna pro takzvané pozemkové parcely a druhá pro stavební parcely.
 * 
 * Viz https://cs.wikipedia.org/wiki/Parcelní_číslo
 */
enum ParcelNumberingType 
{
    /** CZ: Stavební parcely */
    BUILDING,

    /** CZ: Pozemkové parcely */
    OTHER
}

/** Způsob využití parcely */
enum ParcelType 
{
    /** Orná půda */
    ARABLE_LAND,

    /** Chmelnice */
    HOP_GARDEN,

    /** Vinice */
    VINEYARD,

    /** Zahrada */
    GARDEN,

    /** Ovocný sad */
    ORCHARD,

    /** Trvalý travní porost */
    GRASS,

    /** Lesní pozemek */
    WOOD,

    /** Vodní plocha */
    WATER,

    /** Zastavěná plocha */
    BUILDING_AREA,

    /** Ostatní plocha */
    OTHER
}

/** Stručná informace o adrese */
class AddressReference 
{
    /** Kód adresy */
    long code;

    /** Dvoupísmenný ISO kód státu */
    string countryCode;
    
    /** Celý název adresy */
    string wholeName;
}

/** 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é (např. 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
}

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