Bevezetés

a Distance Matrix API olyan szolgáltatás, amely utazási távolságot és időt biztosít az eredet és célállomások mátrixának. Az API a Google Maps API által kiszámított kezdő és végpontok közötti Ajánlott útvonal alapján adja vissza az információkat, és sorokból áll, amelyek duration és distance értékeket tartalmaznak minden párra.

Megjegyzés: Ez a szolgáltatás nem ad vissza részletes útvonaladatokat. Az útvonalinformációk úgy szerezhetők be, hogy a kívánt egy Origót és célállomást átadják a Directions API-nak.

Mielőtt elkezdené

Ez a dokumentum azoknak a fejlesztőknek szól, akik a Google Maps API-k egyikében megadott térképeken belüli pontok közötti utazási távolságot és időt szeretnék kiszámítani. Bemutatja az API és a referenciaanyag használatát a rendelkezésre álló paramétereken.

mielőtt elkezdené a fejlesztést a Distance Matrix API-val, tekintse át a hitelesítési követelményeket (API kulcsra van szüksége), valamint az API használati és számlázási információkat (engedélyeznie kell a projekt számlázását).

Distance Matrix requests

a Distance Matrix API request a következő formában jelenik meg:

ahol outputFormat lehet A következő értékek egyike:

• json (ajánlott), kimenet JavaScript objektum jelölésben (JSON); vagy
• xml, XML-ként jelzi a kimenetet.

Megjegyzés: Az URL-eket megfelelően kell kódolni az érvényességhez, és az összes webszolgáltatáshoz 8192 karakterre kell korlátozni. Legyen tudatában ennek a korlátnak az URL-ek létrehozásakor. Vegye figyelembe, hogy a különböző böngészők, proxyk és szerverek különböző URL-karakterhatárokkal is rendelkezhetnek.

HTTPS vagy HTTP

a biztonság fontos, és a HTTPS ajánlott, amikor csak lehetséges, különösen olyan alkalmazásokhoz, amelyek érzékeny felhasználói adatokat tartalmaznak, például a felhasználó helyét, kérésekben. A HTTPS titkosítás használata biztonságosabbá teszi az alkalmazást, és ellenállóbbá teszi a bepillantást vagy a manipulációt.

ha HTTPS nem lehetséges, a Distance Matrix API HTTP-n keresztüli eléréséhez használja:

Request parameters

bizonyos paraméterek szükségesek, míg mások opcionálisak. Mint az URL-ekben szokásos, az összes paramétert az ampersand (&) karakter segítségével választjuk el. Minden fenntartott karakternek (például a ” + ” pluszjelnek) URL-kódolottnak kell lennie.A paraméterek listáját és azok lehetséges értékeit az alábbiakban soroljuk fel.

szükséges paraméterek

• origins — az utazási távolság és idő kiszámításának kiindulópontja. Megadhat egy vagy több, a pipe karakterrel elválasztott helyet (|), helyazonosító, cím vagy szélességi/hosszúsági koordináták formájában:
  • ha helyazonosítót ad meg, akkor előtagja a place_id:. Csak akkor adhat meg helyazonosítót, ha a kérés tartalmaz egy API kulcsot vagy egy Google Maps platform Premium Plan kliens azonosítót. A Helyazonosítók lekérhetők a Geocoding API-ból és a Helyek API-ból (beleértve a hely automatikus kiegészítését is). Ha például helyazonosítókat használ a hely automatikus kiegészítéséből, lásd: hely automatikus kiegészítése és utasítások. A helyazonosítókkal kapcsolatos további információkért lásd a helyazonosító áttekintést.
  • ha átad egy címet, a szolgáltatás geokódolja a karakterláncot, majd átalakítja azt szélességi / hosszúsági koordinátára a távolság kiszámításához. Ez a koordináta eltérhet a Geocoding API által visszaküldött koordinátától, például az épület bejárata, nem pedig a központja.

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

    megjegyzés: a helyazonosítók használata előnyben részesítendő a címek vagy a szélesség/hosszúság koordináták használata esetén. A koordináták használata mindig azt eredményezi, hogy a pontot a koordinátákhoz legközelebb eső útra törik-ami nem lehet hozzáférési pont az ingatlanhoz, vagy akár olyan út, amely gyorsan vagy biztonságosan vezet a rendeltetési helyhez.
  • ha átadja a szélességi / hosszúsági koordinátákat, akkor a legközelebbi útra pattannak. Előnyben részesítjük a helyazonosító átadását. Ha átmegy a koordinátákon, győződjön meg arról, hogy nincs tér a szélességi és hosszúsági értékek között.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • Plus kódokat globális kódként vagy összetett kódként kell formázni. Format Plus kódok itt látható (plusz jelek url-szökött %2Bés terek url-szökött %20):
    • globális kód egy 4 karakter körzetszám és 6 karakter vagy hosszabb helyi kód (849VCWC8+R9 ).
    • összetett kód egy 6 karakteres vagy hosszabb helyi kód explicit helyen (Cwc8 + R9 Mountain View, CA, USA is CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Alternatív megoldásként kódolt koordinátakészletet is megadhat a kódolt vonallánc algoritmus segítségével. Ez különösen akkor hasznos, ha nagyszámú származási ponttal rendelkezik, mivel az URL lényegesen rövidebb kódolt vonallánc használatakor.
    • a kódolt polilinokat enc: előtaggal kell előtagozni, majd ezt egy kettőspont követi (:).Például: origins=enc:gfo}EtohhU:
    • több kódolt polilint is tartalmazhat, amelyeket a cső karakter választ el (|). Például: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — egy vagy több helyen kell használni, mint a befejező pont kiszámításához utazási távolság és idő. A destinations paraméter beállításai megegyeznek a fent leírt origins paraméterrel.
• key — az alkalmazás API kulcsa. Ez a kulcs azonosítja az Ön kérelmét a kvóta kezelése céljából. Ismerje meg, hogyan kap egy kulcsot.

  Megjegyzés: A Google Maps Platform Premium Plan ügyfelei használhatnak API-kulcsot, vagy érvényes ügyfél-azonosítót és digitális aláírást a Távolságmátrix-kérésekben. További információ a prémium terv ügyfelek hitelesítési paramétereiről.

a következő példa szélességi/hosszúsági koordinátákat használ a rendeltetési koordináták megadásához:

a következő példa plusz kódokat használ a rendeltetési koordináták megadásához:

a következő példa ugyanazt a kérést mutatja kódolt vonallal:

opcionális paraméterek

• mode (alapértelmezés szerint driving) — meghatározza a távolság kiszámításakor használni kívánt szállítási módot. Az érvényes értékeket és a kérelem egyéb részleteit a dokumentum utazási módok részében találja.
• language — az eredmények visszaküldésének nyelve.
  • lásd a támogatott nyelvek listáját. A Google gyakran frissíti a támogatott nyelveket,így ez a lista nem feltétlenül teljes.
  • Ha language nincs megadva, az API megpróbálja használni a kívánt nyelvet a Accept-Language fejlécben vagy annak a tartománynak az anyanyelvén, ahonnan a kérelmet elküldték.
  • az API mindent megtesz annak érdekében, hogy olyan utcacímet biztosítson, amely mind a felhasználó, mind a helyiek számára olvasható. E cél elérése érdekében az utcacímeket a helyi nyelven adja vissza, szükség esetén a felhasználó által olvasható szkriptre átírva, az előnyben részesített nyelv figyelembevételével. Az összes többi cím a kívánt nyelven kerül visszaadásra. A címkomponensek mindegyike ugyanazon a nyelven kerül visszaadásra, amelyet az első komponensből választanak ki.
  • ha egy név nem érhető el a kívánt nyelven, az API a legközelebbi egyezést használja.
  • az előnyben részesített nyelv kis mértékben befolyásolja az API által visszaküldött eredmények halmazát, valamint a visszaküldés sorrendjét. A geocoder a rövidítéseket a nyelvtől függően eltérően értelmezi, például az utcai típusok rövidítéseit, vagy olyan szinonimákat, amelyek egy nyelven érvényesek lehetnek, de nem egy másikban. Például az utca és a tér a Magyar utca szinonimái.
• region-a ccTLD (országkód felső szintű tartomány) két karakteres értékként megadott régiókód. A legtöbb ccTLD kód megegyezik az ISO 3166-1 kódokkal, néhány kivétellel. Ez a paraméter csak a geocoder eredményeit befolyásolja, nem teljesen korlátozza. Ha relevánsabb eredmények léteznek a megadott régión kívül, akkor ezeket fel lehet venni.
• avoid — korlátozásokat vezet be az útvonalon. Az érvényes értékeket a dokumentum korlátozások szakasza határozza meg. Csak egy korlátozás adható meg.
• units — megadja a távolság szöveges kifejezésekor használni kívánt egységrendszert. További információkért lásd a dokumentum egységrendszerek szakaszát.
• arrival_time – megadja a tranzitkérelmek érkezésének kívánt idejét, 1970. január 1-je óta éjféltől másodpercben. Megadhatja a departure_time vagy arrival_time, de nem mindkettőt. Vegye figyelembe, hogyarrival_time egész számként kell megadni.
• departure_time — a kívánt indulási idő. Megadhatja az időt egész számként másodpercben éjfél óta, január 1, 1970 UTC. Ha a departure_time később, mint 9999-12-31T23:59:59.9999999999 Z van megadva, az API visszaesik a departure_time 9999-12-31T23:59:59.99999999999999999 Z. Alternatív megoldásként megadhat egy értéket a now, amely beállítja az indulási idő az aktuális idő (helyes a legközelebbi második). Az indulási idő két esetben adható meg:
  • azon kérések esetében, ahol az utazási mód tranzit: Opcionálisan megadhatja a departure_time vagy arrival_timeegyikét. Ha nincs megadva idő, akkor adeparture_time alapértelmezés szerint most (azaz az indulási idő alapértelmezés szerint az aktuális idő).
  • olyan kérések esetén, ahol az utazási mód vezet: megadhatja a departure_time útvonalat és az utazás időtartamát (válasz mező: duration_in_traffic), amelyek figyelembe veszik a forgalmi feltételeket. Ez a beállítás csak akkor érhető el, ha a kérelem érvényes API kulcsot vagy érvényes Google Maps Platform Premium Plan kliens azonosítót és aláírást tartalmaz. A departure_time értéket az aktuális időre vagy a jövőben egy bizonyos időre kell beállítani. Nem lehet a múltban.

    Megjegyzés: Ha az indulási idő nincs megadva, az útvonal és az időtartam megválasztása az úthálózaton és az átlagos időtől független forgalmi feltételeken alapul. Egy adott kérelem eredményei idővel változhatnak az úthálózat változásai, a frissített átlagos forgalmi Feltételek, valamint a szolgáltatás elosztott jellege miatt. Az eredmények a Közel egyenértékű útvonalak között is változhatnak bármikor vagy gyakorisággal.

    Megjegyzés: A departure_time amikor mode=driving kérésre legfeljebb 100 elemre korlátozódik. A származási helyek száma a rendeltetési helyek száma határozza meg az elemek számát.

• traffic_model (alapértelmezés szerint best_guess) — meghatározza azokat a feltételezéseket, amelyeket a forgalmi idő kiszámításakor használni kell. Ez a beállítás befolyásolja a duration_in_traffic mezőben visszaadott értéket a válaszban, amely a forgalom előre jelzett idejét tartalmazza a történelmi átlagok alapján. Atraffic_model paraméter csak olyan kérésekre adható meg, ahol az utazási móddriving, és ahol a kérés tartalmaz egydeparture_time, és csak akkor, ha a kérés tartalmaz API kulcsot vagy egy Google Maps platform Premium Plan kliens azonosítót. Ennek a paraméternek a rendelkezésre álló értékei a következők:
  • best_guess(alapértelmezett) azt jelzi, hogy a visszaküldött duration_in_traffic legyen az utazási idő legjobb becslése, figyelembe véve mind a történelmi forgalmi feltételeket, mind az élő forgalmat. Az élő forgalom egyre fontosabbá válik, minél közelebb van a departure_time.
  • pessimistic azt jelzi, hogy a visszaküldött duration_in_traffic hosszabbnak kell lennie, mint a tényleges utazási idő a legtöbb napon, bár a különösen rossz forgalmi feltételekkel járó alkalmi napok meghaladhatják ezt az értéket.
  • optimisticazt jelzi, hogy a visszaküldött duration_in_traffic rövidebbnek kell lennie, mint a tényleges utazási idő a legtöbb napon, bár a különösen jó forgalmi feltételekkel rendelkező alkalmi napok gyorsabbak lehetnek, mint ez az érték.
• transit_mode — egy vagy több preferált szállítási módot határoz meg. Ez a paraméter csak akkor adható meg, ha a modetransit. A paraméter a következő érveket támogatja:
  • bus azt jelzi, hogy a számított útvonalnak inkább busszal kell utaznia.
  • subway azt jelzi, hogy a számított útvonalnak inkább metróval kell utaznia.
  • train azt jelzi, hogy a számított útvonalnak inkább vonattal kell utaznia.
  • tram azt jelzi, hogy a számított útvonalnak inkább villamossal és könnyűvasúttal kell utaznia.
  • rail azt jelzi, hogy a számított útvonalnak inkább vonattal, villamossal, könnyűvasúttal és metróval kell utaznia. Ez egyenértékű a transit_mode=train|tram|subwayértékkel.
• transit_routing_preference — megadja a tranzitkérelmek beállításait. Ezzel a paraméterrel torzíthatja a visszaküldött opciókat, ahelyett, hogy elfogadná az API által választott alapértelmezett legjobb útvonalat. Ez a paraméter csak akkor adható meg, ha a modetransit. A paraméter a következő érveket támogatja:
  • less_walking azt jelzi, hogy a számított útvonalnak korlátozott mennyiségű járást kell előnyben részesítenie.
  • fewer_transfers azt jelzi, hogy a számított útvonalnak korlátozott számú transzfert kell előnyben részesítenie.

utazási módok

a távolságok kiszámításához megadhatja a mode használatát. Alapértelmezés szerint a távolságokat vezetési módra számítják ki. A következő utazási módok támogatottak:

• driving (alapértelmezett) a távolság kiszámítását jelzi az úthálózat használatával.
• walkingtávolságszámítást kér a gyalogos utakon való gyalogláshoz & járdák (ahol rendelkezésre állnak).
• bicyclingtávolságszámítás kérése kerékpárutakon keresztüli kerékpározáshoz & preferált utcák (ahol elérhető).
• transit távolságszámítás kérése tömegközlekedési útvonalakon keresztül (ahol elérhető). Ezt az értéket csak akkor lehet megadni, ha a kérés tartalmaz egy API kulcsot vagy egy Google Maps platform Premium Plan kliens azonosítót. Ha az üzemmódot transit értékre állítja, opcionálisan megadhatja a departure_time vagy egy arrival_timeértéket. Ha nincs megadva idő, akkor adeparture_time alapértelmezés szerint most (azaz az indulási idő alapértelmezés szerint az aktuális idő). Opcionálisan tartalmazhat egy transit_mode és/vagy egy transit_routing_preference.

Forgalmi adatok

a Forgalmi információk használni, ha a következő alkalmazni (ezek a szükséges feltételeket ahhoz, hogy megkapja a duration_in_traffic mező a Távolság Mátrix válasz):

• Az utazási mode paraméter driving, vagy nem meghatározott (driving az alapértelmezett utazási mód).
• a kérés tartalmaz egy érvényes departure_time paramétert. A departure_time beállítható az aktuális időre vagy egy időre a jövőben. Nem lehet a múltban.

opcionálisan a traffic_model paramétert is megadhatja a kérésében, hogy meghatározza a forgalmi idő kiszámításakor használni kívánt feltételezéseket.

A következő URL távolsági mátrix kérést kezdeményez Boston, MA vagy Charlestown, MA és Lexington, MA és Concord, MA közötti távolságokra. A kérés tartalmaz egy indulási időt, amely megfelel a duration_in_traffic mező visszatéréséhez a Távolságmátrix válaszában.

korlátozások

olyan távolságok számíthatók ki, amelyek betartanak bizonyos korlátozásokat. A korlátozásokat a avoid paraméter használatával, valamint az elkerülendő korlátozást jelző paraméter argumentumával jelzik. A következő korlátozások használhatók:

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

* Megjegyzés: ezen korlátozás nem zárja ki, hogy útvonalak, amelyek magukban foglalják a korlátozott funkció; ez a torzítás az eredmény kedvezőbb útvonalak.

Unit systems

Distance Matrix results contained text within distance fields to indicate the distance of the calculated route. A használni kívánt egységrendszer megadható:

• units=metric (alapértelmezett) kilométerben és méterben adja vissza a távolságokat.
• units=imperial kilométerben és méterben adja vissza a távolságokat.

* Megjegyzés: Ez az egységrendszer beállítás csak atextdistance mezőkön belül jelenik meg. Adistance mezők tartalmazzák avalues mezőket is, amelyek mindig méterben vannak kifejezve.

Távolságmátrix válaszok

a Távolságmátrix API lekérdezésekre adott válaszok a output zászló által jelzett formátumban kerülnek vissza az URL kérés elérési útján.

Két minta HTTP kérések alább látható, kérve távolság, valamint időtartama a Vancouver, BC, Canada, majd Seattle, WA, USA, San Francisco, CA, USA, Victoria, BC, Kanada.

Ez a kérés a JSON output zászló használatát mutatja:

Ez a kérelem bizonyítja, használja az XML output zászló:

Ez a kérés vissza a négy elem – két eredete alkalommal két cél:

Eredmények visszatért a sorok, minden sor, amely egy eredetű párosítva minden hely.

ezt tesztelheti úgy, hogy beírja az URL-t a böngészőjébe (feltétlenül cserélje ki a YOUR_API_KEY – t a tényleges API-kulcsával).

válassza ki az alábbi lapokat a minta JSON és XML-válaszok megtekintéséhez.

a dokumentáció fennmaradó része a JSON szintaxist fogja használni.

távolság mátrix válasz elemek

távolság mátrix válaszok tartalmazzák a következő gyökér elemek:

• status metaadatokat tartalmaz a kérésre. Lásd az alábbi állapotkódokat.
• origin_addresses az API által az eredeti kérésből visszaküldött címek tömbjét tartalmazza. Ezeket a geocoder formázza, és a language paraméter szerint lokalizálódik.
• destination_addresses az API által az eredeti kérésből visszaküldött címsorokat tartalmazza. Mint a origin_addresses, ezek adott esetben lokalizálódnak.
• rowselements tömböt tartalmaz, amelyek viszont tartalmaznak egy status és distance elem.

állapotkódok

astatus mezők a válaszobjektumon belül tartalmazzák a kérés állapotát, és hasznos hibakeresési információkat tartalmazhatnak. A Distance Matrix API egy felső szintű állapotmezőt ad vissza, általában a kéréssel kapcsolatos információkkal, valamint az egyes elemmezők állapotmezőjével, az adott origin-destination párosítással kapcsolatos információkkal.

felső szintű állapotkódok

• OK jelzi, hogy a válasz érvényes result.
• INVALID_REQUEST jelzi, hogy a megadott kérés érvénytelen volt.
• MAX_ELEMENTS_EXCEEDED azt jelzi, hogy az eredet és a rendeltetési hely terméke meghaladja a lekérdezésenkénti határértéket.
• MAX_DIMENSIONS_EXCEEDED azt jelzi, hogy az eredetek vagy rendeltetési helyek száma meghaladja a lekérdezésenkénti határértéket.
• OVER_DAILY_LIMIT a következők bármelyikét jelzi:
  • az API kulcs hiányzik vagy érvénytelen.
  • a számlázás nincs engedélyezve a fiókjában.
  • túllépték az önkorlátozó Használati korlátozást.
  • a megadott fizetési mód már nem érvényes (például egy hitelkártya lejárt).

  lásd a térképek GYIK, hogy megtanulják, hogyan kell kijavítani ezt.

• OVER_QUERY_LIMIT jelzi, hogy a szolgáltatás túl sok kérést kapott az alkalmazástól a megengedett időtartamon belül.
• REQUEST_DENIED azt jelzi, hogy a szolgáltatás megtagadta a Távolságmátrix szolgáltatás használatát az alkalmazás által.
• UNKNOWN_ERROR azt jelzi, hogy a Távolságmátrix kérés nem dolgozható fel szerverhiba miatt. A kérés sikeres lehet, ha újra megpróbálja.

elem szintű állapotkódok

• OK jelzi, hogy a válasz érvényes result.
• NOT_FOUND azt jelzi, hogy a párosítás eredetét és/vagy rendeltetési helyét nem lehetett geokódolni.
• ZERO_RESULTS azt jelzi, hogy a származási hely és a rendeltetési hely között nem található útvonal.
• MAX_ROUTE_LENGTH_EXCEEDED jelzi, hogy a kért útvonal túl hosszú és nem dolgozható fel.

hibaüzenetek

Ha a felső szintű állapotkód eltér a OK – tól, akkor lehet egy továbbierror_message mező a Távolságmátrix válasz objektumán belül. Ez a mező tartalmazza részletesebb információkat az adott állapotkód mögötti okokról.

Megjegyzés: Ez a mező nem garantált, hogy mindig jelen van, és a tartalma változhat.

sorok

amikor a Distance Matrix API eredményeket ad vissza, azokat egy JSON rows tömbbe helyezi. Még akkor is, ha nincs eredmény (például ha az eredet és/vagy a célállomások nem léteznek), akkor is üres tömböt ad vissza. Az XML válaszok nulla vagy több<row> elemből állnak.

A sorok a origin paraméter értékei szerint vannak megrendelve. Minden sor egy származásnak felel meg, és minden element azon a soron belül megfelel az eredet destination értékkel történő párosításának.

minden row tömb tartalmaz egy vagy több element bejegyzéseket, amelyek viszont tartalmazzák az információkat egyetlen származási hely párosítás.

Elements

az egyes origin-destination párosításokra vonatkozó információkat element bejegyzésben adjuk vissza. An element a következő mezőket tartalmazza:

• status: a lehetséges állapotkódok listájához lásd az állapotkódokat.
• duration: a menetidő hossza, másodpercben kifejezve (a value mező) és a text. A szöveges ábrázolás a lekérdezés language paramétere szerint lokalizálódik.

• duration_in_traffic: az útvonal utazásához szükséges idő hossza a jelenlegi és a korábbi forgalmi viszonyok alapján. Lásd atraffic_model request paramétert az opciókhoz, amelyekkel kérheti, hogy a visszaküldött érték optimista, pesszimista vagy a legjobb becslés. Az időtartam másodpercben (a value mező) és text. A szöveges ábrázolás a lekérdezés language paramétere szerint lokalizálódik. A forgalom időtartama csak akkor tér vissza, ha az alábbiak mindegyike igaz:

  • a kérés tartalmaz egy departure_time paramétert.
  • a kérelem érvényes API kulcsot vagy érvényes Google Maps Platform Premium Plan kliens azonosítót és aláírást tartalmaz.
  • forgalmi feltételek állnak rendelkezésre a kért útvonalon.
  • a modeparaméter értékedriving.
• distance: az útvonal teljes távolsága méterben kifejezve (value) és text. A szöveges érték az eredeti kérés unit paraméterével, vagy az origin régiójával megadott egységrendszert használja.
• fare: ha van, tartalmazza a teljes viteldíjat (azaz a teljes jegyköltséget) ezen az útvonalon. Ezt a tulajdonságot csak tranzitkérelmek esetén adják vissza, és csak olyan tranzitszolgáltatóknak, ahol a viteldíjra vonatkozó információk rendelkezésre állnak. Az információ a következőket tartalmazza:
  • currency: ISO 4217 pénznemkód, amely jelzi az összeg pénznemét.
  • value: A viteldíj teljes összege a fent meghatározott pénznemben.
  • text: a teljes viteldíj összege, a kért nyelven formázva.

Az alábbiakban egy példa egy element tartalmazó viteldíj információ:

az érzékelő paraméter

a Google Maps API korábban szükséges, hogy tartalmazza asensor paraméter jelzi, hogy az alkalmazás használt asensor meghatározni a felhasználó helyét. Ez a paraméter már nemszükséges.