Inleiding

De Distance Matrix API is een dienst die reisafstand en-tijd biedt voor een matrix van oorsprong en bestemming. De API geeft informatie terug op basis van de aanbevolen route tussen begin-en eindpunten, zoals berekend door de Google Maps API, en bestaat uit rijen met duration en distance waarden voor elk paar.

Opmerking: Deze service retourneert geen gedetailleerde routeinformatie. Route-informatie kan worden verkregen door het passeren van de gewenste enkele oorsprong en bestemming aan de routebeschrijving API.

voordat u begint

dit document is bedoeld voor ontwikkelaars die de reisafstand en-tijd willen berekenen tussen een aantal punten binnen kaarten die worden geleverd door een van de Google Maps API ‘ s. Het biedt een inleiding tot het gebruik van de API en referentiemateriaal op de beschikbare parameters.

voordat u begint met het ontwikkelen van de Distance Matrix API, controleert u de verificatievereisten (u hebt een API-sleutel nodig) en de informatie over het gebruik en de facturering van de API (u moet facturering op uw project inschakelen).

Afstand Matrix aanvragen

Een Afstand Matrix API verzoek neemt de volgende vorm:

waar outputFormat kan een van de volgende waarden:

• json (recommended) geeft output JavaScript Object Notation (JSON); of
• xml geeft aan output als XML.

opmerking: URL ‘ s moeten correct gecodeerd zijn om geldig te zijn en zijn beperkt tot 8192 tekens voor alle webservices. Wees je bewust van deze limiet bij het bouwen van uw URL ‘ s. Merk op dat verschillende browsers, proxy ‘ s, en servers kunnen verschillende URL karakter grenzen ook.

HTTPS of HTTP

beveiliging is belangrijk en HTTPS wordt waar mogelijk aanbevolen, vooral voor toepassingen die gevoelige gebruikersgegevens bevatten, zoals de locatie van een gebruiker, in aanvragen. Het gebruik van HTTPS-encryptie maakt uw applicatie veiliger en beter bestand tegen snuffelen of knoeien.

als HTTPS niet mogelijk is, gebruikt u om toegang te krijgen tot de Distance Matrix API via HTTP:

Verzoekparameters

bepaalde parameters zijn vereist, terwijl andere optioneel zijn. Zoals standaard in URL ‘ s, worden alle parameters gescheiden met behulp van het ampersand (&) teken. Alle gereserveerde tekens (bijvoorbeeld het plusteken “+”) moeten URL-gecodeerd zijn.De lijst van parameters en hun mogelijke waarden worden hieronder opgesomd.

vereiste parameters

• origins — het startpunt voor het berekenen van reisafstand en-tijd. U kunt een of meer locaties opgeven, gescheiden door het pipe-teken (|), in de vorm van een plaats-ID, een adres, of latitude/longitude coordinates:
  • Als u een plaats-ID opgeeft, moet u het voorvoegsel geven met place_id:. U kunt alleen een plaats-ID opgeven als de aanvraag een API-sleutel of een Google Maps Platform Premium Plan client-ID bevat. Je kunt plaats-ID ‘ s ophalen uit de Geocoding API en de Places API (inclusief Place Autocomplete). Voor een voorbeeld met behulp van plaats-ID ‘ s van plaats Autocomplete, zie plaats Autocomplete en richtingen. Voor meer informatie over plaats-ID ‘ s, zie het overzicht van plaats-ID.
  • Als u een adres passeert, codeert de service de string en converteert deze naar een breedtegraad/lengtegraad om de afstand te berekenen. Deze coördinaat kan verschillen van die van de Geocoding API, bijvoorbeeld een ingang van een gebouw in plaats van het centrum.

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

    opmerking: het gebruik van plaats-ID ‘ s heeft de voorkeur boven het gebruik van adressen of lengte – /breedtegraadcoördinaten. Het gebruik van coördinaten zal altijd resulteren in het punt wordt geklikt op de weg die het dichtst bij die coördinaten – die misschien niet een toegangspunt tot het pand, of zelfs een weg die snel of veilig zal leiden naar de bestemming.
  • Als u de latitude/longitude coordinaten passeert, zullen ze naar de dichtstbijzijnde weg klikken. Het doorgeven van een plaats ID heeft de voorkeur. Als u de coördinaten passeert, moet u ervoor zorgen dat er geen ruimte tussen de breedtegraad-en lengtegraadwaarden bestaat.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • Plus-codes moeten worden opgemaakt als een globale code of een samengestelde code. Format plus codes zoals hier getoond (plus tekens zijn url-escaped naar %2B en spaties zijn url-escaped naar %20):
    • globale code is een area code van 4 tekens en een lokale code van 6 tekens of langer (849VCWC8+R9 is 849VCWC8%2BR9).
    • samengestelde code is een 6-teken of langere lokale code met een expliciete locatie (Cwc8+R9 Mountain View, CA, USA is CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • u kunt ook een gecodeerde set coördinaten opgeven met behulp van het gecodeerde Polylijnalgoritme. Dit is vooral handig als u een groot aantal origin punten, omdat de URL is aanzienlijk korter bij het gebruik van een gecodeerde polylijn.
    • gecodeerde polylijnen moeten worden voorafgegaan door enc: en gevolgd door een dubbele punt (:).Bijvoorbeeld: origins=enc:gfo}EtohhU:
    • u kunt ook meerdere gecodeerde polylijnen opnemen, gescheiden door het pipe-teken (|). Bijvoorbeeld: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — Een of meer locaties om te gebruiken als eindpunt voor het berekenen van reisafstand en-tijd. De opties voor de destinationsparameter zijn hetzelfde als voor de origins parameter, hierboven beschreven.
• key — de API-sleutel van uw toepassing. Deze sleutel identificeert uw toepassing voor doeleinden van quotabeheer. Leer hoe je aan een sleutel komt.

  opmerking: Klanten van het Google Maps Platform Premium Plan kunnen in uw Distance Matrix-Verzoeken een API-sleutel of een geldige client-ID en digitale handtekening gebruiken. Meer informatie over verificatieparameters voor Premium Plan-klanten.

het volgende voorbeeld gebruikt latitude/longitude coordinates om de bestemmingscoördinaten op te geven:

het volgende voorbeeld gebruikt plus codes om de bestemmingscoördinaten op te geven:

het volgende voorbeeld toont hetzelfde verzoek met behulp van een gecodeerde polylijn:

optionele parameters

• mode (standaard driving) — specificeert de wijze van transport die gebruikt wordt bij het berekenen van de afstand. Geldige waarden en andere verzoekdetails worden gespecificeerd in de sectie reismodi van dit document.
• language – de taal waarin de resultaten moeten worden geretourneerd.
  • zie de lijst met ondersteunde talen. Google werkt vaak de ondersteunde talen bij, dus deze lijst is mogelijk niet volledig.
  • als language niet wordt opgegeven, probeert de API de voorkeurstaal te gebruiken zoals gespecificeerd in de Accept-Language header, of de moedertaal van het domein van waaruit het verzoek wordt verzonden.
  • de API doet zijn best om een straatadres aan te bieden dat leesbaar is voor zowel de gebruiker als de lokale bevolking. Om dat doel te bereiken, geeft het straatadressen terug in de lokale taal, getranslitereerd naar een script dat leesbaar is voor de gebruiker indien nodig, waarbij de voorkeurstaal wordt geobserveerd. Alle andere adressen worden geretourneerd in de gewenste taal. Adrescomponenten worden allemaal geretourneerd in dezelfde taal, die wordt gekozen uit de eerste component.
  • als een naam niet beschikbaar is in de voorkeurstaal, gebruikt de API de dichtstbijzijnde overeenkomst.
  • de voorkeurstaal heeft een kleine invloed op de reeks resultaten die de API kiest om te retourneren, en de volgorde waarin ze worden geretourneerd. De geocoder interpreteert afkortingen verschillend, afhankelijk van de taal, zoals de afkortingen voor straattypen, of Synoniemen die geldig kunnen zijn in de ene taal, maar niet in een andere. Bijvoorbeeld, utca en tér zijn synoniemen voor straat in het Hongaars.
• region — de regiocode, gespecificeerd als een ccTLD (country code top level domain) waarde van twee tekens. De meeste ccTLD-codes zijn identiek aan ISO 3166-1-codes, met enkele uitzonderingen. Deze parameter zal alleen de resultaten van de geocoder beïnvloeden, niet volledig beperken. Indien er buiten het gespecificeerde gebied meer relevante resultaten bestaan, kunnen deze worden opgenomen.
• avoid — introduceert beperkingen op de route. Geldige waarden worden gespecificeerd in de sectie beperkingen van dit document. Er kan slechts één beperking worden gespecificeerd.
• units — specificeert het eenheidssysteem dat moet worden gebruikt bij het uitdrukken van afstand als tekst. Zie de sectie Unit systems van dit document voor meer informatie.
• arrival_time — specificeert de gewenste aankomsttijd voor transitverzoeken, in seconden sinds middernacht, 1 januari 1970 UTC. U kunt departure_time of arrival_time opgeven, maar niet beide. Merk op dat arrival_time moet worden opgegeven als een geheel getal.
• departure_time – de gewenste vertrektijd. U kunt de tijd opgeven als een geheel getal in seconden sinds middernacht, 1 januari 1970 UTC. Als een departure_time later dan 9999-12-31T23:59:59.999999999 Z is opgegeven, zal de API de departure_time terugvallen tot 9999-12-31T23:59:59.999999999 Z. U kunt ook een waarde opgeven van now, waardoor de vertrektijd wordt ingesteld op de huidige tijd (correct tot op de dichtstbijzijnde seconde). De vertrektijd kan in twee gevallen worden gespecificeerd:
  • voor verzoeken waarbij de reismodus doorreis is: U kunt optioneel een van departure_time of arrival_timeopgeven. Als geen van beide tijd is opgegeven, is de departure_time standaard nu (dat wil zeggen, de vertrektijd is standaard de huidige tijd).
  • voor aanvragen waarin de reismodus rijdt: u kunt departure_time opgeven om een route en reisduur te ontvangen (responsveld: duration_in_traffic) die rekening houden met de verkeersomstandigheden. Deze optie is alleen beschikbaar als de aanvraag een geldige API-sleutel of een geldige Google Maps Platform Premium Plan client ID en handtekening bevat. De departure_time moet worden ingesteld op de huidige tijd of enige tijd in de toekomst. Het kan niet in het verleden zijn.

    opmerking: als de vertrektijd niet is gespecificeerd, zijn de keuze van de route en de duur gebaseerd op het wegennet en de gemiddelde tijdonafhankelijke verkeersomstandigheden. De resultaten van een bepaalde aanvraag kunnen in de loop van de tijd variëren als gevolg van veranderingen in het wegennet, bijgewerkte gemiddelde verkeersomstandigheden en de gedistribueerde aard van de dienst. De resultaten kunnen ook variëren tussen bijna gelijkwaardige routes op elk moment of frequentie.

    opmerking: Distance Matrixaanvragen die departure_time specificeren wanneer mode=driving beperkt zijn tot maximaal 100 elementen per aanvraag. Het aantal vertrekpunten maal het aantal bestemmingen bepaalt het aantal elementen.

• traffic_model (standaard best_guess) — specificeert de veronderstellingen die moeten worden gebruikt bij het berekenen van de tijd in het verkeer. Deze instelling beà nvloedt de waarde die wordt geretourneerd in het veld duration_in_traffic in de respons, die de voorspelde tijd in het verkeer bevat op basis van historische gemiddelden. De parameter traffic_model mag alleen worden opgegeven voor aanvragen waarbij de reismodus driving is, en waarbij de aanvraag een departure_time bevat, en alleen als de aanvraag een API-sleutel of een Google Maps Platform Premium Plan client-ID bevat. De beschikbare waarden voor deze parameter zijn:
  • best_guess (standaard) geeft aan dat de geretourneerde duration_in_traffic de beste schatting van de reistijd moet zijn gezien wat bekend is over zowel historische verkeersomstandigheden als live verkeer. Live verkeer wordt belangrijker naarmate departure_time dichter bij nu is.
  • pessimistic geeft aan dat de geretourneerde duration_in_traffic op de meeste dagen langer moet zijn dan de werkelijke reistijd, hoewel af en toe dagen met bijzonder slechte verkeersomstandigheden deze waarde kunnen overschrijden.
  • optimistic geeft aan dat de geretourneerde duration_in_traffic op de meeste dagen korter moet zijn dan de werkelijke reistijd, hoewel af en toe dagen met bijzonder goede verkeersomstandigheden sneller kunnen zijn dan deze waarde.
• transit_mode — specificeert een of meer voorkeurswijzen van doorvoer. Deze parameter mag alleen worden gespecificeerd voor aanvragen waarbij modetransitis. De parameter ondersteunt de volgende argumenten:
  • bus geeft aan dat de berekende route de voorkeur geeft aan reizen met de bus.
  • subway geeft aan dat de berekende route de voorkeur geeft aan reizen met de metro.
  • train geeft aan dat de berekende route de voorkeur geeft aan reizen per trein.
  • tram geeft aan dat de berekende route de voorkeur geeft aan tram-en sneltramverkeer.
  • rail geeft aan dat de berekende route de voorkeur geeft aan reizen per trein, tram, sneltram en metro. Dit is gelijk aan transit_mode=train|tram|subway.
• transit_routing_preference — specificeert voorkeuren voor doorvoerverzoeken. Met behulp van deze parameter, kunt u de geretourneerde opties bias, in plaats van het accepteren van de standaard beste route gekozen door de API. Deze parameter mag alleen worden gespecificeerd voor aanvragen waarbij modetransitis. De parameter ondersteunt de volgende argumenten:
  • less_walking geeft aan dat de berekende route de voorkeur moet geven aan beperkte hoeveelheden lopen.
  • fewer_transfers geeft aan dat de berekende route de voorkeur moet geven aan een beperkt aantal transfers.

reismodi

voor de berekening van afstanden kunt u het te gebruiken Vervoer mode opgeven. Standaard worden afstanden berekend voor de rijmodus. De volgende reismodi worden ondersteund:

• driving (standaard) geeft de berekening van de afstand aan met behulp van het wegennet.
• walking vraagt berekening van de afstand voor het lopen via voetpaden & trottoirs (indien beschikbaar).
• bicycling vraagt berekening van de afstand voor fietsen via fietspaden & voorkeursstraten (indien beschikbaar).
• transit verzoekt om berekening van de afstand via openbaarvervoerroutes (indien beschikbaar). Deze waarde mag alleen worden opgegeven als de aanvraag een API-sleutel of een Google Maps Platform Premium Plan client ID bevat. Als u de modus instelt op transit kunt u optioneel een departure_time opgeven of een arrival_time. Als geen van beide tijd is opgegeven, is de departure_time standaard nu (dat wil zeggen, de vertrektijd is standaard de huidige tijd). U kunt ook optioneel een transit_mode en/of een transit_routing_preferenceopnemen.

verkeersinformatie

verkeersinformatie wordt gebruikt wanneer alle volgende voorwaarden van toepassing zijn (dit zijn de voorwaarden die vereist zijn om het duration_in_traffic veld in de Distance Matrix response te ontvangen):

• De travel mode parameter is driving; or is niet opgegeven (driving is de standaard reismodus).
• het verzoek bevat een geldigedeparture_time parameter. De departure_time kan worden ingesteld op de huidige tijd of enige tijd in de toekomst. Het kan niet in het verleden zijn.

Optioneel kunt u de parameter traffic_model opnemen in uw verzoek om de veronderstellingen te specificeren die moeten worden gebruikt bij het berekenen van de tijd in het verkeer.

de volgende URL initieert een Distance Matrix verzoek voor het rijden afstanden tussen Boston, MA of Charlestown, MA, en Lexington, MA en Concord, MA. Het verzoek bevat een vertrektijd die voldoet aan alle vereisten om het veld duration_in_traffic in de respons van de Distance Matrix terug te geven.

beperkingen

afstanden kunnen worden berekend die aan bepaalde beperkingen voldoen. Beperkingen worden aangegeven door gebruik te maken van de avoid parameter, en een argument voor die parameter dat de te vermijden beperking aangeeft. De volgende beperkingen worden ondersteund:

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

* opmerking: het toevoegen van beperkingen sluit routes die de beperkte functie bevatten niet uit; het vertaalt het resultaat naar gunstiger routes.

Eenheidssystemen

afstand Matrixresultaten bevatten text binnen distance velden om de afstand van de berekende route aan te geven. Het te gebruiken eenheidssysteem kan worden opgegeven:

• units=metric (standaard) geeft afstanden in kilometers en meters terug.
• units=imperial geeft afstanden in mijlen en voeten terug.

* Opmerking: Deze instelling van het eenheidssysteem heeft alleen invloed op de text weergegeven in distance velden. De velden distance bevatten ook values die altijd worden uitgedrukt in meters.

Distance Matrix responses

antwoorden op Distance Matrix API queries worden geretourneerd in het formaat dat is aangegeven met deoutput vlag binnen het pad van de URL-aanvraag.

twee VOORBEELDVERZOEKEN voor HTTP worden hieronder getoond, waarbij afstand en duur worden aangevraagd van Vancouver, BC, Canada en van Seattle, WA, USA, naar San Francisco, CA, USA en Victoria, BC, Canada.

dit verzoek toont het gebruik van de vlag JSON output :

Dit verzoek laat het gebruik van de XML output vlag:

Dit verzoek zal de terugkeer van de vier elementen – twee oorsprong keer twee bestemmingen:

de Resultaten worden weergegeven in rijen, elke rij bevat één oorsprong gepaard met elke bestemming.

u kunt dit testen door de URL in uw webbrowser in te voeren (zorg ervoor dat u YOUR_API_KEY vervangt door uw eigenlijke API-sleutel).

Selecteer de tabbladen hieronder om de voorbeeldreacties van JSON en XML te zien.

de rest van deze documentatie zal JSON syntaxis gebruiken.

Distance Matrix response elements

Distance Matrix response Elements bevatten de volgende root elements:

• status bevat metagegevens op het verzoek. Zie statuscodes hieronder.
• origin_addresses bevat een reeks adressen zoals geretourneerd door de API van uw oorspronkelijke verzoek. Deze worden geformatteerd door de geocoder en gelokaliseerd volgens de parameter language die met het verzoek wordt doorgegeven.
• destination_addresses bevat een reeks adressen zoals geretourneerd door de API van uw oorspronkelijke verzoek. Net als bij origin_addresses, worden deze gelokaliseerd indien van toepassing.
• rows bevat een array van elements, die op hun beurt elk een statusduration, en distance element bevatten.

statuscodes

de status velden binnen het antwoordobject bevatten de status van het verzoek en kunnen nuttige debuginformatie bevatten. De Distance Matrix API retourneert een top-level status veld, met informatie over de aanvraag in het algemeen, evenals een status veld voor elk element veld, met informatie over die specifieke oorsprong-bestemming koppeling.

top-level statuscodes

• OK geeft aan dat het antwoord een geldige resultbevat.
• INVALID_REQUEST geeft aan dat het opgegeven verzoek ongeldig was.
• MAX_ELEMENTS_EXCEEDED geeft aan dat het product van oorsprong en bestemming de limiet per query overschrijdt.
• MAX_DIMENSIONS_EXCEEDED geeft aan dat het aantal oorsprong of bestemming de limiet per query overschrijdt.
• OVER_DAILY_LIMIT geeft een van de volgende aan:
  • de API-sleutel ontbreekt of is ongeldig.
  • facturering is niet ingeschakeld op uw account.
  • een zelf opgelegde gebruikslimiet is overschreden.
  • de opgegeven betaalmethode is niet langer geldig (een creditcard is bijvoorbeeld verlopen).

  zie de Veelgestelde Vragen Over Maps om te leren hoe u dit kunt oplossen.

• OVER_QUERY_LIMIT geeft aan dat de service te veel verzoeken van uw toepassing binnen de toegestane periode heeft ontvangen.
• REQUEST_DENIED geeft aan dat de service het gebruik van de Distance Matrix-service door uw toepassing heeft geweigerd.
• UNKNOWN_ERROR geeft aan dat een Afstandsmatrixverzoek niet kon worden verwerkt door een serverfout. Het verzoek kan slagen als u het opnieuw probeert.

statuscodes op Elementniveau

• OK geeft aan dat het antwoord een geldige resultbevat.
• NOT_FOUND geeft aan dat de oorsprong en/of bestemming van deze koppeling niet geocodeerd kon worden.
• ZERO_RESULTS geeft aan dat er geen route kon worden gevonden tussen de oorsprong en de bestemming.
• MAX_ROUTE_LENGTH_EXCEEDED geeft aan dat de gevraagde route te lang is en niet kan worden verwerkt.

foutmeldingen

wanneer de hoogste status code anders is dan OK, kan er een extraerror_message veld zijn binnen het Distance Matrix response object. Dit veld bevat meer gedetailleerde informatie over de redenen achter de gegeven statuscode.

Opmerking: Dit veld is niet gegarandeerd altijd aanwezig en de inhoud is onderhevig aan wijzigingen.

rijen

wanneer de Distance Matrix API resultaten retourneert, plaatst het deze in een JSON rows array. Zelfs als er geen resultaten worden geretourneerd (zoals wanneer de oorsprong en/of bestemmingen niet bestaan), geeft het nog steeds een lege array terug. XML-reacties bestaan uit nul of meer <row> elementen.

rijen worden geordend volgens de waarden in deorigin parameter van de aanvraag. Elke rij komt overeen met een oorsprong, en elke element binnen die rij komt overeen met een koppeling van de oorsprong met een destination waarde.

elke row array bevat een of meer element items, die op hun beurt de informatie bevatten over een enkele oorsprong-bestemming koppeling.

elementen

de informatie over elke koppeling tussen oorsprong en bestemming wordt geretourneerd in een element entry. An element bevat de volgende velden:

• status: zie statuscodes voor een lijst met mogelijke statuscodes.
• duration: de tijd die nodig is om deze route te reizen, uitgedrukt in seconden (het veld value) en als text. De tekstuele representatie wordt gelokaliseerd volgens de parameter language van de query.

• duration_in_traffic: de tijd die nodig is om deze route te reizen, gebaseerd op de huidige en historische verkeersomstandigheden. Zie detraffic_model request parameter voor de opties die u kunt gebruiken om te vragen dat de geretourneerde waarde optimistisch, pessimistisch of een best-guess schatting is. De duur wordt uitgedrukt in seconden (het veld value) en als text. De tekstuele representatie wordt gelokaliseerd volgens de parameter language van de query. De duur van het verkeer wordt alleen geretourneerd als alle volgende waarden waar zijn:

  • het verzoek bevat een parameter departure_time.
  • het verzoek bevat een geldige API-sleutel of een geldige Google Maps Platform Premium Plan client ID en handtekening.
  • verkeersomstandigheden zijn beschikbaar voor de gevraagde route.
  • de parametermode is ingesteld opdriving.
• distance: de totale afstand van deze route, uitgedrukt in meters (value) en als text. De tekstwaarde gebruikt het eenheidssysteem dat is opgegeven met de parameter unit van het oorspronkelijke verzoek, of de regio van de oorsprong.
• fare: indien aanwezig, bevat het totale tarief (dat wil zeggen de totale ticketkosten) op deze route. Deze accommodatie wordt alleen geretourneerd voor transit-aanvragen en alleen voor transit-aanbieders waar tariefinformatie beschikbaar is. De informatie omvat:
  • currency: Een ISO 4217-valuta-code die aangeeft in welke valuta het bedrag is uitgedrukt.
  • value: het totale tariefbedrag, in de hierboven vermelde valuta.
  • text: het totale tariefbedrag, opgemaakt in de gevraagde taal.

Hieronder is een voorbeeld van een element die tariefinformatie bevat:

de sensorparameter

de Google Maps API vereiste eerder dat u desensor parameter opnam om aan te geven of uw toepassing als sensor gebruikte om de locatie van de gebruiker te bepalen. Deze parameter is niet langer vereist.