Innledning

Distance Matrix API Er en TJENESTE som gir reise avstand og tid for en matrise av opprinnelse og destinasjoner. API-en returnerer informasjon basert på den anbefalte ruten mellom start-og sluttpunkter, beregnet av Google Maps API, og består av rader som inneholder duration og distance verdier for hvert par.

Merk: denne tjenesten returnerer ikke detaljert ruteinformasjon. Ruteinformasjon kan fås ved å sende ønsket enkelt opprinnelse og destinasjon Til Directions API.

Før du begynner

dette dokumentet er ment for utviklere som ønsker å beregne reiseavstand og tid mellom et antall punkter i kart som leveres av En Av Google Maps Api-Ene. Det gir en introduksjon til BRUK AV API OG referansemateriale på de tilgjengelige parametrene.

før du begynner å utvikle Med Distance Matrix API, må du gjennomgå godkjenningskravene (DU trenger EN API-nøkkel) OG API-bruk og faktureringsinformasjon(du må aktivere fakturering på prosjektet).

forespørsler Om Avstandsmatrise

EN FORESPØRSEL om AVSTANDSMATRISE TAR følgende form:

der outputFormat kan være en av følgende verdier:

• json (anbefalt), indikerer utdata i javascript object notation (json); eller
• xml, angir utdata som xml.

Merk: Nettadresser må være riktig kodet for å være gyldige og er begrenset til 8192 tegn for alle webtjenester. Vær oppmerksom på denne grensen når du bygger Nettadressene dine. Merk at forskjellige nettlesere, proxyer og servere kan ha forskjellige URL-tegngrenser også.

HTTPS Eller HTTP

Sikkerhet er viktig, OG HTTPS anbefales når det er mulig, spesielt for applikasjoner som inneholder sensitive brukerdata, for eksempel en brukers plassering, i forespørsler. BRUK AV HTTPS-kryptering gjør programmet sikrere og mer motstandsdyktig mot snusing eller manipulering.

HVIS HTTPS ikke er mulig, for å få tilgang Til Distance Matrix API OVER HTTP, bruk:

Forespørselsparametere

Visse parametere kreves, mens andre er valgfrie. Som standard I Nettadresser, skilles alle parametere ved hjelp av tegnet ampersand (&). Alle reserverte tegn (for eksempel plusstegnet «+») må VÆRE URL-kodet.Listen over parametere og deres mulige verdier er oppført nedenfor.

Nødvendige parametere

• origins), i form av et sted-ID, en adresse eller breddegrad / lengdegradskoordinater:
  • Hvis du oppgir et sted-ID, må du prefiks det medplace_id:. Du kan bare angi en sted-ID hvis forespørselen inneholder EN API-nøkkel eller en klient-id For Google Maps Platform Premium-Abonnement. Du kan hente sted-Ider fra Geokoding API og Steder API (inkludert Sted Autofullfør). Hvis du vil bruke sted-Id-Er fra Sted Autofullfør, kan Du se Sted Autofullfør og Retninger. Hvis du vil ha mer informasjon om sted-Id-er, kan du se sted-ID-oversikten.
  • hvis du sender en adresse, geokoder tjenesten strengen og konverterer den til en breddegrad / lengdegradskoordinat for å beregne avstand. Denne koordinaten kan være forskjellig fra den som returneres av Geokoding API, for eksempel en bygningsinngang i stedet for sentrum.

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

    Merk: bruk av sted-Ider foretrekkes fremfor bruk av adresser eller breddegrad/lengdegradskoordinater. Bruk av koordinater vil alltid føre til at punktet blir snappet til veien nærmest disse koordinatene-som kanskje ikke er et tilgangspunkt til eiendommen , eller til og med en vei som raskt eller trygt fører til destinasjonen.
  • hvis du passerer breddegrad / lengdegrad koordinater, de de vil knipse til nærmeste vei. Passering av et sted ID er foretrukket. Hvis du passerer koordinater, må du sørge for at det ikke finnes mellomrom mellom breddegrad og lengdegrad.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • Plusskoder må formateres som en global kode eller en sammensatt kode. Format pluss koder som vist her (pluss tegn er url-rømt til %2B og mellomrom er url-rømt til %20):
    • global kode er et 4 tegn retningsnummer og 6 tegn eller lengre lokal kode (849VCWC8 + R9 er 849VCWC8%2BR9).
    • sammensatt kode er en 6 tegn eller lengre lokal kode med en eksplisitt plassering (Cwc8 + R9 Mountain View, CA, USA er CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Alternativt kan du levere et kodet sett med koordinater ved Hjelp Av Den Kodede Polylinjevalgoritmen. Dette er spesielt nyttig hvis DU har et stort antall opprinnelsespunkter, FORDI NETTADRESSEN er betydelig kortere når du bruker en kodet polylinje.
    • Kodede polylinjer må prefikses med enc: og etterfulgt av et kolon (:).For eksempel: origins=enc:gfo}EtohhU:
    • Du kan også inkludere flere kodede polylinjer, adskilt av pipetegnet (|). Eksempelvis: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:

destinations — Ett eller flere steder som skal brukes som sluttpunkt for beregning av reiseavstand og tid. Alternativene fordestinations – parameteren er de samme som fororigins – parameteren, beskrevet ovenfor.

• keyMerk: Kunder av Google Maps Platform Premium-Abonnement kan bruke ENTEN EN API-nøkkel eller en gyldig klient-ID og digital signatur i forespørsler om Avstandsmatrise. Få mer informasjon om godkjenningsparametere for Premium-Abonnementskunder.

følgende eksempel bruker breddegrad/lengdegradskoordinater til å angi målkoordinatene:

følgende eksempel bruker plusskoder til å angi målkoordinatene:

følgende eksempel viser den samme forespørselen ved hjelp av en kodet polylinje:

Valgfrie parametere

• mode(standard til driving) — Angir transportmåten som skal brukes ved beregning av avstand. Gyldige verdier og andre forespørselsdetaljer er spesifisert i Reisemodusdelen av dette dokumentet.
• language – språket for å returnere resultater.
  • Se listen over støttede språk. Google oppdaterer ofte de støttede språkene, så denne listen er kanskje ikke uttømmende.
  • Hvis language ikke er oppgitt, FORSØKER API å bruke det foretrukne språket som angitt iAccept-Language toppteksten, eller morsmålet til domenet som forespørselen sendes fra.
  • API gjør sitt beste for å gi en gateadresse som er lesbar for både brukeren og lokalbefolkningen. For å oppnå dette målet returnerer den gateadresser på det lokale språket, translitterert til et skript som kan leses av brukeren om nødvendig, og observerer det foretrukne språket. Alle andre adresser returneres på det foretrukne språket. Adressekomponenter returneres alle på samme språk, som er valgt fra den første komponenten.
  • hvis et navn ikke er tilgjengelig på det foretrukne språket, BRUKER API-EN det nærmeste treffet.
  • det foretrukne språket har liten innflytelse på settet av resultater SOM API velger å returnere, og rekkefølgen de returneres i. Geokoderen tolker forkortelser forskjellig avhengig av språk, for eksempel forkortelser for gatetyper, eller synonymer som kan være gyldige på ett språk, men ikke i et annet. For eksempel er utca og té synonymer for gate på ungarsk.

region – regionskoden, angitt som et cctld (toppnivådomene for landskode) med to tegn. De fleste ccTLD-koder er identiske MED ISO 3166-1-koder, med noen unntak. Denne parameteren vil bare påvirke, ikke helt begrense, resultatene fra geokoderen. Hvis det finnes mer relevante resultater utenfor den angitte regionen, kan de inkluderes.

• avoid — Introduserer restriksjoner på ruten. Gyldige verdier er angitt I Delen Restriksjoner i dette dokumentet. Bare en begrensning kan spesifiseres.
• units — Angir enhetssystemet som skal brukes når du uttrykker avstand som tekst. Se Delen Enhetssystemer i dette dokumentet for mer informasjon.
• arrival_time — Angir ønsket ankomsttid for transittforespørsler, i sekunder siden midnatt 1.januar 1970 UTC. Du kan angi enten departure_time eller arrival_time, men ikke begge deler. Merk at arrival_time må angis som et heltall.
• departure_time – ønsket avgangstid. Du kan angi tiden som et heltall i sekunder siden midnatt 1. januar 1970 UTC. Hvis en departure_time senere enn 9999-12-31t23:59:59.999999999 Z er spesifisert, VIL API falle tilbake departure_time til 9999-12-31T23:59:59.999999999 Z. Alternativt kan du angi en verdi av now, som setter avgangstiden til gjeldende tid (RIKTIG TIL NÆRMESTE SEKUND). Avgangstiden kan spesifiseres i to tilfeller:
  • for forespørsler der reisemodus er transitt: Du kan eventuelt angi en av departure_time eller arrival_time. Hvis ingen tid er angitt ,erdeparture_time som standard til nå (det vil si avgangstiden som standard til gjeldende tid).
  • for forespørsler der reisemodus kjører: du kan angi departure_time for å motta en rute-og turvarighet (svarfelt: duration_in_traffic) som tar hensyn til trafikkforholdene. Dette alternativet er bare tilgjengelig hvis forespørselen inneholder EN GYLDIG API-nøkkel eller en gyldig klient-id Og signatur For Google Maps Platform Premium-Abonnement. departure_time må settes til gjeldende tid eller en gang i fremtiden. Det kan ikke være i fortiden.

    Merk: hvis avgangstid ikke er spesifisert, er valg av rute og varighet basert på veinett og gjennomsnittlige tidsuavhengige trafikkforhold. Resultatene for en gitt forespørsel kan variere over tid på grunn av endringer i veinettet, oppdaterte gjennomsnittlige trafikkforhold og tjenestens distribuerte natur. Resultatene kan også variere mellom nesten tilsvarende ruter når som helst eller frekvens.

    Merk: Forespørsler Om Avstandsmatrise som angir departure_time når mode=driving er begrenset til maksimalt 100 elementer per forespørsel. Antall opprinnelser ganger antall destinasjoner definerer antall elementer.

traffic_model(standard til best_guess) – Angir forutsetningene som skal brukes ved beregning av tid i trafikken. Denne innstillingen påvirker verdien som returneres i feltet duration_in_traffic i svaret, som inneholder forventet tid i trafikken basert på historiske gjennomsnitt. Parameterentraffic_model kan bare angis for forespørsler der reisemodus er driving, og der forespørselen inneholder en departure_time, og bare hvis forespørselen inneholder EN API-nøkkel eller en Google Maps Platform Premium plan klient-id. De tilgjengelige verdiene for denne parameteren er:

• best_guess (standard) indikerer at den returnerte duration_in_traffic bør være det beste estimatet av reisetid gitt det som er kjent om både historiske trafikkforhold og live trafikk. Live trafikk blir viktigere jo nærmere departure_time er til nå.
• pessimistic indikerer at den returnerteduration_in_traffic bør være lengre enn den faktiske reisetiden på de fleste dager, selv om sporadiske dager med spesielt dårlige trafikkforhold kan overstige denne verdien.
• optimistic indikerer at den returnerteduration_in_traffic skal være kortere enn den faktiske reisetiden på de fleste dager, selv om sporadiske dager med spesielt gode trafikkforhold kan være raskere enn denne verdien.

transit_mode — Angir en eller flere foretrukne transportmåter. Denne parameteren kan bare angis for forespørsler der mode er transit. Parameteren støtter følgende argumenter:

• bus indikerer at den beregnede ruten bør foretrekke å reise med buss.
• subway indikerer at den beregnede ruten bør foretrekke reise med t-bane.
• train indikerer at den beregnede ruten bør foretrekke å reise med tog.
• tram indikerer at den beregnede ruten bør foretrekke å reise med trikk og bybane.
• rail indikerer at den beregnede ruten bør foretrekke å reise med tog, trikk, bybane og t-bane. Dette tilsvarer transit_mode=train|tram|subway.

transit_routing_preference — Angir preferanser for transittforespørsler. Ved hjelp av denne parameteren kan du forspenne alternativene som returneres, i stedet for å godta STANDARD beste rute valgt AV API. Denne parameteren kan bare angis for forespørsler der mode er transit. Parameteren støtter følgende argumenter:

• less_walking indikerer at den beregnede ruten bør foretrekke begrensede mengder gange.
• fewer_transfers indikerer at den beregnede ruten bør foretrekke et begrenset antall overføringer.

Reisemodi

for beregning av avstander, kan du angi transport mode å bruke. Som standard beregnes avstander for kjøremodus. Følgende reisemoduser støttes:

• driving (standard) angir avstandsberegning ved hjelp av veinettet.
• walking ber om avstandsberegning for å gå via gangveier & fortau (der det er tilgjengelig).
• bicycling ber om avstandsberegning for sykling via sykkelstier & foretrukne gater (der det er tilgjengelig).
• transit ber om avstandsberegning via offentlige transportruter(der det er tilgjengelig). Denne verdien kan bare angis hvis forespørselen inneholder EN API-nøkkel eller en google Maps Platform Premium plan klient-id. Hvis du setter modusen til transit kan du eventuelt angi enten en departure_time eller en arrival_time. Hvis ingen tid er angitt ,erdeparture_time som standard til nå (det vil si avgangstiden som standard til gjeldende tid). Du kan også eventuelt inkludere en transit_mode og / eller en transit_routing_preference.

Trafikkinformasjon

Trafikkinformasjon brukes når alle følgende gjelder (dette er betingelsene som kreves for å motta duration_in_traffic – feltet I Avstandsmatrisen):

• reisen mode parameteren er driving, eller er ikke spesifisert (driving er standard reisemodus).
• forespørselen inneholder en gyldigdeparture_time parameter. departure_time kan settes til gjeldende tid eller en gang i fremtiden. Det kan ikke være i fortiden.

Eventuelt kan du inkludere parameteren traffic_model for å angi forutsetningene som skal brukes ved beregning av tid i trafikken.

FØLGENDE URL initierer en Avstandsmatriseforespørsel for kjøreavstander mellom Boston, MA eller Charlestown, MA og Lexington, MA og Concord, MA. Forespørselen inkluderer en avgangstid, som oppfyller alle kravene for å returnereduration_in_traffic – feltet I Avstandsmatrisens svar.

Restriksjoner

Avstander kan beregnes som overholder visse restriksjoner. Begrensninger er angitt ved bruk av parameteren avoid, og et argument til den parameteren som angir begrensningen som skal unngås. Følgende begrensninger støttes:

• avoid=tolls

avoid=highwaysavoid=ferriesavoid=indoor

* merk: tillegg av restriksjoner utelukker ikke ruter som inkluderer begrenset funksjon; det skjevheter resultatet til gunstigere ruter.

Enhetssystemer

Avstandsmatriseresultatene inneholder text innen distance felt for å angi avstanden til den beregnede ruten. Enhetssystemet som skal brukes kan spesifiseres:

• units=metric (standard) returnerer avstander i kilometer og meter.
• units=imperial returnerer avstander i miles og føtter.

* Merk: denne enhetens systeminnstilling påvirker baretext som vises idistance – feltene. distance feltene inneholder også values som alltid uttrykkes i meter.

Svar På Avstand MATRISE API-spørringer returneres i formatet angitt medoutput flagget i URL-forespørselens bane.

To EKSEMPLER PÅ HTTP-forespørsler er vist nedenfor, og ber om avstand og varighet fra Vancouver, BC, Canada og Fra Seattle, WA, USA, Til San Francisco, CA, USA og Til Victoria, BC, Canada.

denne forespørselen demonstrerer ved hjelp AV jsonoutput flagget:

denne forespørselen demonstrerer VED HJELP AV XMLoutput flagg:

denne forespørselen vil returnere fire elementer – to opprinnelser ganger to destinasjoner:

resultatene returneres i rader, hver rad inneholder en opprinnelse parret med hver destinasjon.

du kan teste DETTE ved å skrive INN NETTADRESSEN i nettleseren din(pass på å erstatte YOUR_API_KEY med DIN FAKTISKE API-nøkkel).

Velg fanene nedenfor for å se EKSEMPLER PÅ JSON-og XML-svar.

resten av denne dokumentasjonen vil bruke json syntaks.

Avstandsmatriseresponselementer

Avstandsmatriseresponser inneholder følgende rotelementer:

• status inneholder metadata på forespørselen. Se Statuskoder nedenfor.
• origin_addresses inneholder en rekke adresser som returneres AV API fra den opprinnelige forespørselen. Disse er formatert av geokoderen og lokalisert i henhold til parameterenlanguage passert med forespørselen.
• destination_addresses inneholder en rekke adresser som returneres AV API fra den opprinnelige forespørselen. Som med origin_addresses, er disse lokalisert hvis det er hensiktsmessig.

rowsinneholder en matrise avelements, som igjen hver inneholder enstatusdurationogdistanceelement.

Statuskoder

status feltene i svarobjektet inneholder status for forespørselen, og kan inneholde nyttig feilsøkingsinformasjon. Distance Matrix API returnerer et toppnivå statusfelt, med informasjon om forespørselen generelt, samt et statusfelt for hvert elementfelt, med informasjon om den aktuelle origin-destinasjonsparingen.

statuskoder På Toppnivå

• OK indikerer at svaret inneholder en gyldig result.
• INVALID_REQUEST indikerer at den angitte forespørselen var ugyldig.
• MAX_ELEMENTS_EXCEEDED angir at produktet av opprinnelse og mål overskrider grensen per spørring.
• MAX_DIMENSIONS_EXCEEDED angir at antall opprinnelser eller mål overskrider grensen per spørring.
• OVER_DAILY_LIMIT indikerer noe av følgende:
  • API-nøkkelen mangler eller er ugyldig.
  • Fakturering er ikke aktivert på kontoen din.
  • en selvpålagt brukstak er overskredet.
  • den angitte betalingsmåten er ikke lenger gyldig (for eksempel har et kredittkort utløpt).

  Se Kart FAQ for å lære hvordan du løser dette.

• OVER_QUERY_LIMIT indikerer at tjenesten har mottatt for mange forespørsler fra søknaden din innen den tillatte tidsperioden.
• REQUEST_DENIED indikerer at tjenesten nektet Bruk Av Avstandsmatrisetjenesten av søknaden din.
• UNKNOWN_ERROR angir At en Forespørsel Om Avstandsmatrise ikke kunne behandles på grunn av en serverfeil. Forespørselen kan lykkes hvis du prøver igjen.

Elementnivå statuskoder

• OK indikerer at svaret inneholder en gyldig result.
• NOT_FOUND angir at opprinnelsen og / eller målet for denne sammenkoblingen ikke kunne geokodes.
• ZERO_RESULTS indikerer at ingen rute ble funnet mellom opprinnelse og destinasjon.
• MAX_ROUTE_LENGTH_EXCEEDED indikerer at den forespurte ruten er for lang og ikke kan behandles.

Feilmeldinger

når statuskoden på toppnivå er noe annet enn OK, kan det være et ekstraerror_message – felt innenfor Avstandsmatriseresponsobjektet. Dette feltet inneholdermer detaljert informasjon om årsakene bak den gitte statuskoden.

Merk: dette feltet er ikke garantert å være alltid til stede, og dets innhold kan endres.

Rader

Når Distance Matrix API returnerer resultater, plasserer den dem i EN JSON rows matrise. Selv om ingen resultater returneres (for eksempel når opprinnelsen og/eller destinasjonene ikke finnes), returnerer den fortsatt en tom matrise. XML-svar består av null eller mer <row> elementer.

Rader er bestilt i henhold til verdiene iorigin parameteren for forespørselen. Hver rad tilsvarer en origin, og hver element innenfor den raden tilsvarer en sammenkobling av origin med endestination – verdi.

Hver row matrise inneholder en eller flereelement oppføringer, som igjen inneholder informasjon om en enkelt origin-destination paring.

Elementer

informasjonen om hver origin-destination-paring returneres i enelement – oppføring. An element inneholder følgende felt:

• status: se Statuskoder for en liste over mulige statuskoder.

duration: hvor lang tid det tar å reise denne ruten, uttrykt i sekunder (value – feltet) og som text. Tekstrepresentasjonen er lokalisert i henhold til spørringenslanguage parameter.

• duration_in_traffic: hvor lang tid det tar å reise denne ruten, basert på nåværende og historiske trafikkforhold. Setraffic_model request-parameteren for alternativene du kan bruke til å be om at den returnerte verdien er optimistisk, pessimistisk eller et best-guess estimat. Varigheten uttrykkes i sekunder (value – feltet) og som text. Tekstrepresentasjonen er lokalisert i henhold til spørringenslanguage parameter. Varigheten i trafikken returneres bare hvis alle følgende er sanne:

  • forespørselen inneholder en departure_time parameter.
  • forespørselen inkluderer en GYLDIG API-nøkkel, eller en Gyldig google Maps Platform Premium plan klient-id og signatur.
  • Trafikkforholdene er tilgjengelige for den valgte ruten.
  • parameterenmode er satt til driving.

distance: den totale avstanden til denne ruten, uttrykt i meter (value) og som text. Tekstverdien bruker enhetssystemet som er angitt med parameterenunit for den opprinnelige forespørselen, eller opprinnelsesområdet.

• fare: hvis den finnes, inneholder den totale billettprisen (det vil si de totale billettkostnadene) på denne ruten. Denne egenskapen returneres kun for transittforespørsler og kun for transittleverandører der prisinformasjon er tilgjengelig. Informasjonen inkluderer:
  • currency: EN ISO 4217 valutakode som angir valutaen som beløpet er uttrykt i.
  • value: det totale billettbeløpet, i valutaen som er angitt ovenfor.
  • text: den totale billettprisen, formatert på det forespurte språket.

Nedenfor er et eksempel på enelement som inneholder prisinformasjon:

sensorparameteren

Google Maps API krevde tidligere at du tok medsensor parameter for å indikere om applikasjonen din brukte asensor til å bestemme brukerens plassering. Denne parameteren er ikke lengernødvendig.