introduktion

Afstandsmatricen API er en tjeneste, der giver rejseafstand og tid til en matrice af oprindelse og destinationer. API ‘ en returnerer oplysninger baseret på den anbefalede rute mellem start-og slutpunkter, som beregnet af Google Maps API, og består af rækker, der indeholder duration og distance værdier for hvert par.

Bemærk: Denne service returnerer ikke detaljerede ruteoplysninger. Ruteinformation kan fås ved at overføre den ønskede enkelt oprindelse og destination til Directions API.

før du begynder

dette dokument er beregnet til udviklere, der ønsker at beregne rejseafstand og tid mellem et antal punkter i maps leveret af en af Google Maps API ‘ erne. Det giver en introduktion til at bruge API og referencemateriale på de tilgængelige parametre.

før du begynder at udvikle med AFSTANDSMATRICEN API, skal du gennemgå godkendelseskravene (du har brug for en API-nøgle) og API-brugs-og faktureringsoplysningerne (du skal aktivere fakturering på dit projekt).

anmodninger om Afstandsmatrice

en API-anmodning om Afstandsmatrice tager følgende form:

hvoroutputFormat kan være en af følgende værdier:

• json (anbefalet), angiver output i JavaScript Object Notation (JSON); eller
• xml, angiver output som JML.

Bemærk: URL ‘ er skal være korrekt kodet for at være gyldige og er begrænset til 8192 tegn for alle internettjenester. Vær opmærksom på denne grænse, når du konstruerer dine URL ‘ er. Bemærk, at forskellige bro.sere, fuldmagter og servere også kan have forskellige URL-tegngrænser.

HTTPS eller HTTP

sikkerhed er vigtig, og HTTPS anbefales, når det er muligt, især til applikationer, der indeholder følsomme brugerdata, såsom en brugers placering, i anmodninger. Brug af HTTPS-kryptering gør din applikation mere sikker og mere modstandsdygtig over for snooping eller manipulation.

Hvis HTTPS ikke er muligt, skal du bruge:

Anmod om parametre

visse parametre er påkrævet, mens andre er valgfri. Som det er standard i URL ‘ er, adskilles alle parametre ved hjælp af tegnet ampersand (&). Alle reserverede tegn (for eksempel plustegnet “+”) skal være URL-kodet.Listen over parametre og deres mulige værdier er opregnet nedenfor.

nødvendige parametre

• origins — udgangspunktet for beregning af rejseafstand og tid. Du kan angive et eller flere steder adskilt af pipe-tegnet (|) i form af et sted-ID, en adresse eller breddegrad/længdegradskoordinater:
  • hvis du angiver et sted-ID, skal du præfiksere det med place_id:. Du kan kun angive et sted-ID, hvis anmodningen indeholder en API-nøgle eller et Google Maps-Platform Premium Plan-klient-ID. Du kan hente place id ‘ er fra Geocoding API og Places API (herunder Place autofuldførelse). For et eksempel ved hjælp af sted-id ‘ er fra sted autofuldførelse, Se sted Autofuldførelse og retninger. For mere om sted-id’ er, Se oversigt over Sted-ID.
  • hvis du sender en adresse, geokoder tjenesten strengen og konverterer den til en breddegrad/længdegradskoordinat for at beregne afstanden. Denne koordinat kan være forskellig fra den, der returneres af Geocoding API, for eksempel en bygningsindgang snarere end dens centrum.

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

    Bemærk: Brug af sted-id ‘ er foretrækkes frem for brug af adresser eller breddegrad/længdegradskoordinater. Brug af koordinater vil altid resultere i, at punktet bliver snappet til vejen nærmest disse koordinater – hvilket måske ikke er et adgangspunkt til ejendommen eller endda en vej, der hurtigt eller sikkert fører til destinationen.
  • hvis du passerer breddegrad / længdegradskoordinater, de de klikker på den nærmeste vej. At passere et sted-ID foretrækkes. Hvis du passerer koordinater, skal du sikre dig, at der ikke er plads mellem breddegrad og længdegrad.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • Plus-koder skal formateres som en global kode eller en sammensat kode. Format plus koder som vist her (plus tegn er url-escaped til %2B og mellemrum er url-escaped til %20):
    • global kode er en 4 tegn områdekode og 6 tegn eller længere lokal kode (849VCVC8+R9 er 849VCWC8%2BR9).sammensat kode er en 6 tegn eller længere lokal kode med en eksplicit placering (CVC8+R9 bjergudsigt, CA, USA er CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Alternativt kan du levere et kodet sæt koordinater ved hjælp af den kodede Polylinealgoritme. Dette er især nyttigt, hvis du har et stort antal oprindelsespunkter, fordi URL ‘ en er betydeligt kortere, når du bruger en kodet polylinje.
    • kodede polyliner skal være præfikset medenc: og efterfulgt af et kolon (:).For eksempel: origins=enc:gfo}EtohhU:
    • du kan også inkludere flere kodede polyliner, adskilt af rørtegnet (|). Eksempel: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — et eller flere steder, der skal bruges som slutpunkt til beregning af rejseafstand og tid. Indstillingerne for parameterendestinations er de samme som for parameterenorigins, beskrevet ovenfor.
• key — din applikations API-nøgle. Denne nøgle identificerer din ansøgning med henblik på kvoteforvaltning. Lær hvordan du får en nøgle.

  Bemærk: Google Maps Platform Premium Plan-kunder kan bruge enten en API-nøgle eller et gyldigt klient-ID og digital signatur i dine anmodninger om Afstandsmatrice. Få flere oplysninger om godkendelsesparametre for Premium Plan-kunder.

følgende eksempel bruger breddegrad / længdegradskoordinater til at specificere destinationskoordinaterne:

følgende eksempel bruger plus-koder til at specificere destinationskoordinaterne:

følgende eksempel viser den samme anmodning ved hjælp af en kodet polylinje:

valgfrie parametre

• mode (standard driving) — angiver den transportform, der skal bruges ved beregning af afstand. Gyldige værdier og andre anmodningsoplysninger er angivet i afsnittet Rejsetilstande i dette dokument.
• language — sproget til at returnere resultater.
  • se listen over understøttede sprog. Google opdaterer ofte de understøttede sprog, så denne liste er muligvis ikke udtømmende.
  • hvislanguage ikke leveres, forsøger API at bruge det foretrukne sprog som angivet iAccept-Language header eller modersmålet for det domæne, hvorfra anmodningen sendes.
  • API ‘ en gør sit bedste for at give en adresse, der kan læses for både brugeren og lokalbefolkningen. For at nå dette mål returnerer den gadeadresser på det lokale sprog, translittereret til et script, der kan læses af brugeren, hvis det er nødvendigt, og observerer det foretrukne sprog. Alle andre adresser returneres på det foretrukne sprog. Adressekomponenter returneres alle på samme sprog, som vælges fra den første komponent.
  • hvis et navn ikke er tilgængeligt på det foretrukne sprog, bruger API det nærmeste match.
  • det foretrukne sprog har en lille indflydelse på det sæt resultater, som API ‘ en vælger at returnere, og i hvilken rækkefølge de returneres. Geocoderen fortolker forkortelser forskelligt afhængigt af sprog, såsom forkortelser for gadetyper eller synonymer, der kan være gyldige på et sprog, men ikke på et andet. For eksempel er utca og T-kurr synonymer for gade på ungarsk.
• region — regionskoden, angivet som en ccTLD (landekode topdomæne) to-tegn værdi. De fleste ccTLD-koder er identiske med ISO 3166-1-koder med nogle undtagelser. Denne parameter vil kun påvirke, ikke fuldt ud begrænse, resultater fra geocoderen. Hvis der findes mere relevante resultater uden for det angivne område, kan de medtages.
• avoid — introducerer begrænsninger for ruten. Gyldige værdier er angivet i afsnittet begrænsninger i dette dokument. Kun en begrænsning kan specificeres.
• units — angiver det enhedssystem, der skal bruges, når afstanden udtrykkes som tekst. Se afsnittet enhedssystemer i dette dokument for at få flere oplysninger.
• arrival_time — angiver det ønskede ankomsttidspunkt for transitanmodninger i sekunder siden midnat den 1.januar 1970 UTC. Du kan angive enten departure_timeellerarrival_time, men ikke begge dele. Bemærk, at arrival_time skal angives som et heltal.
• departure_time — det ønskede afgangstidspunkt. Du kan angive tiden som et heltal i sekunder siden midnat den 1.januar 1970 UTC. Hvis en departure_time senere end 9999-12-31T23:59:59.9999999999 er angivet, vil API ‘ en falde tilbage departure_time til 9999-12-31T23:59:59.999999999 af now, som indstiller afgangstiden til den aktuelle tid (korrekt til nærmeste sekund). Afgangstidspunktet kan angives i to tilfælde:
  • for anmodninger, hvor rejsetilstanden er transit: Du kan eventuelt angive en af departure_timeeller arrival_time. Hvis ingen af tidene er angivet, er departure_time standard til nu (dvs.afgangstiden er standard til den aktuelle tid).
  • for anmodninger, hvor rejsetilstanden kører: du kan angive departure_timefor at modtage en rute og turvarighed (svarfelt: duration_in_traffic), der tager hensyn til trafikforholdene. Denne indstilling er kun tilgængelig, hvis anmodningen indeholder en gyldig API-nøgle eller et gyldigt Google Maps-Platform Premium Plan-klient-ID og-signatur. departure_time skal indstilles til den aktuelle tid eller et stykke tid i fremtiden. Det kan ikke være i fortiden. Bemærk: Hvis afgangstid ikke er angivet, er valg af rute og varighed baseret på vejnet og gennemsnitlige tidsuafhængige trafikforhold. Resultaterne for en given anmodning kan variere over tid på grund af ændringer i vejnettet, opdaterede gennemsnitlige trafikforhold og tjenestens distribuerede karakter. Resultaterne kan også variere mellem næsten ækvivalente ruter til enhver tid eller frekvens.

    Bemærk: anmodninger om Afstandsmatrice, der specificerer departure_timenår mode=driving er begrænset til maksimalt 100 elementer pr. Antallet af oprindelser gange antallet af destinationer definerer antallet af elementer.

• traffic_model(standard best_guess) — angiver de antagelser, der skal bruges ved beregning af tid i trafik. Denne indstilling påvirker den værdi, der returneres i feltetduration_in_traffic i svaret, som indeholder den forudsagte tid i trafikken baseret på historiske gennemsnit. Parameterentraffic_modelkan kun angives for anmodninger, hvor rejsetilstanden er driving, og hvor anmodningen indeholder et departure_time, og kun hvis anmodningen indeholder en API-nøgle eller et Google Maps Platform Premium Plan client ID. De tilgængelige værdier for denne parameter er:
  • best_guess(standard) angiver, at den returnerededuration_in_traffic skal være det bedste skøn over rejsetid givet hvad der er kendt om både historiske trafikforhold og levende trafik. Live trafik bliver vigtigere, jo tættere departure_time er til nu.
  • pessimisticangiver, at den returnerededuration_in_traffic skal være længere end den faktiske rejsetid på de fleste dage, selvom lejlighedsvise dage med særligt dårlige trafikforhold kan overstige denne værdi.
  • optimisticangiver, at den returnerededuration_in_traffic skal være kortere end den faktiske rejsetid på de fleste dage, selvom lejlighedsvise dage med særligt gode trafikforhold kan være hurtigere end denne værdi.
• transit_mode — angiver en eller flere foretrukne transportformer. Denne parameter kan kun angives for anmodninger, hvor modeer transit. Parameteren understøtter følgende argumenter:
  • bus angiver, at den beregnede rute bør foretrække rejse med bus.
  • subway angiver, at den beregnede rute bør foretrække rejse med metro.
  • train angiver, at den beregnede rute bør foretrække rejse med tog.
  • tram angiver, at den beregnede rute bør foretrække rejse med sporvogn og letbane.
  • rail angiver, at den beregnede rute bør foretrække rejse med tog, sporvogn, letbane og metro. Dette svarer til transit_mode=train|tram|subway.
• transit_routing_preference — angiver præferencer for transitanmodninger. Ved hjælp af denne parameter kan du bias de returnerede indstillinger i stedet for at acceptere den standard bedste rute valgt af API ‘ en. Denne parameter kan kun angives for anmodninger, hvor modeer transit. Parameteren understøtter følgende argumenter:
  • less_walking angiver, at den beregnede rute bør foretrække begrænsede mængder gang.
  • fewer_transfers angiver, at den beregnede rute bør foretrække et begrænset antal overførsler.

Rejsetilstande

til beregning af afstande kan du angive transporten mode at bruge. Som standard beregnes afstande for køremodus. Følgende rejsetilstande understøttes:

• driving (standard) angiver afstandsberegning ved hjælp af vejnettet.
• walking anmoder om afstandsberegning for at gå via gangstier& fortove (hvor det er tilgængeligt).
• bicycling anmoder om afstandsberegning til cykling via cykelstier & foretrukne gader (hvor tilgængelig).
• transit anmoder om afstandsberegning via offentlige transitruter (hvor det er muligt). Denne værdi kan kun angives, hvis anmodningen indeholder en API-nøgle eller et Google Maps Platform Premium Plan client ID. Hvis du indstiller tilstanden til transitkan du eventuelt angive enten endeparture_timeeller enarrival_time. Hvis ingen af tidene er angivet, er departure_time standard til nu (dvs.afgangstiden er standard til den aktuelle tid). Du kan også eventuelt inkludere en transit_mode og/eller en transit_routing_preference.

trafikinformation

trafikinformation bruges, når alle følgende gælder (disse er de betingelser, der kræves for at modtageduration_in_traffic felt i Afstandsmatricen svar):

• rejsemode parameter erdriving, eller er ikke angivet (driving er standard rejsetilstand).
• Anmodningen indeholder en gyldigdeparture_time parameter. departure_time kan indstilles til den aktuelle tid eller et stykke tid i fremtiden. Det kan ikke være i fortiden.

Valgfrit kan du medtage parameterentraffic_model i din anmodning om at specificere de antagelser, der skal bruges ved beregning af tid i trafik.

følgende URL indleder en anmodning om Afstandsmatrice for kørselsafstande mellem Boston, MA og Concord, MA. Anmodningen inkluderer en afgangstid, der opfylder alle kravene til at returnere duration_in_traffic – feltet i Afstandsmatricen svar.

begrænsninger

afstande kan beregnes, der overholder visse begrænsninger. Begrænsninger er angivet ved brug af parameteren avoid og et argument til denne parameter, der angiver den begrænsning, der skal undgås. Følgende begrænsninger understøttes:

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

* bemærk: tilføjelsen af begrænsninger udelukker ikke ruter, der inkluderer den begrænsede funktion; det forstyrrer resultatet til mere gunstige ruter.

enhedssystemer

Afstandsmatriceresultater indeholdertext inden fordistance felter for at angive afstanden til den beregnede rute. Det enhedssystem, der skal bruges, kan specificeres:

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

* Bemærk: Denne enhedssystemindstilling påvirker kuntext vises inden fordistance felter. Felternedistance indeholder ogsåvalues som altid udtrykkes i meter.

Afstandsmatrice svar

svar på AFSTANDSMATRICE API-forespørgsler returneres i det format, der er angivet medoutput flag inden for URL-anmodningens sti.

to eksempler på HTTP-anmodninger er vist nedenfor, der anmoder om afstand og varighed fra Vancouver, BC, Canada og fra Seattle, USA, til San Francisco, CA, USA og til Victoria, BC, Canada.

denne anmodning demonstrerer ved hjælp af JSONoutput flag:

denne anmodning viser ved hjælp afoutput flag:

denne anmodning vil returnere fire elementer – to oprindelser gange to destinationer:

resultaterne returneres i rækker, hver række indeholder en oprindelse parret med hver destination.

Du kan teste dette ved at indtaste URL ‘ en i din internetsøgemaskine (sørg for at erstatte YOUR_API_KEY med din faktiske API-nøgle).

Vælg fanerne nedenfor for at se eksemplerne på JSON-og HML-svarene.

resten af denne dokumentation vil bruge JSON syntaks.

Afstandsmatrice responselementer

Afstandsmatrice responselementer indeholder følgende rodelementer:

• status indeholder metadata på anmodningen. Se statuskoder nedenfor.
• origin_addresses indeholder en række adresser som returneret af API fra din oprindelige anmodning. Disse er formateret af geocoderen og lokaliseret i henhold til language parameter bestået med anmodningen.
• destination_addresses indeholder en række adresser som returneret af API fra din oprindelige anmodning. Som med origin_addresses er disse lokaliserede, hvis det er relevant.
• rows indeholder et array af elements, som igen hver indeholder en statusduration og distance element.

statuskoder

status felter inden for svarobjektet indeholder status for anmodningen og kan indeholde nyttige fejlfindingsoplysninger. Afstandsmatricen API returnerer et statusfelt på øverste niveau med oplysninger om anmodningen generelt samt et statusfelt for hvert elementfelt med oplysninger om den pågældende parring mellem oprindelse og destination.

statuskoder på topniveau

• OK angiver, at svaret indeholder et gyldigt result.
• INVALID_REQUEST angiver, at den angivne anmodning var ugyldig.
• MAX_ELEMENTS_EXCEEDED angiver, at produktet af oprindelse og destinationer overstiger grænsen pr.forespørgsel.
• MAX_DIMENSIONS_EXCEEDED angiver, at antallet af oprindelser eller destinationer overstiger grænsen pr.forespørgsel.
• OVER_DAILY_LIMIT angiver et af følgende:
  • API-nøglen mangler eller er ugyldig.
  • fakturering er ikke aktiveret på din konto.
  • et selvpålagt brugsloft er overskredet.
  • den angivne betalingsmetode er ikke længere gyldig (for eksempel er et kreditkort udløbet).

  se Ofte Stillede Spørgsmål om kort for at lære, hvordan du løser dette.

• OVER_QUERY_LIMIT angiver, at tjenesten har modtaget for mange anmodninger fra din ansøgning inden for den tilladte tidsperiode.
• REQUEST_DENIED angiver, at tjenesten nægtede brug af Afstandsmatricetjenesten af din ansøgning.
• UNKNOWN_ERROR angiver, at en Afstandsmatriceanmodning ikke kunne behandles på grund af en serverfejl. Anmodningen kan lykkes, hvis du prøver igen.

elementniveau statuskoder

• OK angiver, at svaret indeholder et gyldigtresult.
• NOT_FOUND angiver, at oprindelsen og / eller destinationen for denne parring ikke kunne geokodes.
• ZERO_RESULTS angiver, at der ikke kunne findes nogen rute mellem oprindelse og destination.
• MAX_ROUTE_LENGTH_EXCEEDED angiver, at den ønskede rute er for lang og ikke kan behandles.

fejlmeddelelser

Når statuskoden på øverste niveau er anden endOK, kan der være et yderligereerror_message felt inden for afstandsmatricen svarobjekt. Dette felt indeholdermere detaljerede oplysninger om årsagerne til den givne statuskode.

Bemærk: Dette felt er ikke garanteret at være altid til stede, og dets indhold kan ændres.

rækker

når Afstandsmatricen API returnerer resultater, placerer den dem inden for et JSONrows array. Selvom der ikke returneres resultater (som når oprindelsen og/eller destinationerne ikke findes), returnerer den stadig et tomt array. <row> elementer.

rækker bestilles i henhold til værdierne i origin parameter for anmodningen. Hver række svarer til en oprindelse, og hver element inden for denne række svarer til en parring af oprindelsen med en destination værdi.

hverrow array indeholder en eller flereelement poster, som igen indeholder oplysninger om en enkelt oprindelse-destinationsparring.

Elements

oplysningerne om hver origin-destination parring returneres i enelement post. En element indeholder følgende felter:

• status: se statuskoder for en liste over mulige statuskoder.
• duration: hvor lang tid det tager at rejse denne rute, udtrykt i sekunder (feltet value) og som text. Tekstrepræsentationen er lokaliseret i henhold til forespørgslens language parameter.

• duration_in_traffic: hvor lang tid det tager at rejse denne rute, baseret på aktuelle og historiske trafikforhold. Se traffic_model Anmod om de indstillinger, du kan bruge til at anmode om, at den returnerede værdi er optimistisk, pessimistisk eller et estimat for bedste gæt. Varigheden udtrykkes i sekunder (feltet value) og som text. Tekstrepræsentationen er lokaliseret i henhold til forespørgslens language parameter. Varigheden i trafikken returneres kun, hvis alle følgende er sande:

  • Anmodningen indeholder en departure_time parameter.
  • Anmodningen indeholder en gyldig API-nøgle eller et gyldigt Google Maps Platform Premium Plan client ID og signatur.
  • trafikforhold er tilgængelige for den ønskede rute.
  • mode parameteren er indstillet tildriving.
• distance: den samlede afstand af denne rute, udtrykt i meter (value) og somtext. Tekstværdien bruger det enhedssystem, der er angivet med parameteren unit for den oprindelige anmodning eller oprindelsesregionen.
• fare: hvis den er til stede, indeholder den samlede billetpris (det vil sige de samlede billetomkostninger) på denne rute. Denne ejendom returneres kun for transitanmodninger og kun for transitudbydere, hvor billetoplysninger er tilgængelige. Oplysningerne inkluderer:
  • currency: EN ISO 4217-valutakode, der angiver den valuta, som beløbet udtrykkes i.
  • value: det samlede billetbeløb i den ovenfor angivne valuta.
  • text: det samlede billetbeløb, formateret på det ønskede sprog.

nedenfor er et eksempel på enelement indeholdende billetoplysninger:

sensorparameteren

Google Maps API krævede tidligere, at du inkluderedesensor parameter for at angive, om din applikation brugte asensor til at bestemme brugerens placering. Denne parameter er ikke længerekræves.