introduktion

Distance Matrix API är en tjänst som tillhandahåller reseavstånd och tid för en matris av ursprung och destinationer. API Returnerar information baserat på den rekommenderade rutten mellan start-och slutpunkter, beräknat av Google Maps API, och består av rader som innehåller duration och distance värden för varje par.

Obs: Denna tjänst returnerar inte detaljerad ruttinformation. Ruttinformation kan erhållas genom att skicka önskat enda ursprung och destination till riktnings API.

innan du börjar

detta dokument är avsett för utvecklare som vill beräkna reseavstånd och tid mellan ett antal punkter i kartor som tillhandahålls av en av Google Maps API: er. Det ger en introduktion till att använda API och referensmaterial på tillgängliga parametrar.

innan du börjar utveckla med Distance Matrix API, granska autentiseringskraven (du behöver en API-nyckel) och API-användnings-och faktureringsinformation (du måste aktivera fakturering på ditt projekt).

Avståndsmatrisförfrågningar

en API-begäran om Avståndsmatris har följande form:

där outputFormat kan vara något av följande värden:

• json (rekommenderas), indikerar utgång i JavaScript Object Notation (JSON); eller
• xml, indikerar utdata som XML.

Obs: webbadresser måste vara korrekt kodade för att vara giltiga och är begränsade till 8192 tecken för alla webbtjänster. Var medveten om denna gräns när du konstruerar dina webbadresser. Observera att olika webbläsare, proxies och servrar kan ha olika URL-teckengränser också.

HTTPS eller HTTP

säkerhet är viktigt och HTTPS rekommenderas när det är möjligt, särskilt för applikationer som innehåller känsliga användardata, till exempel en användares plats, i förfrågningar. Att använda HTTPS-kryptering gör din applikation säkrare och mer motståndskraftig mot snooping eller manipulering.

om HTTPS inte är möjligt, för att komma åt Distansmatrisen API över HTTP, använd:

begär parametrar

vissa parametrar krävs medan andra är valfria. Som standard i webbadresser separeras alla parametrar med tecknet ampersand (&). Alla reserverade tecken (till exempel plustecknet ”+”) måste vara URL-kodade.Listan över parametrar och deras möjliga värden räknas upp nedan.

obligatoriska parametrar

• origins — utgångspunkten för beräkning av reseavstånd och tid. Du kan leverera en eller flera platser åtskilda av pipe-tecknet (|), I form av ett place ID, en adress eller latitud/longitud koordinater:
  • Om du anger ett place ID måste du prefixa det med place_id:. Du kan bara ange ett plats-ID om begäran innehåller en API-nyckel eller ett Google Maps Platform Premium Plan client ID. Du kan hämta plats-ID från Geocoding API och platser API (inklusive plats Komplettera automatiskt). Om du till exempel använder place ID från Place Autocomplete, se Place Autocomplete och vägbeskrivning. Mer information om plats-ID finns i översikt över plats-ID.
  • Om du skickar en adress geocoderar tjänsten strängen och konverterar den till en latitud/longitudkoordinat för att beräkna avståndet. Denna koordinat kan skilja sig från den som returneras av GEOKODNINGS API, till exempel en byggnadsingång snarare än dess centrum.

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

    Obs: att använda plats-ID är att föredra framför att använda adresser eller latitud/longitudkoordinater. Att använda koordinater kommer alltid att resultera i att punkten knäpps till vägen närmast dessa koordinater – vilket kanske inte är en åtkomstpunkt till fastigheten, eller till och med en väg som snabbt eller säkert leder till destinationen.
  • Om du passerar latitud / longitud koordinater, de de kommer att knäppa till närmaste väg. Passerar en plats ID är att föredra. Om du skickar koordinater, se till att det inte finns något utrymme mellan latitud-och longitudvärdena.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • Plus koder måste formateras som en global kod eller en sammansatt kod. Format plus koder som visas här (plustecken är url-flydde till %2Boch mellanslag är url-flydde till %20):
    • global kod är en Riktnummer med 4 tecken och 6 tecken eller längre lokal kod (849VCWC8+R9 är 849VCWC8%2BR9).
    • sammansatt kod är en 6 tecken eller längre lokal kod med en uttrycklig plats (CWC8+R9 Mountain View, CA, USA är CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Alternativt kan du leverera en kodad uppsättning koordinater med den kodade Polylinalgoritmen. Detta är särskilt användbart om du har ett stort antal ursprungspunkter, eftersom webbadressen är betydligt kortare när du använder en kodad polylinje.
    • kodade polyliner måste prefixeras med enc: och följt av ett kolon (:).Till exempel: origins=enc:gfo}EtohhU:
    • Du kan också inkludera flera kodade polyliner, åtskilda av rörtecknet (|). Exempelvis: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — en eller flera platser att använda som slutpunkt för beräkning av reseavstånd och tid. Alternativen för parametern destinations är desamma som för parametern origins som beskrivs ovan.
• key — programmets API-nyckel. Denna nyckel identifierar din ansökan för kvothantering. Lär dig hur du får en nyckel.

  Obs: Google Maps Platform Premium Plan-kunder kan använda antingen en API-nyckel eller ett giltigt klient-ID och digital signatur i dina Distansmatrisförfrågningar. Få mer information om autentiseringsparametrar för Premium plan-kunder.

i följande exempel används Koordinater för latitud / longitud för att ange destinationskoordinater:

i följande exempel används pluskoder för att ange destinationskoordinater:

i följande exempel visas samma begäran med en kodad polylinje:

valfria parametrar

• mode(Standardvärdet är driving) — anger vilket transportsätt som ska användas vid beräkning av avstånd. Giltiga värden och andra förfrågningsuppgifter anges i avsnittet Reselägen i detta dokument.
• language — språket för att returnera resultat.
  • se listan över språk som stöds. Google uppdaterar ofta de språk som stöds, så den här listan kanske inte är uttömmande.
  • Om languageinte tillhandahålls, försöker API: n att använda det språk som anges i Accept-Language eller modersmålet för domänen från vilken begäran skickas.
  • API gör sitt bästa för att ge en gatuadress som är läsbar för både användaren och lokalbefolkningen. För att uppnå detta mål returnerar den gatuadresser på det lokala språket, transliterated till ett skript som kan läsas av användaren om det behövs, observera det föredragna språket. Alla andra adresser returneras på önskat språk. Adress komponenter returneras alla på samma språk, som väljs från den första komponenten.
  • om ett namn inte är tillgängligt på det språk som föredras använder API: n den närmaste matchningen.
  • det föredragna språket har ett litet inflytande på den uppsättning resultat som API väljer att returnera och i vilken ordning de returneras. Geocoder tolkar förkortningar olika beroende på språk, till exempel förkortningar för gatutyper, eller synonymer som kan vara giltiga på ett språk men inte på ett annat. Till exempel är utca och t Ubir synonymer för gatan på ungerska.
• region — regionkoden, specificerad som ett ccTLD-värde (landskod toppdomän) med två tecken. De flesta ccTLD-koder är identiska med ISO 3166-1-koder, med vissa undantag. Denna parameter påverkar bara, inte helt begränsa, resultat från geocoder. Om det finns mer relevanta resultat utanför den angivna regionen kan de inkluderas.
• avoid — introducerar begränsningar för rutten. Giltiga värden anges i avsnittet begränsningar i detta dokument. Endast en begränsning kan anges.
• units — anger det enhetssystem som ska användas vid uttryck av avstånd som text. Se avsnittet enhetssystem i detta dokument för mer information.
• arrival_time — anger önskad ankomsttid för transitförfrågningar, i sekunder sedan midnatt den 1 januari 1970 UTC. Du kan ange antingen departure_timeeller arrival_time, men inte båda. Observera att arrival_time måste anges som ett heltal.
• departure_time — önskad avgångstid. Du kan ange tiden som ett heltal i sekunder sedan midnatt den 1 januari 1970 UTC. Om ett departure_time senare än 9999-12-31t23:59:59.9999999999 Z anges kommer API:et att falla tillbaka departure_time till 9999-12-31t23:59: 59.9999999999 Z. Alternativt kan du ange ett värde av now, som ställer in avgångstiden till den aktuella tiden (korrekt till närmaste sekund). Avgångstiden kan anges i två fall:
  • för förfrågningar där reseläget är transitering: Du kan valfritt ange en av departure_time eller arrival_time. Om ingen tid anges är departure_time som standard nu (det vill säga avgångstiden som standard den aktuella tiden).
  • för förfrågningar där reseläget kör: du kan ange departure_time för att få en rutt och reslängd (svarsfält: duration_in_traffic) som tar hänsyn till trafikförhållandena. Det här alternativet är endast tillgängligt om begäran innehåller en giltig API-nyckel eller ett giltigt Google Maps Platform Premium Plan client ID och signatur. departure_time måste ställas in på aktuell tid eller någon tid i framtiden. Det kan inte vara i det förflutna.

    Obs: Om avgångstiden inte anges är val av rutt och varaktighet baserat på vägnät och genomsnittliga tidsoberoende trafikförhållanden. Resultaten för en viss begäran kan variera över tid på grund av förändringar i vägnätet, uppdaterade genomsnittliga trafikförhållanden och tjänstens distribuerade karaktär. Resultaten kan också variera mellan nästan likvärdiga rutter när som helst eller frekvens.

    Obs: Avståndsmatrisförfrågningar som anger departure_time när mode=driving är begränsade till högst 100 element per begäran. Antalet ursprung gånger antalet destinationer definierar antalet element.

• traffic_model (Standardvärdet är best_guess) — anger de antaganden som ska användas vid beräkning av tid i trafiken. Den här inställningen påverkar värdet som returneras i fältet duration_in_traffic I svaret, som innehåller den förutsagda tiden i trafiken baserat på historiska medelvärden. Parameterntraffic_model får endast anges för förfrågningar där reseläget ärdriving, och där begäran innehåller ettdeparture_time, och endast om begäran innehåller en API-nyckel eller ett Google Maps Platform Premium Plan client ID. De tillgängliga värdena för denna parameter är:
  • best_guess (standard) indikerar att det returnerade duration_in_traffic ska vara den bästa uppskattningen av restiden med tanke på vad som är känt om både historiska trafikförhållanden och levande trafik. Levande trafik blir viktigare ju närmare departure_time är nu.
  • pessimistic indikerar att det returneradeduration_in_traffic bör vara längre än den faktiska restiden på de flesta dagar, även om tillfälliga dagar med särskilt dåliga trafikförhållanden kan överstiga detta värde.
  • optimistic indikerar att det returneradeduration_in_traffic bör vara kortare än den faktiska restiden på de flesta dagar, även om tillfälliga dagar med särskilt goda trafikförhållanden kan vara snabbare än detta värde.
• transit_mode — anger ett eller flera föredragna transportsätt. Denna parameter får endast anges för förfrågningar där mode är transit. Parametern stöder följande argument:
  • bus indikerar att den beräknade rutten föredrar att resa med buss.
  • subway indikerar att den beräknade rutten föredrar att resa med tunnelbana.
  • train indikerar att den beräknade rutten föredrar att resa med tåg.
  • tram indikerar att den beräknade rutten föredrar att resa med spårvagn och spårväg.
  • rail indikerar att den beräknade rutten föredrar att resa med tåg, spårvagn, spårväg och tunnelbana. Detta motsvarar transit_mode=train|tram|subway.
• transit_routing_preference — anger inställningar för transitförfrågningar. Med den här parametern kan du bias de alternativ som returneras, snarare än att acceptera den standard bästa rutten som valts av API. Denna parameter får endast anges för förfrågningar där mode är transit. Parametern stöder följande argument:
  • less_walking indikerar att den beräknade vägen bör föredra begränsade mängder gång.
  • fewer_transfers indikerar att den beräknade rutten bör föredra ett begränsat antal överföringar.

reslägen

för beräkning av avstånd kan du ange transport mode att använda. Som standard beräknas avstånd för körläge. Följande körlägen stöds:

• driving (standard) indikerar avståndsberäkning med vägnätet.
• walking begär avståndsberäkning för promenader via gångvägar & trottoarer (om tillgängligt).
• bicycling begär avståndsberäkning för cykling via cykelvägar & föredragna gator (där det finns).
• transit begär avståndsberäkning via kollektivtrafikvägar (om tillgängligt). Detta värde får endast anges om begäran innehåller en API-nyckel eller ett klient-ID för Google Maps Platform Premium Plan. Om du ställer in läget på transit kan du välja att ange antingen ett departure_time eller ett arrival_time. Om ingen tid anges är departure_time som standard nu (det vill säga avgångstiden som standard den aktuella tiden). Du kan också valfritt inkludera ett transit_mode och/eller ett transit_routing_preference.

trafikinformation

trafikinformation används när alla följande gäller (dessa är de villkor som krävs för att ta emot fältetduration_in_traffic I Avståndsmatrissvaret):

• parametern travelmode ärdriving, eller är inte specificerat (driving är standardläget för resor).
• begäran innehåller en giltigdeparture_time parameter. departure_time kan ställas in på aktuell tid eller någon tid i framtiden. Det kan inte vara i det förflutna.

Alternativt kan du inkludera parameterntraffic_model I din begäran om att ange de antaganden som ska användas vid beräkning av tid i trafiken.

följande URL initierar en Distansmatrisförfrågan för köravstånd mellan Boston, MA eller Charlestown, MA och Lexington, MA och Concord, MA. Begäran innehåller en avgångstid som uppfyller alla krav för att returnera fältet duration_in_traffic I Avståndsmatrissvaret.

begränsningar

avstånd kan beräknas som följer vissa begränsningar. Begränsningar anges med hjälp av parametern avoid och ett argument till den parametern som anger begränsningen som ska undvikas. Följande begränsningar stöds:

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

* Obs: tillägg av begränsningar utesluter inte rutter som inkluderar den begränsade funktionen; det föregriper resultatet till mer gynnsamma rutter.

enhetssystem

Avståndsmatrisresultat innehållertext inomdistance fält för att ange avståndet för den beräknade rutten. Enhetssystemet som ska användas kan specificeras:

• units=metric (standard) returnerar avstånd i kilometer och meter.
• units=imperial returnerar avstånd i miles och fot.

* Obs! Denna enhetssysteminställning påverkar endast fälten textsom visas i distance. Fälten distance innehåller också values som alltid uttrycks i meter.

Distansmatrissvar

svar på API-frågor för Distansmatris returneras i det format som indikeras av flaggan output inom URL-förfrågans sökväg.

två exempel HTTP-förfrågningar visas nedan, begär avstånd och varaktighet från Vancouver, BC, Kanada och från Seattle, WA, USA, till San Francisco, CA, USA och Victoria, BC, Kanada.

denna begäran visar med hjälp av flaggan JSON output :

denna begäran visar att använda XMLoutput flagga:

denna begäran kommer att returnera fyra element – två ursprung gånger två destinationer:

resultat returneras i rader, varje rad innehåller ett ursprung parat med varje destination.

Du kan testa detta genom att ange webbadressen i din webbläsare (var noga med att ersätta YOUR_API_KEY med din faktiska API-nyckel).

Välj flikarna nedan för att se sample JSON och XML svar.

resten av denna dokumentation kommer att använda JSON syntax.

Avståndsmatrissvarselement

Avståndsmatrissvar innehåller följande rotelement:

• status innehåller metadata på begäran. Se statuskoder nedan.
• origin_addresses innehåller en rad adresser som returneras av API från din ursprungliga begäran. Dessa formateras av geocoder och lokaliseras enligtlanguage – parametern som skickas med begäran.
• destination_addresses innehåller en rad adresser som returneras av API från din ursprungliga begäran. Som med origin_addresses är dessa lokaliserade om det är lämpligt.
• rows innehåller en matris med elements, som i sin tur innehåller ett statusduration och distance element.

statuskoder

status fält i svarsobjektet innehåller status för begäran och kan innehålla användbar felsökningsinformation. Distance Matrix API returnerar ett statusfält på toppnivå, med information om begäran i allmänhet, samt ett statusfält för varje elementfält, med information om den specifika parkopplingen mellan ursprung och destination.

toppnivåstatuskoder

• OKindikerar att svaret innehåller ett giltigtresult.
• INVALID_REQUEST indikerar att den angivna begäran var ogiltig.
• MAX_ELEMENTS_EXCEEDED indikerar att produkten av ursprung och destinationer överskrider gränsen per fråga.
• MAX_DIMENSIONS_EXCEEDED anger att antalet ursprung eller destinationer överskrider gränsen per fråga.
• OVER_DAILY_LIMIT anger något av följande:
  • API-nyckeln saknas eller är ogiltig.
  • fakturering har inte aktiverats på ditt konto.
  • ett självpålagt användningslock har överskridits.
  • den angivna betalningsmetoden är inte längre giltig (till exempel har ett kreditkort löpt ut).

  se Vanliga frågor om kartor för att lära dig hur du åtgärdar detta.

• OVER_QUERY_LIMIT indikerar att tjänsten har fått för många förfrågningar från din ansökan inom den tillåtna tidsperioden.
• REQUEST_DENIED indikerar att tjänsten nekade användning av Distansmatristjänsten av din applikation.
• UNKNOWN_ERROR indikerar att en begäran om Avståndsmatris inte kunde behandlas på grund av ett serverfel. Begäran kan lyckas om du försöker igen.

statuskoder på Elementnivå

• OK indikerar att svaret innehåller ett giltigtresult.
• NOT_FOUND indikerar att ursprunget och/eller destinationen för denna parning inte kunde geokodas.
• ZERO_RESULTS indikerar att ingen rutt kunde hittas mellan ursprung och destination.
• MAX_ROUTE_LENGTH_EXCEEDED indikerar att den begärda rutten är för lång och kan inte behandlas.

felmeddelanden

När toppnivåstatuskoden är annan änOK kan det finnas ett ytterligareerror_message fält inom avståndsmatrisens svarobjekt. Detta fält innehållermer detaljerad information om orsakerna till den angivna statuskoden.

Obs: Detta fält är inte garanterat att alltid vara närvarande, och dess innehåll kan ändras.

rader

När Avståndsmatrisens API returnerar resultat placerar den dem i en JSON rows array. Även om inga resultat returneras (till exempel när ursprung och/eller destinationer inte finns) returnerar det fortfarande en tom matris. XML-svar består av noll eller fler <row> element.

rader beställs enligt värdena i parametern origin för begäran. Varje rad motsvarar ett ursprung och varje elementinom den raden motsvarar en parning av ursprunget med ett destination värde.

varjerow array innehåller en eller fleraelement poster, som i sin tur innehåller information om en enda ursprung-destination parning.

element

informationen om varje ursprung-destination parning returneras i enelement post. Ett element innehåller följande fält:

• status: se statuskoder för en lista över möjliga statuskoder.
• duration: hur lång tid det tar att resa denna rutt, uttryckt i sekunder (fältetvalue) och somtext. Textrepresentationen är lokaliserad enligt fråganslanguage parameter.

• duration_in_traffic: hur lång tid det tar att resa denna rutt, baserat på nuvarande och historiska trafikförhållanden. Setraffic_model begär parameter för de alternativ du kan använda för att begära att det returnerade värdet är optimistiskt, pessimistiskt eller en uppskattning av bästa gissning. Varaktigheten uttrycks i sekunder (fältet value) och som text. Textrepresentationen är lokaliserad enligt fråganslanguage parameter. Varaktigheten i trafiken returneras endast om alla följande är sanna:

  • begäran innehåller en departure_time parameter.
  • begäran innehåller en giltig API-nyckel eller ett giltigt Google Maps Platform Premium Plan client ID och signatur.
  • trafikförhållandena är tillgängliga för den begärda rutten.
  • parameternmode är inställd pådriving.
• distance: det totala avståndet för denna rutt, uttryckt i meter (value) och som text. Textvärdet använder enhetssystemet som anges med parameternunit för den ursprungliga begäran eller ursprungsregionen.
• fare: om närvarande innehåller den totala biljettpriset (det vill säga de totala biljettkostnaderna) på denna rutt. Denna fastighet returneras endast för transitförfrågningar och endast för transitleverantörer där biljettinformation är tillgänglig. Informationen innehåller:
  • currency: EN ISO 4217-valutakod som anger den valuta som beloppet uttrycks i.
  • value: det totala biljettpriset, i den valuta som anges ovan.
  • text: det totala biljettpriset, formaterat på det begärda språket.

nedan är ett exempel på enelement innehåller biljettinformation:

sensorparametern

Google Maps API krävde tidigare att du inkluderarsensor parameter för att ange om din applikation använde asensor för att bestämma användarens plats. Denna parameter är inte längrekrävs.