Żądanie i odpowiedź Distance Matrix API (starsza wersja)

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Wprowadzenie

Żądanie do interfejsu Distance Matrix API (starszego typu) ma następującą postać:

https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters

gdzie outputFormat może mieć jedną z tych wartości:

  • json (zalecane) wskazuje dane wyjściowe w formacie JSON (JavaScript Object Notation).
  • xml wskazuje dane wyjściowe w formacie XML.

Niektóre parametry są wymagane, a inne opcjonalne. Zgodnie ze standardem adresów URL wszystkie parametry są rozdzielone znakiem ampersand (&). Wszystkie znaki zarezerwowane (np. znak plusa „+”) muszą być zakodowane na potrzeby adresu URL. Lista parametrów i ich możliwych wartości znajduje się poniżej.

Wymagane parametry

  • miejsca docelowe

    Co najmniej 1 lokalizacja, która ma być używana jako punkt końcowy do obliczania odległości i czasu podróży. Opcje parametru destinations są takie same jak w przypadku parametru origins.

  • źródła

    Punkt początkowy do obliczania odległości i czasu podróży. Możesz podać co najmniej 1 lokalizację, rozdzielając je znakiem kreski pionowej (|), w postaci identyfikatora miejsca, adresu lub współrzędnych geograficznych:

    • Identyfikator miejsca: jeśli podajesz identyfikator miejsca, musisz go poprzedzić ciągiem znaków place_id:.
    • Adres: jeśli podasz adres, usługa geokoduje ciąg znaków i konwertuje go na współrzędne szerokości i długości geograficznej, aby obliczyć odległość. Ta współrzędna może się różnić od współrzędnej zwracanej przez interfejs Geocoding API, np. może to być wejście do budynku, a nie jego środek.
      Uwaga: zalecamy używanie identyfikatorów miejsc, a nie adresów czy współrzędnych geograficznych. Użycie współrzędnych zawsze spowoduje przyciągnięcie punktu do drogi znajdującej się najbliżej tych współrzędnych, która może nie być punktem dostępu do nieruchomości, a nawet drogą, która szybko lub bezpiecznie prowadzi do miejsca docelowego. Użycie adresu spowoduje podanie odległości do środka budynku, a nie do wejścia.
    • Współrzędne: jeśli podasz współrzędne szerokości i długości geograficznej, zostaną one przyciągnięte do najbliższej drogi. Zalecamy przekazywanie identyfikatora miejsca. Jeśli przekazujesz współrzędne, upewnij się, że między wartościami szerokości i długości geograficznej nie ma spacji.
    • Kody Plus Code muszą być sformatowane jako kod globalny lub kod złożony. Sformatuj plus kody w sposób pokazany tutaj (znaki plusa są zastępowane przez %2B, a spacje przez %20):
      • global code to 4-znakowy numer kierunkowy i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9 jest kodowany jako 849VCWC8%2BR9).
      • kod złożony to kod lokalny składający się z co najmniej 6 znaków z wyraźną lokalizacją (CWC8+R9 Mountain View, CA, USA jest kodowany jako CWC8%2BR9%20Mountain%20View%20CA%20USA).
    • Zakodowana linia łamana – możesz też podać zakodowany zestaw współrzędnych, korzystając z algorytmu zakodowanej linii łamanej. Jest to szczególnie przydatne, gdy masz dużą liczbę punktów początkowych, ponieważ adres URL jest znacznie krótszy, gdy używasz zakodowanej linii łamanej.
      • Zakodowane linie łamane muszą być poprzedzone ciągiem enc: i dwukropkiem :. Na przykład: origins=enc:gfo}EtohhU:
      • Możesz też uwzględnić wiele zakodowanych linii łamanych, rozdzielając je znakiem kreski pionowej |. Na przykład: 
        origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:

Parametry opcjonalne

  • arrival_time

    Określa preferowany czas przyjazdu w przypadku wskazówek dojazdu transportem publicznym w sekundach od północy 1 stycznia 1970 r. czasu UTC. Możesz określić departure_time lub arrival_time, ale nie obie te wartości. Pamiętaj, że wartość arrival_time musi być liczbą całkowitą.

  • unikanie

    Odległości mogą być obliczane z uwzględnieniem pewnych ograniczeń. Ograniczenia są wskazywane przez użycie parametru avoid i argumentu tego parametru, który wskazuje ograniczenie, którego należy unikać. Obsługiwane są te ograniczenia:

    • tolls wskazuje, że obliczona trasa powinna omijać drogi i mosty płatne.
    • highways wskazuje, że obliczona trasa powinna omijać autostrady.
    • ferries wskazuje, że obliczona trasa powinna omijać promy.
    • indoor wskazuje, że obliczona trasa powinna unikać schodów wewnątrz budynków w przypadku wskazówek dojazdu pieszo i transportem publicznym.

    Możesz poprosić o trasę, która omija dowolną kombinację opłat, autostrad i promów, przekazując oba ograniczenia do parametru avoid. Na przykład avoid=tolls|highways|ferries.

    Uwaga: dodanie ograniczeń nie wyklucza tras, które obejmują ograniczoną funkcję, ale wpływa na wynik, faworyzując bardziej korzystne trasy.

  • departure_time

    Określa preferowaną godzinę wyjazdu. Możesz określić czas jako liczbę całkowitą w sekundach od północy 1 stycznia 1970 r. czasu UTC. Jeśli podasz wartość departure_time późniejszą niż 9999-12-31T23:59:59.999999999Z, interfejs API przywróci wartość departure_time do 9999-12-31T23:59:59.999999999Z. Możesz też podać wartość now, która ustawia czas odjazdu na bieżącą godzinę (z dokładnością do najbliższej sekundy). Godzinę odjazdu można określić w 2 przypadkach:

    • W przypadku żądań, w których tryb podróży to transport publiczny: możesz opcjonalnie określić departure_time lub arrival_time. Jeśli nie podano żadnej godziny, departure_time domyślnie przyjmuje wartość „teraz” (czyli czas odjazdu domyślnie przyjmuje wartość bieżącego czasu).
    • W przypadku żądań, w których tryb podróży to jazda samochodem: możesz określić parametr departure_time, aby otrzymać trasę i czas trwania podróży (pole odpowiedzi: duration_in_traffic) uwzględniające warunki na drodze. Wartość departure_time musi być ustawiona na bieżącą godzinę lub godzinę w przyszłości. Nie może przypadać w przeszłości.
    Uwaga: jeśli czas wyjazdu nie jest określony, wybór trasy i czas trwania są określane na podstawie sieci dróg i średnich warunków na drodze niezależnych od czasu. Wyniki dla danego żądania mogą się zmieniać w czasie ze względu na zmiany w sieci dróg, aktualizacje średnich warunków na drodze i rozproszony charakter usługi. Wyniki mogą się też różnić w przypadku niemal równoważnych tras w dowolnym momencie lub z dowolną częstotliwością.
    Uwaga: żądania macierzy odległości, które określają departure_time, gdy mode=driving, są ograniczone do maksymalnie 100 elementów na żądanie. Liczba elementów jest iloczynem liczby miejsc początkowych i miejsc docelowych.

  • language

    Język, w którym mają być zwracane wyniki.

    • Zobacz listę obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być wyczerpująca.
    • Jeśli nie podasz parametru language, interfejs API spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language.
    • Interfejs API stara się podać adres, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby osiągnąć ten cel, zwraca adresy pocztowe w języku lokalnym, w razie potrzeby transliterowane na pismo czytelne dla użytkownika, z uwzględnieniem preferowanego języka. Wszystkie inne adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego komponentu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API używa najbliższego dopasowania.
    • Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API zwraca, oraz na kolejność, w jakiej są zwracane. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym. Na przykład utca i tér to synonimy słowa „ulica” w języku węgierskim.

  • tryb

    Do obliczania odległości i wskazówek dojazdu możesz określić środek transportu. Domyślnie używany jest tryb DRIVING. Domyślnie wskazówki dojazdu są obliczane jako wskazówki dojazdu samochodem. Obsługiwane są te środki transportu:

    • driving (domyślna) wskazuje standardowe wskazówki dojazdu lub odległość z wykorzystaniem sieci dróg.
    • walking prośba o trasę pieszą lub odległość z wykorzystaniem ścieżek dla pieszych i chodników (jeśli są dostępne).
    • bicycling – prośba o wskazówki dojazdu rowerem lub odległość z uwzględnieniem ścieżek rowerowych i preferowanych ulic (jeśli są dostępne).
    • transit prosi o wskazówki dojazdu lub odległość z wykorzystaniem tras transportu publicznego (jeśli są dostępne). Jeśli ustawisz tryb na transport publiczny, możesz opcjonalnie określić departure_time lub arrival_time. Jeśli nie podasz żadnej godziny, departure_time domyślnie przyjmie wartość „teraz” (czyli godzina odjazdu będzie domyślnie ustawiona na bieżącą godzinę). Możesz też opcjonalnie dodać transit_mode lub transit_routing_preference.
    Uwaga: wskazówki dojazdu pieszo i rowerem mogą czasami nie obejmować wyraźnych ścieżek dla pieszych lub rowerzystów, dlatego w zwróconym wyniku pojawią się ostrzeżenia, które musisz wyświetlić użytkownikowi.
    Uwaga: przejazdy transportem publicznym są dostępne do 7 dni wstecz lub do 100 dni do przodu, w zależności od dostępności informacji o transporcie publicznym dostarczanych przez dostawców danych. Rozkłady jazdy transportu publicznego często się zmieniają, dostępne przejazdy mogą się zmieniać w czasie i nie ma gwarancji, że prognozy będą spójne z dużym wyprzedzeniem.

  • region

    Kod regionu określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”).

  • traffic_model

    Określa założenia, które mają być używane podczas obliczania czasu w ruchu ulicznym. To ustawienie wpływa na wartość zwracaną w polu duration_in_traffic w odpowiedzi, która zawiera przewidywany czas w ruchu na podstawie średnich historycznych. Parametr traffic_model można określić tylko w przypadku wskazówek dojazdu, gdy żądanie zawiera parametr departure_time. Dostępne wartości tego parametru:

    • best_guess (domyślna) wskazuje, że zwracana wartość duration_in_traffic powinna być najlepszym szacunkiem czasu podróży na podstawie informacji o historycznych i bieżących warunkach na drodze. Aktualne natężenie ruchu staje się tym ważniejsze, im bliżej departure_time jest obecnej chwili.
    • pessimistic wskazuje, że zwrócona wartość duration_in_traffic powinna być dłuższa niż rzeczywisty czas podróży w większości dni, chociaż w niektóre dni, gdy warunki na drodze są szczególnie złe, może przekroczyć tę wartość.
    • optimistic wskazuje, że zwrócona wartość duration_in_traffic powinna być krótsza niż rzeczywisty czas podróży w większości dni, chociaż w niektóre dni, gdy warunki na drodze są szczególnie dobre, czas podróży może być krótszy niż ta wartość.

    Wartość domyślna best_guess zapewnia najbardziej przydatne prognozy w większości przypadków. Możliwe, że prognoza czasu podróży best_guess może być krótsza niż optimistic lub dłuższa niż pessimistic ze względu na sposób, w jaki model predykcyjny best_guess integruje informacje o aktualnym natężeniu ruchu.

  • transit_mode

    Określa co najmniej 1 preferowany środek transportu. Ten parametr można określić tylko w przypadku wskazówek dojazdu transportem publicznym. Parametr obsługuje te argumenty:

    • bus wskazuje, że obliczona trasa powinna preferować podróż autobusem.
    • subway wskazuje, że obliczona trasa powinna preferować podróż metrem.
    • train wskazuje, że obliczona trasa powinna preferować podróż pociągiem.
    • tram wskazuje, że obliczona trasa powinna preferować podróż tramwajem i koleją miejską.
    • rail wskazuje, że obliczona trasa powinna preferować podróż pociągiem, tramwajem, koleją miejską i metrem. Odpowiada to transit_mode=train|tram|subway.

  • transit_routing_preference

    Określa preferencje dotyczące tras transportu publicznego. Za pomocą tego parametru możesz wpływać na zwracane opcje, zamiast akceptować domyślną najlepszą trasę wybraną przez interfejs API. Ten parametr można określić tylko w przypadku wskazówek dojazdu transportem publicznym. Parametr obsługuje te argumenty:

    • less_walking wskazuje, że obliczona trasa powinna preferować ograniczoną ilość chodzenia.
    • fewer_transfers wskazuje, że obliczona trasa powinna preferować ograniczoną liczbę przesiadek.

  • jedn.

    Określa system jednostek, który ma być używany podczas wyświetlania wyników.

    Uwaga: to ustawienie układu jednostek wpływa tylko na tekst wyświetlany w polach odległości. Pola odległości zawierają też wartości, które są zawsze wyrażone w metrach.

Przykłady żądań

W tym przykładzie współrzędne miejsca docelowego są podane za pomocą współrzędnych geograficznych: szerokości i długości geograficznej.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

W tym przykładzie do określenia współrzędnych miejsca docelowego użyto kodów Plus Code:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

Ten przykład pokazuje to samo żądanie z użyciem zakodowanej linii łamanej:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

Informacje o natężeniu ruchu

Informacje o natężeniu ruchu są używane, gdy spełnione są wszystkie te warunki (są to warunki wymagane do otrzymania pola duration_in_traffic w odpowiedzi macierzy odległości):

  • Parametr modepodróży ma wartość driving lub nie jest określony (driving to domyślny środek transportu).
  • Żądanie zawiera prawidłowy parametr departure_time. Wartość departure_time można ustawić na bieżącą godzinę lub na godzinę w przyszłości. Nie może przypadać w przeszłości.

Opcjonalnie możesz dodać do żądania parametr traffic_model, aby określić założenia, które mają być używane podczas obliczania czasu w ruchu ulicznym.

Poniższy adres URL inicjuje żądanie Distance Matrix dotyczące odległości drogowych między Bostonem (Massachusetts) lub Charlestown (Massachusetts) a Lexington (Massachusetts) i Concord (Massachusetts). Żądanie zawiera czas wyjazdu, co spełnia wszystkie wymagania dotyczące zwracania pola duration_in_traffic w odpowiedzi macierzy odległości.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

JSON

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins

Modyfikatory lokalizacji

Możesz użyć modyfikatorów lokalizacji, aby wskazać, jak kierowcy powinni dojechać do określonej lokalizacji. Możesz użyć modyfikatora side_of_road, aby określić, po której stronie drogi należy jechać, lub podać kierunek, aby wskazać właściwy kierunek jazdy.

określić, że obliczone trasy muszą przebiegać po określonej stronie drogi;

Podczas określania lokalizacji możesz poprosić o wyznaczenie trasy po tej stronie drogi, po której znajduje się punkt pośredni, używając prefiksu side_of_road:. Na przykład to żądanie zwróci odległość dla długiej trasy, tak aby pojazd zakończył jazdę po tej stronie drogi, po której znajduje się punkt pośredni:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

Gdy używasz parametru side_of_road: z zakodowanymi liniami łamanymi, modyfikator jest stosowany do każdej lokalizacji na linii łamanej. Na przykład oba miejsca docelowe w tym żądaniu używają parametru:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

Modyfikatora side_of_road: można używać tylko z tym ograniczeniem:

  • Parametr mode ma wartość driving lub nie jest określony (driving to domyślny środek transportu).

Określanie, że obliczone trasy powinny mieć określony kierunek

Podczas określania lokalizacji możesz poprosić o obliczenie trasy, która będzie przebiegać przez tę lokalizację w określonym kierunku. Ten kierunek jest określany za pomocą prefiksu heading=X:, gdzie X jest liczbą całkowitą z zakresu od 0 (włącznie) do 360 (wyłącznie). Kierunek 0 oznacza północ, 90 – wschód, i tak dalej zgodnie z ruchem wskazówek zegara. Na przykład w tym żądaniu obliczona trasa prowadzi na wschód od punktu początkowego, a następnie zawraca:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

Modyfikatora heading=X: można używać tylko z tymi ograniczeniami:

  • Parametr mode ma wartość driving, bicycling lub nie jest określony (driving to domyślny środek transportu).
  • Modyfikator side_of_road nie jest określony dla tej samej lokalizacji.
  • Lokalizacja jest określana za pomocą wartości szerokości i długości geograficznej. Nie możesz używać parametru heading z adresami, identyfikatorami miejsc ani zakodowanymi łamanymi.

Żądania i odpowiedzi dotyczące macierzy odległości

Poniżej znajduje się przykładowe żądanie HTTP, które dotyczy odległości i czasu trwania podróży z Vancouver (Kolumbia Brytyjska, Kanada) i Seattle (Waszyngton, USA) do San Francisco (Kalifornia, USA) i Victorii (Kolumbia Brytyjska, Kanada).

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

To żądanie zwróci 4 elementy – 2 miejsca początkowe pomnożone przez 2 miejsca docelowe:

Z Warszawy do Gdańska Vancouver – Victoria
Z Wrocławia do Warszawy Seattle – Victoria

Wyniki są zwracane w wierszach, z których każdy zawiera jedno miejsce początkowe sparowane z każdym miejscem docelowym.

JSON

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km

DistanceMatrixResponse

Pole Wymagane Typ Opis
wymagane Array<string>

Tablica adresów zwróconych przez interfejs API z pierwotnego żądania. Podobnie jak w przypadku origin_addresses, są one lokalizowane, jeśli jest to konieczne. Te treści są przeznaczone do odczytu w obecnej postaci. Nie analizuj sformatowanych adresów automatycznie.

wymagane Array<string>

Tablica adresów zwróconych przez interfejs API z pierwotnego żądania. Są one formatowane przez geokoder i lokalizowane zgodnie z parametrem języka przekazanym w żądaniu. Te treści powinny być odczytywane w takiej postaci, w jakiej są. Nie analizuj sformatowanych adresów automatycznie.

wymagane thought Array<DistanceMatrixRow>

Tablica elementów, z których każdy zawiera elementy status, duration i distance.

Więcej informacji znajdziesz w artykule DistanceMatrixRow.

wymagane DistanceMatrixStatus

Zawiera stan żądania i może zawierać informacje na potrzeby debugowania, które pomogą Ci ustalić, dlaczego żądanie się nie powiodło.

Więcej informacji znajdziesz w sekcji DistanceMatrixStatus.

opcjonalnie tekst

Ciąg znaków zawierający zrozumiały dla człowieka tekst błędów, które wystąpiły podczas przetwarzania żądania.

DistanceMatrixStatus

Kody stanu zwracane przez usługę.

  • OK wskazuje, że odpowiedź zawiera prawidłowy wynik.
  • INVALID_REQUEST oznacza, że przesłane żądanie było nieprawidłowe.
  • MAX_ELEMENTS_EXCEEDED wskazuje, że iloczyn liczby miejsc początkowych i docelowych przekracza limit na zapytanie.
  • MAX_DIMENSIONS_EXCEEDED wskazuje, że liczba punktów początkowych lub docelowych przekracza limit na zapytanie.
  • OVER_DAILY_LIMIT oznacza dowolną z tych wartości:
    • Brak klucza interfejsu API lub jest on nieprawidłowy.
    • Na Twoim koncie nie włączono płatności.
    • Przekroczono samodzielnie nałożony limit wykorzystania.
    • Podana forma płatności nie jest już ważna (np. karta kredytowa straciła ważność).
  • OVER_QUERY_LIMIT oznacza, że usługa otrzymała zbyt wiele żądań z Twojej aplikacji w dozwolonym okresie.
  • REQUEST_DENIED wskazuje, że usługa odmówiła aplikacji dostępu do usługi macierzy odległości.
  • UNKNOWN_ERROR wskazuje, że nie udało się przetworzyć żądania macierzy odległości z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.

DistanceMatrixRow

Pole Wymagane Typ Opis
wymagane Array<DistanceMatrixElement>

Gdy interfejs Distance Matrix API zwraca wyniki, umieszcza je w tablicy wierszy JSON. Nawet jeśli nie zostaną zwrócone żadne wyniki (np. gdy miejsca początkowe lub docelowe nie istnieją), nadal zwracana jest pusta tablica.

Wiersze są uporządkowane według wartości w parametrze origin żądania. Każdy wiersz odpowiada miejscu początkowemu, a każdy element w tym wierszu odpowiada parze miejsca początkowego i wartości miejsca docelowego.

Każda tablica wierszy zawiera co najmniej 1 wpis elementu, który z kolei zawiera informacje o pojedynczej parze miejsce początkowe – miejsce docelowe.

Więcej informacji znajdziesz w artykule DistanceMatrixElement.

DistanceMatrixElement

Pole Wymagane Typ Opis
wymagane DistanceMatrixElementStatus

Stan elementu.

Więcej informacji znajdziesz w sekcji DistanceMatrixElementStatus.

opcjonalnie TextValueObject

Łączna odległość na tej trasie wyrażona w metrach (wartość) i jako tekst. Wartość tekstowa używa układu jednostek określonego za pomocą parametru unit pierwotnego żądania lub regionu miejsca początkowego.

Więcej informacji znajdziesz w opisie obiektu TextValueObject.

opcjonalnie TextValueObject

Czas potrzebny na pokonanie tej trasy, wyrażony w sekundach (pole value) i jako tekst. Reprezentacja tekstowa jest lokalizowana zgodnie z parametrem języka zapytania.

Więcej informacji znajdziesz w opisie obiektu TextValueObject.

opcjonalnie TextValueObject

Czas potrzebny na pokonanie tej trasy, obliczony na podstawie bieżących i historycznych warunków na drodze. Więcej informacji o opcjach, których możesz użyć, aby poprosić o zwrócenie wartości optymistycznej, pesymistycznej lub najbardziej prawdopodobnej, znajdziesz w parametrze żądania traffic_model. Czas trwania jest wyrażony w sekundach (pole value) i jako tekst. Reprezentacja tekstowa jest lokalizowana zgodnie z parametrem języka zapytania. Czas trwania w ruchu jest zwracany tylko wtedy, gdy są spełnione wszystkie te warunki:

  • Żądanie zawiera parametr departure_time.
  • Informacje o warunkach na drodze są dostępne dla wybranej trasy.
  • Parametr mode jest ustawiony na driving.

Więcej informacji znajdziesz w opisie obiektu TextValueObject.

opcjonalnie Fare

Jeśli jest obecny, zawiera łączną opłatę (czyli łączny koszt biletów) na tej trasie. Ta właściwość jest zwracana tylko w przypadku żądań dotyczących transportu publicznego i tylko w przypadku dostawców transportu publicznego, u których dostępne są informacje o opłatach.

Więcej informacji znajdziesz w sekcji Opłata.

Cena

Łączna opłata za przejazd na trasie.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}
Pole Wymagane Typ Opis
wymagane tekst

Kod waluty w formacie ISO 4217 wskazujący walutę, w której wyrażona jest kwota.

text

wymagane tekst

Łączna kwota opłaty za przejazd sformatowana w żądanym języku.
wymagane liczba

Łączna kwota opłaty za przejazd w określonej walucie.

DistanceMatrixElementStatus

  • OK wskazuje, że odpowiedź zawiera prawidłowy wynik.
  • NOT_FOUND oznacza, że nie udało się wygenerować kodu geograficznego dla źródła lub miejsca docelowego tej pary.
  • ZERO_RESULTS oznacza, że nie udało się znaleźć trasy między miejscem wyjazdu a miejscem docelowym.
  • MAX_ROUTE_LENGTH_EXCEEDED oznacza, że żądana trasa jest za długa i nie można jej przetworzyć.

TextValueObject

Obiekt zawierający wartość liczbową i jej sformatowaną reprezentację tekstową.

Pole Wymagane Typ Opis

text

wymagane tekst

Wartość w formie ciągu znaków.
wymagane liczba

Wartość liczbowa.