API pro Geokódování
Skupina funkcí zaměřená na vyhledávání adres a lokalit, jejich převod na souřadnice a zpět. Funkce se obvykle využívají pro validaci adres (ověření, že zadaná adresa je platná) a pro našeptávání adres (pomoc klientovi se zadáním validní adresy).
Popis funkcí
- Geokódování – Vyhledává entity (adresy) na základě textového dotazu. Získá souřadnice a další informace (např. okolní regionální strukturu)
- Našeptávání – funguje podobně jako geokódování, ale zohledňuje neúplné dotazy, takže jej lze použít k navrhování odpovídajících entit, když uživatel píše dotaz na umístění.
- Reverzní geokódování – vrací regionální entity na základě souřadnice (při kliknutí do mapy vrací adresy v daném bodě)
Funkce si můžete vyzkoušet v Testovací laboratoři. A na konkrétní příklady se podívejte v Tutoriálech.
Technická dokumentace
https://api.mapy.cz/v1/docs/geocode/
Technická dokumentace obsahuje přesný popis vstupních a výstupních parametrů, výchozích hodnot, chyby a další podrobnosti.
Vstupní parametry (pro Geokódování a Našeptávání)
| query | Hledaný výraz – více viz Dotazy a data |
| lang | Preferovaný jazyk názvů vyhledaných entit. (funkce vrátí např pro CZ: Praha 1 – Staré Město, Česko, pro EN: Prague 1 – Old Town, Czechia atd..) |
| limit | Max. počet výsledků |
| type | Požadovaný typ výsledků (co se hledá) regional – hledá v celé regionální struktuře (státy, města, adresy,…) – regional.country – státy – regional.region – regiony (v ČR např kraj a okres) – regional.municipality – obce – regional.municipality_part – části obcí, čtvrtě – regional.street – ulice – regional.address – adresy poi – body mimo regionální strukturu (zatím dále neděleny) coordinate – zeměpisné souřadnice v různých formátech Pokud Type nezadáte, hledá se v regional, poi (coordinate tedy ve výchozím nastavení nehledá). Pozn. – pro často používané omezení na města, vesnice a čtvrtě je vhodné použít regional.municipality + regional.municipality_part (menší vesnice jsou většinou části obcí) |
| locality | Omezení výsledků na určitou lokalitu. Nejsou vraceny výsledky mimo tuto lokalitu. Je možné zadat názvy lokalit oddělených čárkou (např. Praha 5, Lhota u Kolína), kódy států(cz, gb, us, …) nebo bounding box({minLon},{minLat},{maxLon}, {maxLat}) nebo jejich kombinace. Názvy lokalit (kromě kódů států) jsou interně převedeny na bounding boxy. Je doporučeno používat právě bounding boxy, aby se předešlo nejednoznačnostem. Pro usnadnění práce se v případě použití textové lokality vrátí ve výsledku odpovídající bounding boxy (nebo „Nenalezeno!“ u neznámých lokalit), kterými můžete textové lokality příště nahradit. V případě omezení na celé státy doporučujeme používat kódy států, v tomto případě je to přesnější než bounding boxy. |
| preferBBox, preferNear, preferNearPrecision | Preferování výsledků z dané oblasti (bounding box nebo poloha/kružnice). Jsou vraceny i výsledky mimo danou oblast, nicméně výsledky z požadované oblasti mají prioritu. |
Vstupní parametry pro reverzní geokodování
| lon, lat | Souřadnice, na kterých hledáme regionální entity |
| lang | Preferovaný jazyk názvů navrácených entit. |
Návratové hodnoty
Všechny tři funkce vrací ve výsledku stejnou datovou strukturu. Struktura obsahuje pole entit odpovídajících dotazu. Pro každou entitu vrací:
| name | textový název(Týnská ulička 610/7) |
| label | textové označení (adresa, město, rozhledna, zastávka MHD) |
| position | souřadnice lon, lat |
| type | typ entity, viz type ve vstupních parametrech |
| location | textová lokalita, do které daná entita patří (Praha 1 – Staré Město, Česko). Nejedná se o pouhý přepis regionální struktury. Je zde použito chytrých algoritmů pro zkracování, vynechávání duplicit v rámci obcí, čtvrtí, části obcí. Regiony se používají pouze tehdy, pokud město není v rámci státu unikátní. |
| regionalStructure | Kompletní rozpad regionální struktury, do které daná entita patří. Pro každou úroveň uvádím její textový název Name a její typ Type. Pouze pro regional.country je navíc uváděn parametr isoCode, který vrací dvou písmenný kód státu dle normy ISO 3166-1 alpha-2 Typy regional.region a regional.municipality_part mohou být ve struktuře vícekrát. V daném státě mají ale vždy fixní pořadí a jsou řazeny od nejmenšího po největší (např. v ČR je první region okres, druhý region kraj). V každém státě je ale hloubka a význam jiný. Číslo adresního bodu (regional.address) v ČR se může skládat z jednoho nebo dvou čísel oddělených lomítkem. Jejich význam je následující: První číslo – číslo bez prefixu – číslo popisné – prefix “ev. č.“ – číslo evidenční Druhé číslo (za lomítkem, ne všude existuje) – číslo orientační |
| zip | PSČ – pouze pokud máme pro daný stát data |
| locality | informace o převodu textové locality na bounding box – viz vstupní parametr locality |