Dokumentace API – Hledání parcel

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

Webová služba pro hledání parcel je k dispozici na adrese:

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

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í parcel.
 * 
 * Vždy musí obsahovat 
 *  - identifikaci katastrálního území, tedy "cadastralUnitName" nebo "cadastralUnitCode".
 *  - číslo parcely, tedy dvojici "number1" a "number2" nebo "wholeNumber".  
 */
class SearchParcelRequest 
{
    /** Heslo - pokud jej nemáte, získáte ho v administraci na https://admin.smartform.cz */
    string password;

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

    /** Kód katastrálního území */
    int cadastralUnitCode;

    /** První číslo parcely. V Česku slouží pro zadání kmenového čísla. */
    int number1;

    /** 
     * Druhé číslo parcely. V Česku slouží pro zadání poddělení čísla.
     * 
     * Když je zadáno "number1" a není zadáno "number2", hledají se jen parcely bez poddělení čísla. 
     */
    int number2;

    /** 
     * Celé číslo parcely.
     * 
     * Může mít následující tvary:
     *    321
     *    321/45
     *    st 321
     *    st. 321/45
     *    pp 321/45
     *    pp. 321
     */
    string wholeNumber;
    
    /**
     * Typ číslování.
     * 
     * V Česku některé katastrální území používají dvě číselné řady: pro stavební pozemky a pro
     * ostatní pozemky.
     * 
     * Nepovinný vstup.
     */
    ParcelNumberingType numberingType;

}

Odpověď

/** Odpověď hledání parcel. */
class SearchParcelResponse 
{
    /** Zdali vůbec došlo k hledání parcel a hledání proběhlo v pořádku */
    ResultCode resultCode;

    /** Typ výsledku hledání parcel. */
    ResultType resultType;

    /** Nalezené parcely. */
    List<Parcel> parcels;

    /** Doplňující vysvětlení k výsledku hledání. Např. když je vstup zadán špatně nebo když dojde k nějaké chybě. */
    string message;
}

Další objekty

/** Typ výsledku hledání parcel. */
enum ResultType 
{
    /** Byla nalezena právě jedna parcela. */
    HIT,

    /** Nebyla nalezena žádná parcela. */
    NOTHING,

    /** Bylo nalezeno více parcel.*/
    MANY,

    /** Nebyla nalezena žádná parcela, protože vstupní data obsahují nějaký závažný nedostatek. */
    BAD_INPUT
}    

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