API pro Plánování
Plánování slouží k vyhledávání trasy mezi dvěma (nebo více) body. Funkce najde vhodnou trasu podle zvoleného typu plánování (autem, pěšky, …) a vrátí délku, čas a geometrii nalezené trasy.
Popis funkcí
- Naplánuj trasu – funkce naplánuje trasu mezi dvěma (nebo více) body.
- Maticové plánování – (matrix routing) funkce počítá časy a vzdálenosti mezi M starty a N cíli.
Podívejte se na ukázky použití plánování i maticového plánování.
Technická dokumentace
https://api.mapy.com/v1/docs/routing/
Technická dokumentace obsahuje přesný popis vstupních a výstupních parametrů, výchozích hodnot, chyby a další podrobnosti.
Funkce Naplánuj trasu
Funkce naplánuje trasu mezi startem a cílem, případně přes průjezdní body. Plánuje zvoleným typem plánování (autem, na kole, pěšky,…). Vrátí délku, čas a přesnou geometrii dané trasy.
Funkce si můžete vyzkoušet v Testovací laboratoři.
Vstupní parametry
| start, end | Souřadnice startu a cíle |
| routeType | Typ plánování – více v kapitole Typ plánování |
| lang | Preferovaný jazyk – na tuto funkci nemá vliv |
| format | Formát výstupní geometrie trasy (geojson, polyline, polyline) |
| avoidToll | Vyhnout se placeným úsekům |
| avoidHighways | Vyhnout se dálnicím |
| waypoints | Průjezdní body, maximálně 15. Navržená trasa povede ze startu, přes tyto průjezdní body (v zadaném pořadí) do cíle |
| departure | (ISO-8601) Čas odjezdu v místním čase, např. ?departure=2025-01-01T00:00:00.000. Při neuvedení se plánuje „nyní“. Čas odjezdu má vliv na časově platné uzavírky a omezení. |
Návratové hodnoty
| length | Délka trasy v metrech |
| duration | Odhadovaný čas na průjezd/průchod ve vteřinách |
| geometry | Geometrie trasy vhodná pro vykreslení do mapy (ve zvoleném formátu) |
| parts | (pole) Jednotlivé části trasy mezi waypointy (obsahují length a duration úseku) |
| routePoints | (pole) Detailní data o startu, cíly a průjezdních bodech. originalPosition, mappedPosition a snapDistance popisují posun vstupního bodu na routovací síť služby. restricted = true říká, že bod leží v oblasti, kam by se běžně neplánovalo, ale trasa tam byla přesto spočítána kvůli vynucení tohoto bodu uživatelem jako start, cíl nebo waypoint. V restrictionType je pak naznačen důvod. Možné hodnoty: – NO_ENTRY — Zákaz vjezdu/vstupu – RESTRICTED_ENTRY — Omezený vjezd/vstup (např. nutné povolení, zaplacení) – PEDESTRIAN_ZONE — Pěší zóna – CLOSURE — Dočasná uzavírka – OTHER_RESTRICTION — Jiné dopravní nebo plánovací omezení |
Funkce Maticové plánování
Funkce slouží k plánování mezi více body naráz. Typický scénář je například to, který z 20 taxíků to má nejblíže/nejrychleji ke klientovi. Obecně funkce naplánuje mezi N starty a M cíli. Pro každou trasu vrátíme délku a čas (nikoliv geometrii – pro získání geometrie je pak potřeba zavolat funkci plánování).
Počet startů x počet cílů může být maximálně 100. Je možné tedy plánovat například 10×10, 1×100, 50×2 apod.
Cena za volání maticového plánování je fixní – za jedno volání funkce. Nezávisí na počtu využitých plánování (počet stržených kreditů je stejný za dotaz 50×2 i 12×1). Konkrétní cenu/počet kreditů najdete na stránce cena.
Vstupní parametry
| starts | Pole souřadnic startů |
| ends | Pole souřadnic cílů – nepovinné, když není uvedeno, plánuje se NxN mezi starty |
| routeType | Typ plánování – více v kapitole Typ plánování |
| lang | Preferovaný jazyk – na tuto funkci nemá vliv |
| avoidToll | Vyhnout se placeným úsekům |
Návratové hodnoty
Funkce vrací matici (dvojrozměrné pole). Řádky tvoří jednotlivé startovní body a sloupečky jednotlivé cílové body.
starts: A,B,C
ends: X,Y,Z
matrix: [
[AX AY AZ]
[BX BY BZ]
[CX CY CZ]
]starts: A,B,C
(výsledky AA,BB,CC jsou nulové)
matrix: [
[AA AB AC]
[BA BB BC]
[CA CB CC]
]Pro každý záznam pak vrátí:
| length | Délka trasy v metrech |
| duration | Odhadovaný čas na průjezd/průchod ve vteřinách |
Pro podrobnější popis vstupních a výstupních parametrů, chybových stavů apod. se podívejte do Technické dokumentace.
Typ plánování
Plánování podporuje různé typy plánování, podle kterých optimalizuje navrženou trasu:
- autem – rychlá – hledá rychlou trasu autem
- autem – rychlá – s dopravou – hledá rychlou trasu autem s přihlédnutím k aktuální dopravní situaci, zácpám apod. (pouze v ČR, mimo ČR bez přihlédnutí k dopravě)
- autem – krátká – hledá krátkou trasu autem
- pěšky – rychlá – hledá rychlou trasu pěšky
- pěšky – turistická – hledá trasu pěšky s preferencí turistických tras
- kolo – silniční – hledá trasu pro silniční kola, s asfaltovým povrchem, preferuje cyklostezky a cyklotrasy
- kolo – horské – hledá trasu pro horská kola, preferuje cyklostezky a cyklotrasy bez ohledu na povrch (pozn. na Mapy.com po změně názvů tomuto typu plánování odpovídá Cykloturistika)