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
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) Pokud Type nezadáte, hledá se ve všech více uvedených typech. 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

Chytré vyhledávání

Funkce Geokódování a Našeptávání prohledávají data pomocí chytrých (a neustále rozvíjených) algoritmů. S čím si např. dokáže vyhledávání poradit:

Různé formy zadání

Dlouhá 21, Praha 1
Dlouhá 737, Praha 1
Dlouhá 737/21, Praha
Dlouhá 21, 110 00
Dlouhá 21, Staré město

Různé pořadí

Dlouhá 21, Praha 1
Praha 1, Dlouhá 21
11000,Dlouhá 21
..

Různé vstupní jazyky

Václavské náměstí 1, Praha 1
Wenceslas Square 846/1
Wenzelsplatz 1, prager neustadt

Místní názvy

Václavák 846/1

Překlepy, diakritika (jen suggest, strojově učený model)

dloha 21 pracha 1
vaclafske namsti 1

Podrobná data

Jakkoliv chytré hledání nenajde nic, pokud nehledá v podrobné databázi. S jakými daty naše hledání pracuje:

Adresní body

Primárním zdrojem je pravidelně importovaný RUIAN
Redakce občas přidává adresy “na míru” (pokud v RUIAN zatím chybějí, nebo se jedná o místní používané “neoficiální” označení)

Zbytek světa

Základ tvoří data z OpenStreetMap
V jednotlivých státech postupně doplňujeme o místní registry
- Máme Slovensko, Rakousko, Polsko, Švýcarsko, Belgie, Lucembursko, Slovinsko, Estonsko
- Připravujeme Nizozemí, Finsko, Dánsko, Norsko, atd.

Regionální data udržujeme jak v nativním jazyce, tak dohledáváme překlady do dalších jazyků a různé alternativní názvy.

ZIP kódy (PSČ)

CZ, SK, Germany, Poland, Austria, Hungary, Italy, France, United kingdom
Chystáme zbytek západní Evropy