Introducere

API-ul Distance Matrix este un serviciu care oferă distanța și timpul de călătorie pentru o matrice de origini și destinații. API-ul returnează informații pe baza rutei recomandate între punctele de început și de sfârșit, calculată de API-ul Google Maps, și constă din rânduri care conțin duration și distance valori pentru fiecare pereche.

Notă: Acest serviciu nu returnează informații detaliate despre traseu. Informațiile despre traseu pot fi obținute prin trecerea originii și destinației unice dorite către API-ul Direcții.

înainte de a începe

acest document este destinat dezvoltatorilor care doresc să calculeze distanța și timpul de călătorie între un număr de puncte din hărți furnizate de unul dintre API-urile Google Maps. Acesta oferă o introducere în utilizarea materialului API și de referință cu privire la parametrii disponibili.

înainte de a începe dezvoltarea cu API-ul Distance Matrix, examinați cerințele de autentificare (aveți nevoie de o cheie API) și informațiile de utilizare și facturare API (trebuie să activați facturarea pentru proiectul dvs.).

cereri matrice distanță

o cerere API matrice distanță ia următoarea formă:

unde outputFormat poate fi oricare dintre următoarele valori:

• json (recomandat), indică ieșire în JavaScript Object Notation (JSON); sau
• xml, indică ieșirea ca XML.

notă: URL-urile trebuie să fie codificate corespunzător pentru a fi valide și sunt limitate la 8192 de caractere pentru toate serviciile web. Fiți conștienți de această limită atunci când vă construiți adresele URL. Rețineți că diferite browsere, proxy-uri și servere pot avea și limite de caractere URL diferite.

HTTPS sau HTTP

Securitatea este importantă și HTTPS este recomandat ori de câte ori este posibil, în special pentru aplicațiile care includ date sensibile ale utilizatorului, cum ar fi locația unui utilizator, în cereri. Utilizarea criptării HTTPS face ca aplicația dvs. să fie mai sigură și mai rezistentă la snooping sau manipulare.

dacă HTTPS nu este posibil, pentru a accesa API – ul matricei de distanță prin HTTP, utilizați:

parametrii de solicitare

anumiți parametri sunt necesari, în timp ce alții sunt opționali. Așa cum este standard în URL-uri, toți parametrii sunt separați folosind caracterul ampersand (&). Toate caracterele rezervate (de exemplu semnul plus „+”) trebuie să fie codificate URL.Lista parametrilor și valorile posibile ale acestora sunt enumerate mai jos.

parametrii necesari

• origins — punctul de plecare pentru calcularea distanței și timpului de deplasare. Puteți furniza una sau mai multe locații separate prin caracterul pipe (|), sub forma unui ID loc, a unei adrese sau a coordonatelor latitudine/longitudine:
  • Dacă furnizați un ID loc, trebuie să îl prefixați cu place_id:. Puteți specifica un ID de locație numai dacă solicitarea include o cheie API sau un ID Client plan Premium Google Maps Platform. Puteți prelua ID-urile de loc din API-ul geocodare și API-ul locații (inclusiv completarea automată a locului). Pentru un exemplu de utilizare a ID-urilor de locație din Completarea automată a locului, consultați completarea automată a locului și indicații de orientare. Pentru mai multe informații despre ID-urile de locație, consultați prezentarea generală a ID-ului de locație.
  • dacă treceți o adresă, serviciul geocodifică șirul și îl convertește într-o coordonată latitudine/longitudine pentru a calcula distanța. Această coordonată poate fi diferită de cea returnată de API-ul de geocodificare, de exemplu o intrare în clădire, mai degrabă decât centrul acesteia.

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

    Notă: Utilizarea ID-urilor de locație este preferată față de utilizarea adreselor sau a coordonatelor de latitudine/longitudine. Folosind coordonatele va duce întotdeauna la punctul fiind rupt la drumul cel mai apropiat de aceste coordonate – care nu poate fi un punct de acces la proprietate, sau chiar un drum care va duce rapid sau în condiții de siguranță la destinație.
  • dacă treci coordonatele latitudine / longitudine, ei se vor fixa la cel mai apropiat drum. Trecerea unui ID de loc este preferată. Dacă treceți coordonatele, asigurați-vă că nu există spațiu între valorile de latitudine și longitudine.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • codurile Plus trebuie formatate ca un cod global sau un cod compus. Format plus coduri așa cum se arată aici (plus semne sunt URL-a scăpat la %2B și spațiile sunt URL-a scăpat la %20):
    • codul global este un cod de zonă de 4 caractere și 6 caractere sau cod local mai lung (849VCWC8+R9 este 849VCWC8%2BR9).
    • codul compus este un cod local de 6 caractere sau mai lung, cu o locație explicită (CWC8+R9 Mountain View, CA, SUA esteCWC8%2BR9%20Mountain%20View%20CA%20USA).
  • alternativ, puteți furniza un set codificat de coordonate folosind algoritmul polilinie codificat. Acest lucru este util în special dacă aveți un număr mare de puncte de origine, deoarece adresa URL este semnificativ mai scurtă atunci când utilizați o polilinie codificată.
    • polilinele codificate trebuie prefixate cuenc: și urmate de două puncte (:).De exemplu: origins=enc:gfo}EtohhU:
    • puteți include, de asemenea, mai multe polilinii codificate, separate prin caracterul conductei (|). De exemplu: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — una sau mai multe locații de utilizat ca punct final pentru calcularea distanței și timpului de deplasare. Opțiunile pentru parametruldestinations sunt aceleași ca și pentru parametrulorigins, descris mai sus.
• key — cheia API a aplicației dvs. Această cheie identifică cererea dvs. în scopul gestionării cotelor. Aflați cum să obțineți o cheie.

  notă: Clienții Google Maps Platform Premium Plan pot utiliza fie o cheie API, fie un ID de client valid și o semnătură digitală, în cererile dvs. de matrice la distanță. Obțineți mai multe informații despre parametrii de autentificare pentru clienții Premium Plan.

următorul exemplu folosește coordonatele latitudine / longitudine pentru a specifica coordonatele destinației:

următorul exemplu folosește coduri plus pentru a specifica coordonatele destinației:

următorul exemplu arată aceeași solicitare utilizând o polilinie codificată:

parametri opționali

• mode (implicit ladriving) — specifică modul de transport de utilizat la calcularea distanței. Valorile valide și alte detalii de solicitare sunt specificate în secțiunea Moduri de deplasare a acestui document.
• language — limba în care să se întoarcă rezultatele.
  • vedeți lista limbilor acceptate. Google actualizează adesea limbile acceptate, deci este posibil ca această listă să nu fie exhaustivă.
  • dacălanguage nu este furnizat, API-ul încearcă să utilizeze limba preferată așa cum este specificat înAccept-Language antet, sau limba maternă a domeniului din care este trimisă cererea.
  • API-ul face tot posibilul pentru a oferi o adresă stradală care poate fi citită atât pentru utilizator, cât și pentru localnici. Pentru a atinge acest obiectiv, returnează adresele stradale în limba locală, transliterate într-un script care poate fi citit de utilizator, dacă este necesar, respectând limba preferată. Toate celelalte adrese sunt returnate în limba preferată. Componentele adresei sunt toate returnate în aceeași limbă, care este aleasă din prima componentă.
  • dacă un nume nu este disponibil în limba preferată, API-ul folosește cea mai apropiată potrivire.
  • limba preferată are o mică influență asupra setului de rezultate pe care API-ul alege să le returneze și asupra ordinii în care sunt returnate. Geocoderul interpretează abrevierile diferit în funcție de limbă, cum ar fi abrevierile pentru tipurile de stradă sau sinonime care pot fi valabile într-o limbă, dar nu în alta. De exemplu, utca și T ectr sunt sinonime pentru stradă în limba maghiară.
• region — codul de regiune, specificat ca ccTLD (domeniu de nivel superior cod de țară) valoare de două caractere. Majoritatea codurilor ccTLD sunt identice cu codurile ISO 3166-1, cu unele excepții. Acest parametru va influența, nu va restricționa complet, rezultatele geocoderului. Dacă există rezultate mai relevante în afara regiunii specificate, acestea pot fi incluse.
• avoid — introduce restricții la traseu. Valorile valide sunt specificate în secțiunea restricții a acestui document. Se poate specifica o singură restricție.
• units — specifică sistemul de unități de utilizat la exprimarea distanței ca text. Consultați secțiunea sisteme de unități din acest document pentru mai multe informații.
• arrival_time — specifică ora dorită de sosire pentru cererile de tranzit, în câteva secunde de la miezul nopții, 1 ianuarie 1970 UTC. Puteți specifica fie departure_time sau arrival_time, dar nu ambele. Rețineți că arrival_time trebuie specificat ca număr întreg.
• departure_time — ora dorită de plecare. Puteți specifica ora ca număr întreg în câteva secunde de la miezul nopții, 1 ianuarie 1970 UTC. Dacă este specificat un departure_time mai târziu de 9999-12-31T23:59:59.9999999999 Z, API-ul va cădea înapoi departure_time la 9999-12-31T23:59:59.999999999 Z. alternativ, puteți specifica o valoare de now, care stabilește ora de plecare la ora curentă (corectă la cea mai apropiată secundă). Ora de plecare poate fi specificată în două cazuri:
  • pentru cererile în care modul de călătorie este tranzit: Puteți specifica opțional unul dintre departure_timesauarrival_time. Dacă nu este specificată nici o oră,departure_time implicit la acum (adică ora de plecare implicit la ora curentă).
  • pentru cererile în care modul de deplasare este condus: puteți specifica departure_time pentru a primi o rută și durata călătoriei (câmpul de răspuns: duration_in_traffic) care iau în considerare condițiile de trafic. Această opțiune este disponibilă numai dacă solicitarea conține o cheie API validă sau un ID de client și o semnătură validă Google Maps Platform Premium Plan. departure_time trebuie setat la ora curentă sau ceva timp în viitor. Nu poate fi în trecut.

    Notă: Dacă ora de plecare nu este specificată, alegerea rutei și a duratei se bazează pe rețeaua rutieră și pe condițiile medii de trafic independente de timp. Rezultatele pentru o anumită solicitare pot varia în timp din cauza modificărilor rețelei rutiere, a condițiilor medii de trafic actualizate și a naturii distribuite a serviciului. Rezultatele pot varia, de asemenea, între rute aproape echivalente în orice moment sau frecvență.

    notă: cererile matricei de distanță care specifică departure_timecândmode=driving sunt limitate la maximum 100 de elemente per cerere. Numărul de origini ori numărul de destinații definește numărul de elemente.

• traffic_model(implicit labest_guess) — specifică ipotezele de utilizat la calcularea timpului în trafic. Această setare afectează valoarea returnată în câmpulduration_in_traffic din răspuns, care conține timpul prezis în trafic pe baza mediilor istorice. Parametrultraffic_modelpoate fi specificat numai pentru cererile în care modul de deplasare estedrivingși în cazul în care cererea include undeparture_time și numai dacă cererea include o cheie API sau un ID Client Google Maps Platform Premium Plan. Valorile disponibile pentru acest parametru sunt:
  • best_guess(implicit) indică faptul căduration_in_traffic returnat ar trebui să fie cea mai bună estimare a timpului de călătorie, având în vedere ceea ce se știe atât despre condițiile istorice de trafic, cât și despre traficul live. Traficul Live devine mai important cu cât departure_time este mai aproape de acum.
  • pessimistic indică faptul căduration_in_traffic returnat ar trebui să fie mai lung decât timpul real de călătorie în majoritatea zilelor, deși zilele ocazionale cu condiții de trafic deosebit de proaste pot depăși această valoare.
  • optimistic indică faptul căduration_in_traffic returnat ar trebui să fie mai scurt decât timpul real de călătorie în majoritatea zilelor, deși zilele ocazionale cu condiții de trafic deosebit de bune pot fi mai rapide decât această valoare.
• transit_mode — specifică unul sau mai multe moduri de tranzit preferate. Acest parametru poate fi specificat numai pentru cererile în care mode este transit. Parametrul acceptă următoarele argumente:
  • bus indică faptul că ruta calculată ar prefera călătoria cu autobuzul.
  • subway indică faptul că ruta calculată ar prefera călătoria cu metroul.
  • train indică faptul că ruta calculată ar prefera călătoria cu trenul.
  • tram indică faptul că ruta calculată ar prefera călătoria cu tramvaiul și calea ferată ușoară.
  • rail indică faptul că ruta calculată ar prefera călătoria cu trenul, tramvaiul, metroul ușor și metroul. Aceasta este echivalentă cu transit_mode=train|tram|subway.
• transit_routing_preference — specifică preferințele pentru cererile de tranzit. Folosind acest parametru, puteți înclina opțiunile returnate, mai degrabă decât să acceptați cea mai bună rută implicită aleasă de API. Acest parametru poate fi specificat numai pentru cererile în care mode este transit. Parametrul acceptă următoarele argumente:
  • less_walking indică faptul că traseul calculat ar trebui să prefere cantități limitate de mers pe jos.
  • fewer_transfers indică faptul că ruta calculată ar prefera un număr limitat de transferuri.

moduri de deplasare

pentru calcularea distanțelor, puteți specifica transportulmode de utilizat. În mod implicit, distanțele sunt calculate pentru modul de conducere. Sunt acceptate următoarele moduri de deplasare:

• driving (implicit) indică calculul distanței utilizând rețeaua rutieră.
• walking solicită calcularea distanței pentru mersul pe căile pietonale& trotuare (acolo unde sunt disponibile).
• bicycling solicită calcularea distanței pentru biciclete prin piste de biciclete& străzi preferate (acolo unde sunt disponibile).
• transit solicită calcularea distanței prin intermediul rutelor de transport public (dacă este disponibil). Această valoare poate fi specificată numai dacă solicitarea include o cheie API sau un ID de client Google Maps Platform Premium Plan. Dacă setați modul la transit puteți specifica opțional un departure_time sau un arrival_time. Dacă nu este specificată nici o oră,departure_time implicit la acum (adică ora de plecare implicit la ora curentă). De asemenea, puteți include opțional un transit_mode și/sau un transit_routing_preference.

informații despre trafic

informațiile despre trafic sunt utilizate atunci când se aplică toate următoarele (acestea sunt condițiile necesare pentru a primi câmpul duration_in_traffic în răspunsul matricei de distanță):

• parametrul de deplasare mode este driving, sau nu este specificat (driving este modul de deplasare implicit).
• cererea include un parametru validdeparture_timedeparture_time poate fi setat la ora curentă sau ceva timp în viitor. Nu poate fi în trecut.

opțional, puteți include parametrultraffic_model în solicitarea dvs. de a specifica ipotezele de utilizat la calcularea timpului în trafic.

următoarea adresă URL inițiază o cerere de matrice de distanță pentru distanțele de conducere între Boston, MA sau Charlestown, MA și Lexington, MA și Concord, MA. Cererea include o oră de plecare, îndeplinind toate cerințele pentru a returna câmpul duration_in_traffic în răspunsul matricei de distanță.

restricții

distanțele pot fi calculate care respectă anumite restricții. Restricțiile sunt indicate prin utilizarea parametruluiavoid și un argument pentru acel parametru care indică restricția de evitat. Sunt acceptate următoarele restricții:

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

* notă: adăugarea restricțiilor nu exclude rutele care includ caracteristica restricționată; aceasta distorsionează rezultatul către rute mai favorabile.

sisteme unitare

rezultatele matricei de distanță conțintext îndistance câmpuri pentru a indica distanța traseului calculat. Sistemul de unități de utilizat poate fi specificat:

• units=metric (implicit) returnează distanțele în kilometri și metri.
• units=imperial returnează distanțele în mile și picioare.

* Notă: Această setare a sistemului unitar afectează numai câmpuriletext afișate îndistance. Câmpuriledistance conțin, de asemenea,values care sunt întotdeauna exprimate în metri.

răspunsurile matricei de distanță

răspunsurile la interogările API ale matricei de distanță sunt returnate în formatul indicat deoutput în calea solicitării URL.două exemple de cereri HTTP sunt prezentate mai jos, solicitând distanța și durata de la Vancouver, BC, Canada și de la Seattle, WA, SUA, la San Francisco, CA, SUA și la Victoria, BC, Canada.

această solicitare demonstrează utilizarea steagului JSON output :

această solicitare demonstrează utilizarea XMLoutput steag:

această solicitare va returna patru elemente – două origini ori două destinații:

rezultatele sunt returnate în rânduri, fiecare rând conținând o origine asociată cu fiecare destinație.

puteți testa acest lucru introducând adresa URL în browserul dvs. web (asigurați-vă că înlocuițiYOUR_API_KEY cu cheia API reală).

selectați filele de mai jos pentru a vedea exemplele de răspunsuri JSON și XML.

restul acestei documentații va folosi sintaxa JSON.

elementele de răspuns ale matricei de distanță

răspunsurile matricei de distanță conțin următoarele elemente rădăcină:

• status conține metadate la cerere. A se vedea codurile de stare de mai jos.
• origin_addresses conține o serie de adrese returnate de API DIN solicitarea inițială. Acestea sunt formatate de geocoder și localizate conform parametruluilanguage transmis cu cererea.
• destination_addresses conține o serie de adrese returnate de API DIN solicitarea inițială. Ca și în cazul origin_addresses, acestea sunt localizate dacă este cazul.
• rows conține o matrice deelements, care la rândul lor conțin fiecare unstatusduration șidistance element.

coduri de stare

status câmpurile din obiectul de răspuns conțin starea cererii și pot conține informații utile de depanare. API-ul Distance Matrix returnează un câmp de stare de nivel superior, cu informații despre cerere în general, precum și un câmp de stare pentru fiecare câmp element, cu informații despre acea asociere origine-destinație.

coduri de stare de nivel superior

• OK indică faptul că răspunsul conține unresultvalid.
• INVALID_REQUEST indică faptul că cererea furnizată a fost nevalidă.
• MAX_ELEMENTS_EXCEEDED indică faptul că produsul originilor și destinațiilor depășește limita per interogare.
• MAX_DIMENSIONS_EXCEEDED indică faptul că numărul de origini sau destinații depășește limita per interogare.
• OVER_DAILY_LIMIT indică oricare dintre următoarele:
  • cheia API lipsește sau este nevalidă.
  • facturarea nu a fost activată în contul dvs.
  • un plafon de utilizare autoimpus a fost depășit.
  • metoda de plată furnizată nu mai este valabilă (de exemplu, un card de credit a expirat).

  consultați Întrebările frecvente despre hărți pentru a afla cum să remediați acest lucru.

• OVER_QUERY_LIMIT indică faptul că serviciul a primit prea multe solicitări din partea aplicației dvs. în perioada de timp permisă.
• REQUEST_DENIED indică faptul că serviciul a refuzat utilizarea Serviciului matrice de distanță de către aplicația dvs.
• UNKNOWN_ERROR indică faptul că o cerere de matrice de distanță nu a putut fi procesată din cauza unei erori de server. Solicitarea poate avea succes dacă încercați din nou.

coduri de stare la nivel de Element

• OK indică faptul că răspunsul conține unresultvalid.
• NOT_FOUND indică faptul că originea și / sau destinația acestei asocieri nu au putut fi geocodificate.
• ZERO_RESULTS indică faptul că nu a putut fi găsită nicio rută între origine și destinație.
• MAX_ROUTE_LENGTH_EXCEEDED indică faptul că ruta solicitată este prea lungă și nu poate fi procesată.

Mesaje de eroare

când codul de stare de nivel superior este altul decâtOK, poate exista un câmp suplimentarerror_message în obiectul de răspuns al matricei de distanță. Acest câmp conțineinformații mai detaliate despre motivele din spatele codului de stare dat.

Notă: Acest câmp nu este garantat să fie întotdeauna prezent, iar conținutul său poate fi modificat.

rânduri

când API-ul matricei de distanță returnează rezultatele, le plasează într-o matrice JSONrows. Chiar dacă nu se returnează niciun rezultat (cum ar fi atunci când originile și/sau destinațiile nu există), acesta returnează în continuare o matrice goală. Răspunsurile XML constau din zero sau mai multe elemente<row>.

rândurile sunt ordonate în funcție de valorile din parametrulorigin al solicitării. Fiecare rând corespunde unei origini și fiecare elementdin acel rând corespunde unei împerecheri a originii cu o valoaredestination.

fiecarerow matrice conține una sau mai multeelement intrări, care la rândul lor conțin informații despre o singură asociere origine-destinație.

elemente

informațiile despre fiecare asociere origine-destinație sunt returnate într-o intrareelement. Un element conține următoarele câmpuri:

• status: consultați codurile de stare pentru o listă de coduri de stare posibile.
• duration: durata de timp necesară pentru a parcurge această rută, exprimată în secunde (câmpulvalue) și catext. Reprezentarea textuală este localizată în funcție de parametrul language al interogării.

• duration_in_traffic: durata de timp necesară pentru a parcurge această rută, în funcție de condițiile actuale și istorice de trafic. Consultați parametrultraffic_model request pentru opțiunile pe care le puteți utiliza pentru a solicita ca valoarea returnată să fie optimistă, pesimistă sau o estimare cu cea mai bună estimare. Durata este exprimată în secunde (câmpul value) și ca text. Reprezentarea textuală este localizată în funcție de parametrul language al interogării. Durata în trafic este returnată numai dacă toate următoarele sunt adevărate:

  • cererea include un parametru departure_time.
  • cererea include o cheie API validă sau un ID de client și o semnătură validă Google Maps Platform Premium Plan.
  • condițiile de trafic sunt disponibile pentru ruta solicitată.
  • parametrulmode este setat ladriving.
• distance: distanța totală a acestui traseu, exprimată în metri (value) și catext. Valoarea textuală utilizează sistemul unitar specificat cu parametrulunit al cererii inițiale sau al regiunii originii.
• fare: dacă este prezent, conține tariful total (adică costurile totale ale biletului) pe această rută. Această proprietate este returnată numai pentru cererile de tranzit și numai pentru furnizorii de tranzit unde sunt disponibile informații despre tarif. Informațiile includ:
  • currency: un cod de monedă ISO 4217 care indică moneda în care este exprimată suma.
  • value: suma totală a tarifului, în moneda specificată mai sus.
  • text: suma totală tarif, formatat în limba solicitată.

mai jos este un exemplu deelement care conține informații tarifare:

parametrul senzorului

API-ul Google Maps a cerut anterior să includeți parametrulsensor pentru a indica dacă aplicația dvs. a folosit asensor pentru a determina locația utilizatorului. Acest parametru nu mai estenecesare.