Úvod

rozhraní Distance Matrix API je služba, která poskytuje vzdálenost a čas cesty pro matici původu a destinací. API vrátí informace na základě doporučené trasy mezi počáteční a koncové body, které jsou vypočteny podle Google Maps API, a skládá se z řádků, obsahující durationdistance hodnoty pro každý pár.

Poznámka: Tato služba nevrací podrobné informace o trase. Informace o trase lze získat předáním požadovaného jediného původu a cíle do rozhraní Directions API.

než začnete

tento dokument je určen pro vývojáře, kteří chtějí vypočítat cestovní vzdálenost a čas mezi počtem bodů v Mapách poskytovaných jedním z API Map Google. Poskytuje úvod do používání API a referenčního materiálu o dostupných parametrech.

než začnete vyvíjet rozhraní Distance Matrix API, přečtěte si požadavky na autentizaci (potřebujete klíč API) a informace o použití a fakturaci API (musíte povolit fakturaci ve vašem projektu).

Matice Vzdáleností žádosti

Distance Matrix API request má následující podobu:

kde outputFormat může být jedna z následujících hodnot:

• json (doporučeno), označuje výstup v JavaScript Object Notation (JSON); nebo
• xml, označuje výstup ve formátu XML.

Poznámka: adresy Url musí být správně zakódovány, aby byly platné a jsou omezeny na 8192 znaků pro všechny webové služby. Při vytváření adres URL si uvědomte tento limit. Všimněte si, že různé prohlížeče, servery proxy a servery mohou mít také různá omezení znaků URL.

HTTPS nebo HTTP

bezpečnost je důležitá a HTTPS se doporučuje, kdykoli je to možné, zejména pro aplikace, které v požadavcích obsahují citlivá uživatelská data, například polohu uživatele. Pomocí šifrování HTTPS je vaše aplikace bezpečnější a odolnější vůči snoopingu nebo manipulaci.

Pokud HTTPS není možný, pro přístup k rozhraní Distance Matrix API přes HTTP použijte:

parametry požadavku

některé parametry jsou vyžadovány, zatímco jiné jsou volitelné. Jak je u adres URL obvyklé, všechny parametry jsou odděleny znakem ampersand (&). Všechny vyhrazené znaky (například znaménko plus“+“) musí být kódovány URL.Seznam parametrů a jejich možné hodnoty jsou uvedeny níže.

Požadované parametry

• origins — výchozí bod pro výpočet cestovní vzdálenosti a času. Můžete zadat jeden nebo více místech odděleny svislítkem (|), v podobě místa ID, adresy, nebo zeměpisné šířky/délky souřadnice:
  • Pokud se vám nabídka místo ID, musí předpony s place_id:. ID místa můžete zadat pouze v případě, že požadavek obsahuje klíč API nebo ID klienta Prémiového plánu Google Maps Platform. ID místa můžete načíst z Geokódovacího API a API míst (včetně automatického doplňování místa). Příklad použití ID místa z automatického doplňování místa, viz Automatické doplňování místa a pokyny. Další informace o ID místa naleznete v přehledu ID místa.
  • Pokud předáte adresu, služba geokóduje řetězec a převede jej na souřadnici zeměpisné šířky a délky pro výpočet vzdálenosti. Tato souřadnice se může lišit od souřadnic vrácených GEOKÓDOVÁNÍM API, například vchod do budovy spíše než jeho střed.

    origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON

    Poznámka: použití ID místa je upřednostňováno před použitím adres nebo souřadnic zeměpisné šířky a délky. Pomocí souřadnic bude vždy výsledek, a to v bodě, že prasklo na cestě nejbližší na ty souřadnice – což nemusí být přístupový bod k nemovitosti, nebo i silnice, která bude rychle a bezpečně dovést k cíli.
  • pokud míjíte souřadnice zeměpisné šířky a délky, přichytí se k nejbližší silnici. Předání ID místa je upřednostňováno. Pokud předáte souřadnice, ujistěte se, že mezi hodnotami zeměpisné šířky a délky není mezera.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • Plus kódy musí být formátován jako globální kód nebo složený kód. Formát plus kódy, jak je znázorněno zde (plus známky jsou url-utekl do %2B a prostory jsou url-utekl do %20):
    • globální kód je 4 znaků předčíslí a 6 znaků nebo déle místní kód (849VCWC8+R9 je 849VCWC8%2BR9).
    • složené kód je 6 znaků nebo déle místní kód s explicitním umístění (CWC8+R9 Mountain View, CA, USA je CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Alternativně můžete zadat kódovanou sadu souřadnic pomocí kódovaného algoritmu křivky. To je zvláště užitečné, pokud máte velký počet výchozích bodů, protože Adresa URL je při použití kódované křivky výrazně kratší.
    • Kódované křivek musí být s předponou enc: a následované dvojtečkou (:).Například: origins=enc:gfo}EtohhU:
    • můžete také zahrnout více kódovaných křivek, které jsou odděleny svislítkem (|). Příklad: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — Jedno nebo více míst k použití jako dokončovací bod výpočtu cestovní vzdálenosti a času. Možnosti pro parametr destinations jsou stejné jako pro parametr origins, popsaný výše.
• key – klíč API vaší aplikace. Tento klíč identifikuje vaši žádost pro účely správy kvót. Naučte se, jak získat klíč.

  Poznámka: Zákazníci služby Google Maps Platform Premium Plan mohou ve vašich požadavcích na matici vzdálenosti používat buď klíč API, nebo platné ID klienta a digitální podpis. Získejte více informací o parametrech ověřování pro zákazníky Premium Plan.

následující příklad používá zeměpisné šířky/délky souřadnic, určete souřadnice určení:

následující příklad používá plus kódy zadat cílové souřadnice:

následující příklad ukazuje stejný požadavek pomocí kódované křivku:

Volitelné parametry

• mode (výchozí hodnota je driving) — Určuje způsob dopravy použít při výpočtu vzdálenosti. Platné hodnoty a další podrobnosti požadavku jsou uvedeny v části cestovní režimy tohoto dokumentu.
• language – jazyk, ve kterém se mají vrátit výsledky.
  • viz seznam podporovaných jazyků. Google často aktualizuje Podporované jazyky, takže tento seznam nemusí být vyčerpávající.
  • Pokud language není dodáván, API se pokusí použít preferovaný jazyk, jak je uvedeno v Accept-Language záhlaví, nebo rodný jazyk domény, ze které je odeslán požadavek.
  • API se snaží poskytnout adresu ulice, která je čitelná jak pro uživatele, tak pro místní obyvatele. K dosažení tohoto cíle vrací adresy ulic v místním jazyce, přepsané do skriptu čitelného uživatelem, pokud je to nutné, při dodržení preferovaného jazyka. Všechny ostatní adresy jsou vráceny v preferovaném jazyce. Komponenty adresy jsou vráceny ve stejném jazyce, který je vybrán z první komponenty.
  • pokud název není k dispozici v preferovaném jazyce, API používá nejbližší shodu.
  • preferovaný jazyk má malý vliv na sadu výsledků, které se API rozhodne vrátit, a pořadí, ve kterém jsou vráceny. Geokodér interpretuje zkratky různě v závislosti na jazyce, jako jsou zkratky pro typy ulic, nebo synonyma, která mohou být platná v jednom jazyce, ale ne v jiném jazyce. Například utca a tér jsou synonyma pro ulici v maďarštině.
• region — kód regionu, je uvedeno jako ccTLD (country code top-level domain) dvou znaků hodnotu. Většina kódů ccTLD je s některými výjimkami shodná s kódy ISO 3166-1. Tento parametr bude mít vliv pouze na výsledky geokoderu, nikoli na jeho úplné omezení. Pokud existují relevantnější výsledky mimo určenou oblast, mohou být zahrnuty.
• avoid – zavádí omezení trasy. Platné hodnoty jsou uvedeny v části omezení tohoto dokumentu. Lze zadat pouze jedno omezení.
• units – určuje jednotkový systém, který se použije při vyjadřování vzdálenosti jako textu. Další informace naleznete v části jednotkové systémy tohoto dokumentu.
• arrival_time — Určuje požadovaný čas příjezdu tranzitu požaduje, v sekundách od půlnoci 1. ledna 1970 UTC. Můžete zadat buď departure_time nebo arrival_time, ale ne obojí. Všimněte si, že arrival_time musí být zadáno jako celé číslo.
• departure_time – požadovaný čas odjezdu. Čas můžete zadat jako celé číslo v sekundách od půlnoci 1. ledna 1970 UTC. Pokud departure_time později, než 9999-12-31T23:59:59.999999999 Z je uvedeno, že API bude klesat zpět departure_time 9999-12-31T23:59:59.999999999 Z. Případně, můžete zadat hodnotu now, který nastavuje čas odjezdu na aktuální čas (na nejbližší sekundu). Čas odjezdu lze specifikovat ve dvou případech:
  • pro žádosti, kde je režim cesty tranzitní: Volitelně můžete zadat jeden z departure_time nebo arrival_time. Pokud není zadán žádný čas, departure_time je výchozí hodnota now (tj.
  • Pro žádosti, kde cestovní režim jízda: můžete zadat departure_time získat trasy a trvání cesty (odpověď pole: duration_in_traffic), které se dopravní podmínky v úvahu. Tato možnost je k dispozici pouze v případě, že požadavek obsahuje platný klíč API nebo platné ID a podpis klienta Google Maps Platform Premium Plan. departure_time musí být nastaven na aktuální čas nebo nějaký čas v budoucnosti. Nemůže to být minulost.

    Poznámka: není-li stanoven čas odjezdu, je volba trasy a doby trvání založena na silniční síti a průměrných provozních podmínkách nezávislých na čase. Výsledky pro danou žádost se mohou v průběhu času lišit v důsledku změn v silniční síti, aktualizovaných průměrných dopravních podmínek a distribuované povahy služby. Výsledky se mohou také lišit mezi téměř ekvivalentními trasami kdykoli nebo s frekvencí.

    Poznámka: Matice Vzdáleností požadavků zadání departure_timemode=driving jsou omezeny na maximálně 100 elementy na vyžádání. Počet původů krát počet destinací definuje počet prvků.

• traffic_model (výchozí hodnota je best_guess) — Určuje předpoklady pro použití při výpočtu času v provozu. Toto nastavení ovlivňuje hodnotu vrácenou v poli duration_in_traffic v odpovědi, které obsahuje předpokládaný čas v provozu na základě historických průměrů. traffic_model parametr může být zadán pouze pro žádosti, kde cestovním režimu je driving, a, pokud žádost obsahuje departure_time, a pouze tehdy, pokud žádost obsahuje API klíč nebo Platformě Google Maps Plán Premium ID klienta. Dostupné hodnoty pro tento parametr jsou:
  • best_guess (výchozí) označuje, že se vrátil duration_in_traffic by měl být nejlepší odhad cestovní čas vzhledem k tomu, co je známo o historické dopravní podmínky a live traffic. Živý přenos se stává důležitějším, čím blíže je departure_time.
  • pessimistic označuje, že se vrátil duration_in_traffic by měl být delší než skutečná doba cestování na většinu dní, i když občas dní s obzvláště špatné dopravní podmínky mohou tuto hodnotu překročit.
  • optimistic označuje, že se vrátil duration_in_traffic by měla být kratší, než je skutečná cestovní doba na většinu dní, i když občas dní s obzvláště dobrou dopravní podmínky mohou být rychlejší, než tato hodnota.
• transit_mode – určuje jeden nebo více preferovaných způsobů tranzitu. Tento parametr lze zadat pouze pro požadavky, kde mode je transit. Parametr podporuje následující argumenty:
  • bus označuje, že vypočtená trasa by měla přednost cestování autobusem.
  • subway znamená, že vypočtená trasa by měla upřednostňovat cestování metrem.
  • train znamená, že vypočtená trasa by měla upřednostňovat cestování vlakem.
  • tram označuje, že vypočtená trasa by měla přednost cestování do tramvaje a light rail.
  • rail označuje, že vypočtená trasa by měla přednost cestování vlakem, tramvají, železnice a metra. To odpovídá transit_mode=train|tram|subway.
• transit_routing_preference – určuje předvolby pro tranzitní požadavky. Pomocí tohoto parametru, můžete zkreslit vrácené možnosti, spíše než přijmout výchozí nejlepší trasu vybranou API. Tento parametr lze zadat pouze pro požadavky, kde mode je transit. Parametr podporuje následující argumenty:
  • less_walking označuje, že vypočtená trasa by měla přednost omezené množství chůze.
  • fewer_transfers znamená, že vypočtená trasa by měla upřednostňovat omezený počet převodů.

Cestovní režimy

Pro výpočet vzdálenosti, můžete zadat dopravy mode použít. Ve výchozím nastavení jsou vzdálenosti vypočteny pro jízdní režim. Následující cestovní režimy jsou podporovány:

• driving (výchozí) označuje, výpočet vzdálenosti pomocí silniční sítě.
• walking požaduje výpočet vzdálenosti pro chůzi po pěších cestách & chodníky (pokud jsou k dispozici).
• bicycling žádostí výpočet vzdálenosti pro jízdu na kole přes cyklostezky & preferované ulice (pokud je k dispozici).
• transit požaduje výpočet vzdálenosti po trasách veřejné dopravy (pokud jsou k dispozici). Tuto hodnotu lze zadat pouze v případě, že požadavek obsahuje klíč API nebo ID klienta Prémiového plánu Google Maps Platform. Pokud nastavíte režim transit volitelně můžete zadat buď departure_time nebo arrival_time. Pokud není zadán žádný čas, departure_time je výchozí hodnota now (tj. Můžete také volitelně obsahovat transit_mode a/nebo transit_routing_preference.

Dopravní informace

Dopravní informace se používá, když jsou splněny všechny následující podmínky (tyto podmínky potřebné pro příjem duration_in_traffic pole ve Vzdálenosti Matrix odezva):

• cestovní mode parametr driving, nebo je neuvádějí (driving je výchozí cestovní režim).
• požadavek obsahuje platný parametr departure_timedeparture_time lze nastavit na aktuální čas nebo nějaký čas v budoucnosti. Nemůže to být minulost.

Volitelně můžete zahrnout traffic_model parametr v žádosti specifikovat předpoklady pro použití při výpočtu času v provozu.

následující adresa URL iniciuje požadavek matice vzdálenosti pro jízdní vzdálenosti mezi Bostonem, MA nebo Charlestownem, MA a Lexingtonem, MA a Concordem, MA. Požadavek obsahuje Čas odjezdu, který splňuje všechny požadavky na vrácení pole duration_in_traffic v odpovědi matice vzdálenosti.

omezení

lze vypočítat vzdálenosti, které dodržují určitá omezení. Omezení jsou označeny pomocí avoid parametr a argument, že parametr udávající omezení, aby se zabránilo. Tato omezení jsou podporovány:

• avoid=tolls
• avoid=highways
• avoid=ferries
• avoid=indoor

* Poznámka: přidáním omezení nebrání tras, které zahrnují omezené funkce; předsudky výsledek příznivější trasy.

jednotkové systémy

výsledky matice vzdálenosti obsahujítext v políchdistance pro označení vzdálenosti vypočtené trasy. Systém jednotek, který se má použít, lze zadat:

• units=metric (výchozí) vrací vzdálenosti v kilometrech a metrech.
• units=imperial vrací vzdálenosti v mílích a stopách.

* Poznámka: Toto nastavení systému jednotek ovlivňuje pouze poletext zobrazená v políchdistance. Pole distance také obsahují values, které jsou vždy vyjádřeny v metrech.

Matice Vzdáleností odpovědi

Odpovědi na Distance Matrix API dotazy jsou vráceny ve formátu indikována output vlajky v URL požadavku je cesta.

Níže jsou uvedeny dva ukázkové HTTP požadavky, které vyžadují vzdálenost a trvání z Vancouveru, BC, Kanady a ze Seattlu, WA, USA, do San Francisca, CA, USA a do Victoria, BC, Kanady.

tento požadavek demonstruje pomocí příznaku JSON output :

Tento požadavek ukazuje použití XML output flag:

Tento požadavek se vrátí čtyři prvky – dva počátky krát dva cíle:

Výsledky jsou vráceny v řadách, každý řádek obsahuje jednu původu spárován s každé místo určení.

můžete to otestovat zadáním adresy URL do webového prohlížeče (nezapomeňte nahradit YOUR_API_KEY skutečným klíčem API).

vyberte níže uvedené karty, abyste viděli ukázkové odpovědi JSON a XML.

zbytek této dokumentace bude používat syntaxi JSON.

Matice Vzdáleností reakce prvků

Matice Vzdáleností odpovědi obsahuje následující kořenové elementy:

• status obsahuje metadata na požádání. Viz stavové kódy níže.
• origin_addresses obsahuje pole adres vrácených API z vašeho původního požadavku. Ty jsou formátovány geokoderem a lokalizovány podle parametru language předaného s požadavkem.
• destination_addresses obsahuje pole adres vrácených API z vašeho původního požadavku. Stejně jako u origin_addresses Jsou tyto lokalizovány, pokud je to vhodné.
• rows obsahuje pole elements, které zase obsahují statusdurationdistance elementu.

stavové kódy

pole status v objektu odpovědi obsahují stav požadavku a mohou obsahovat užitečné informace o ladění. Rozhraní Distance Matrix API vrací stavové pole nejvyšší úrovně s informacemi o požadavku obecně, stejně jako stavové pole pro každé pole prvku, s informacemi o konkrétním párování původu a cíle.

stavové kódy nejvyšší úrovně

• OK označuje, že odpověď obsahuje platný result.
• INVALID_REQUEST označuje, že zadaný požadavek byl neplatný.
• MAX_ELEMENTS_EXCEEDED označuje, že produkt původu a místa určení překračuje limit na dotaz.
• MAX_DIMENSIONS_EXCEEDED označuje, že počet původů nebo destinací překračuje limit na dotaz.
• OVER_DAILY_LIMIT označuje některou z následujících možností:
  • klíč API chybí nebo je neplatný.
  • fakturace nebyla ve vašem účtu povolena.
  • byl překročen limit použití, který si sám uložil.
  • poskytnutý způsob platby již není platný (například vypršela platnost kreditní karty).

  podívejte se na mapy FAQ se dozvíte, jak to opravit.

• OVER_QUERY_LIMIT označuje, že služba obdržela příliš mnoho požadavků z vaší aplikace v povoleném časovém období.
• REQUEST_DENIED označuje, že služba odepřela použití Služby Distance Matrix vaší aplikací.
• UNKNOWN_ERROR označuje, že požadavek matice vzdálenosti nemohl být zpracován kvůli chybě serveru. Žádost může být úspěšná, pokud to zkusíte znovu.

Prvek-úroveň stavové kódy

• OK označuje odpověď obsahuje platný result.
• NOT_FOUND označuje, že původ a / nebo cíl tohoto párování nelze geokódovat.
• ZERO_RESULTS označuje, že mezi původem a cílem nebyla nalezena žádná trasa.
• MAX_ROUTE_LENGTH_EXCEEDED označuje, že požadovaná trasa je příliš dlouhá a nelze ji zpracovat.

Chybová hlášení

Když top-level status kód je jiný než OK, tam může být dalšíerror_message pole ve Vzdálenosti Matrix objektu odpověď. Toto pole obsahujepodrobnější informace o důvodech daného stavového kódu.

Poznámka: není zaručeno, že toto pole bude vždy přítomno a jeho obsah se může změnit.

řádky

Když rozhraní Distance Matrix API vrátí výsledky, umístí je do pole JSON rows. I když nejsou vráceny žádné výsledky (například když počátky a / nebo cíle neexistují), stále vrací prázdné pole. XML odpovědi se skládají z nulových nebo více prvků <row>.

řádky jsou seřazeny podle hodnot v parametru origin požadavku. Každý řádek odpovídá původu, a každý element v daném řádku odpovídá párování původu s destination hodnota.

Každý row array obsahuje jeden nebo více element položky, které zase obsahují informace o jediném původu-určení párování.

Elements

informace o každém párování původu a cíle jsou vráceny v položce elementelement obsahuje následující pole:

• status Viz: Stavové Kódy pro seznam možných stavových kódech.
• duration: délka čas potřebný k cestování na této trase, vyjádřený v sekundách (value pole) a jako text. Textová reprezentace je lokalizována podle parametru language dotazu.

• duration_in_traffic: doba potřebná k cestování touto trasou na základě aktuálních a historických dopravních podmínek. Podívejte se na parametrtraffic_model request pro možnosti, které můžete použít k požadavku, aby vrácená hodnota byla optimistická,pesimistická nebo nejlépe odhadnutelná. Doba trvání je vyjádřena v sekundách (pole value) a jako text. Textová reprezentace je lokalizována podle parametru language dotazu. Doba trvání provozu je vrácena pouze v případě, že jsou splněny všechny následující:

  • požadavek obsahuje parametr departure_time.
  • požadavek obsahuje platný klíč API nebo platné ID klienta Google Maps Platform Premium Plan a podpis.
  • dopravní podmínky jsou k dispozici pro požadovanou trasu.
  • parametr mode je nastaven na driving.
• distance: celková vzdálenost této trasy, vyjádřené v m (value) a text. Textová hodnota používá jednotkový systém zadaný parametrem unit původního požadavku nebo oblasti původu.
• fare: pokud je přítomen, obsahuje celkové jízdné (tj. celkové náklady na jízdenku) na této trase. Tato vlastnost je vrácena pouze pro žádosti o tranzit a pouze pro poskytovatele tranzitu, kde jsou k dispozici informace o jízdném. Informace zahrnují:
  • currency: kód měny ISO 4217 označující měnu, ve které je částka vyjádřena.
  • value: celková částka jízdného v měně uvedené výše.
  • text: celková částka jízdného formátovaná v požadovaném jazyce.

Níže je příklad element obsahující informace o jízdném:

parametr snímače

Google Maps API dříve nutné zahrnoutsensor parametr označující, zda vaše aplikace používá asensor určit polohu uživatele. Tento parametr již nenípožadováno.