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

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Wprowadzenie

Żądanie do interfejsu Distance Matrix API (starszego) 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) oznacza dane wyjściowe w formacie JSON (JavaScript Object Notation).
  • xml oznacza 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. Listę parametrów i ich możliwych wartości znajdziesz poniżej.

Wymagane parametry

  • miejsca docelowe

    Co najmniej 1 lokalizacja, która będzie punktem końcowym obliczania odległości i czasu podróży. Opcje parametru miejsc docelowych są takie same jak w przypadku parametru miejsc początkowych.

  • pochodzenie,

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

    • Identyfikator miejsca: jeśli podasz identyfikator miejsca, musisz dodać przed nim prefiks place_id:.
    • Adres: jeśli podasz adres, usługa geokoduje ciąg znaków i przekształca go we współrzędne geograficzne, aby obliczyć odległość. Te współrzędne mogą się różnić od tych zwracanych przez interfejs Geocoding API, np. mogą wskazywać wejście do budynku, a nie jego środek.
      Uwaga: zalecamy używanie identyfikatorów miejsc zamiast adresów lub współrzędnych geograficznych. Użycie współrzędnych zawsze spowoduje przyciągnięcie punktu do drogi najbliższej tym współrzędnym – może to nie być punkt dostępu do nieruchomości ani nawet droga, która szybko lub bezpiecznie doprowadzi do miejsca docelowego. Użycie adresu spowoduje podanie odległości do środka budynku, a nie do wejścia do niego.
    • Współrzędne: jeśli podasz współrzędne geograficzne, zostaną one dopasowane do najbliższej drogi. Zalecane jest 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. Kody plus należy formatować w sposób pokazany poniżej (znaki plus są kodowane w adresie URL jako %2B, a spacje jako %20):
      • kod globalny to 4-znakowy kod obszaru i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9 jest kodowany jako 849VCWC8%2BR9).
      • kod złożony to lokalny kod składający się z co najmniej 6 znaków, który zawiera 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, jeśli 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 znakiem enc: i dwukropkiem :. Na przykład:origins=enc:gfo}EtohhU:
      • Możesz też dodać wiele zakodowanych linii łamanych oddzielonych znakiem |. Na przykład: 
        origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:

Parametry opcjonalne

  • arrival_time

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

  • unikać

    Odległości mogą być obliczane z uwzględnieniem pewnych ograniczeń. Ograniczenia są wskazywane za pomocą parametru avoid, a argument tego parametru wskazuje ograniczenie, którego należy unikać. Obsługiwane są te ograniczenia:

    • tolls oznacza, że obliczona trasa powinna omijać drogi i mosty płatne.
    • highways oznacza, że obliczona trasa powinna omijać autostrady.
    • ferries oznacza, że obliczona trasa powinna omijać promy.
    • indoor oznacza, że obliczona trasa powinna unikać schodów w budynkach w przypadku wskazówek dotyczących pieszych i wskazówek dojazdu transportem publicznym.

    Możesz poprosić o wyznaczenie trasy, która omija dowolną kombinację dróg płatnych, 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ą ograniczony element. Wpływa ono na wynik, faworyzując bardziej korzystne trasy.

  • departure_time

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

    • W przypadku żądań, w których tryb podróży to transport publiczny, możesz opcjonalnie określić jedną z wartości departure_time lub arrival_time. Jeśli nie podasz żadnego z tych czasów, domyślnie zostanie użyta wartość departure_time (czyli czas odjazdu będzie domyślnie ustawiony na bieżący czas).
    • W przypadku żądań, w których trybem podróży jest jazda samochodem, możesz określić 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żący czas lub na czas w przyszłości. Nie może to być data z przeszłości.
    Uwaga: jeśli czas odjazdu nie zostanie określony, wybór trasy i czas trwania podróży będą zależeć od sieci dróg i średnich warunków ruchu niezależnych od czasu. Wyniki danego żądania mogą się zmieniać z czasem ze względu na zmiany w sieci dróg, zaktualizowane średnie warunki na drodze i rozproszony charakter usługi. Wyniki mogą się też różnić w przypadku niemal identycznych tras w dowolnym momencie lub z dowolną częstotliwością.
    Uwaga: żądania interfejsu Distance Matrix API określające departure_time, gdy mode=driving, są ograniczone do maksymalnie 100 elementów na żądanie. Liczba punktów początkowych pomnożona przez liczbę punktów docelowych określa liczbę elementów.

  • language

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

    • Zobacz listę obsługiwanych języków. Google często aktualizuje listę obsługiwanych języków, więc może ona 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 ulicy, który jest czytelny zarówno dla użytkownika, jak i mieszkańców. Aby to osiągnąć, zwraca adresy w języku lokalnym, a w razie potrzeby transliteruje je na pismo czytelne dla użytkownika, uwzględniając preferowany język. Wszystkie pozostałe 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żyje najbliższego dopasowania.
    • Preferowany język ma niewielki wpływ na zbiór wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one 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

    Aby obliczyć odległości i wyznaczyć trasę, możesz określić środek transportu. Domyślnie używany jest tryb DRIVING. Domyślnie wskazówki są obliczane jako wskazówki dojazdu. Obsługiwane są te środki transportu:

    • driving (domyślnie) oznacza standardowe wskazówki dojazdu lub odległość z wykorzystaniem sieci dróg.
    • walking prośby o wskazówki dojazdu pieszo lub o odległość do pokonania pieszo z wykorzystaniem ścieżek dla pieszych i chodników (jeśli są dostępne).
    • bicycling prośby o wskazówki dojazdu rowerem lub o odległość dojazdu rowerem z wykorzystaniem ścieżek rowerowych i preferowanych ulic (jeśli są dostępne);
    • transit prosi o wskazówki dojazdu lub odległość, korzystając z tras transportu publicznego (tam, gdzie są dostępne); Jeśli ustawisz tryb na transport publiczny, możesz opcjonalnie określić departure_time lub arrival_time. Jeśli nie podasz żadnego czasu,departure_time domyślnie przyjmuje wartość „teraz” (czyli czas odjazdu jest domyślnie ustawiony na bieżący czas). Opcjonalnie możesz też dodać transit_mode lub transit_routing_preference.
    Uwaga: wskazówki dojazdu pieszo i rowerem mogą czasami nie uwzględniać wyraźnych ścieżek dla pieszych lub rowerzystów, dlatego w wyniku zwracają ostrzeżenia, które musisz wyświetlić użytkownikowi.
    Uwaga: trasy transportu publicznego są dostępne do 7 dni wstecz lub do 100 dni w przyszłości, 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ć z czasem i nie ma gwarancji, że prognozy z dużym wyprzedzeniem będą spójne.

  • region

    Kod regionu podany jako ccTLD („domena najwyższego poziomu”), czyli wartość dwuznakowa. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma wyjątkami. Na przykład krajowa domena najwyższego poziomu Wielkiej Brytanii to „uk” (.co.uk), a 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. To ustawienie wpływa na wartość zwracaną w polu duration_in_traffic w odpowiedzi, które zawiera prognozowany czas przejazdu z uwzględnieniem ruchu na podstawie średnich wartości historycznych. Parametr traffic_model można określić tylko w przypadku wskazówek dojazdu, w których żądanie zawiera parametr departure_time. Dostępne wartości tego parametru:

    • best_guess (domyślny) oznacza, że zwrócony czas trwania duration_in_traffic powinien być najlepszym oszacowaniem czasu podróży na podstawie danych historycznych o warunkach na drodze i aktualnego natężenia ruchu. Im bliżej teraźniejszości jest departure_time, tym większe znaczenie ma aktualne natężenie ruchu.
    • pessimistic oznacza, że zwrócony czas duration_in_traffic powinien być dłuższy 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 być wyższy.
    • optimistic oznacza, że zwrócony czas duration_in_traffic powinien być krótszy niż rzeczywisty czas podróży w większości dni, chociaż w niektóre dni, gdy warunki na drodze są szczególnie dobre, może być krótszy niż ta wartość.

    Wartość domyślna best_guess zapewni najbardziej przydatne prognozy w większości przypadków. Możliwe, że best_guess prognoza czasu podróży będzie krótsza niż optimistic lub dłuższa niż pessimistic ze względu na sposób, w jaki model prognozowania best_guess integruje aktualne natężenie 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 oznacza, że obliczona trasa powinna preferować podróż autobusem.
    • subway oznacza, że obliczona trasa powinna preferować podróż metrem.
    • train oznacza, że obliczona trasa powinna preferować podróż pociągiem.
    • tram oznacza, że obliczona trasa powinna preferować podróż tramwajem lub koleją miejską.
    • rail – obliczona trasa powinna preferować podróż pociągiem, tramwajem, koleją miejską i metrem. Jest to odpowiednik transit_mode=train|tram|subway.

  • transit_routing_preference

    Określa preferencje dotyczące tras transportu publicznego. Za pomocą tego parametru możesz zmienić kolejność zwracanych opcji, 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 oznacza, że obliczona trasa powinna uwzględniać ograniczone ilości chodzenia.
    • fewer_transfers oznacza, że obliczona trasa powinna mieć 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 do określenia współrzędnych miejsca docelowego użyto współrzędnych geograficznych:

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żywamy kodów plusowych:

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 ruchu są używane, gdy wszystkie poniższe warunki są spełnione (są to warunki wymagane do otrzymania pola duration_in_traffic w odpowiedzi interfejsu Distance Matrix API):

  • Parametr mode dotyczący podróży ma wartość driving lub nie jest określony (driving to domyślny środek transportu).
  • Żądanie zawiera prawidłowy departure_time parametr. departure_time można ustawić na bieżącą godzinę lub na późniejszy termin. Nie może to być data z 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.

Poniższy adres URL inicjuje żądanie dotyczące matrycy odległości w przypadku odległości dojazdu samochodem między Bostonem w stanie Massachusetts lub Charlestown w stanie Massachusetts a Lexington w stanie Massachusetts i Concord w stanie Massachusetts. Żądanie zawiera czas odjazdu, który spełnia wszystkie wymagania dotyczące zwracania pola duration_in_traffic w odpowiedzi interfejsu Distance Matrix API.

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żywać modyfikatorów lokalizacji, aby wskazać kierowcom, jak mają podjeżdżać do określonego miejsca. Użyj modyfikatora side_of_road, aby określić, po której stronie drogi mają się poruszać, lub podaj kierunek, aby wskazać prawidłowy kierunek jazdy.

Określanie, że obliczone trasy muszą przebiegać po określonej stronie drogi

Podczas określania lokalizacji możesz poprosić, aby obliczona trasa przebiegała po tej stronie drogi, w kierunku której jest przesunięty punkt pośredni. W tym celu użyj prefiksu side_of_road:. Na przykład to żądanie zwróci odległość dla długiej trasy, tak aby pojazd zatrzymał się po stronie drogi, do której był przesunięty 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 side_of_road: z zakodowanymi liniami łamanymi, modyfikator jest stosowany do każdej lokalizacji wzdłuż linii łamanej. Na przykład oba miejsca docelowe w tym żądaniu używają tego 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'

Modyfikator side_of_road: może być używany tylko z tym ograniczeniem:

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

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

Podczas określania lokalizacji możesz poprosić, aby obliczona trasa przebiegała przez tę lokalizację w określonym kierunku. Kierunek jest określany za pomocą prefiksu heading=X:, gdzie X to liczba całkowita z zakresu od 0 (włącznie) do 360 (wyłącznie). Kierunek 0 oznacza północ, 90 – wschód, a kolejne wartości są podawane 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'

Modyfikator heading=X: może być używany 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ć heading z adresami, identyfikatorami miejsc ani zakodowanymi liniami łamanymi.

Żądania i odpowiedzi dotyczące interfejsu Distance Matrix API

Poniżej znajduje się przykładowe żądanie HTTP, w którym prosisz o podanie odległości i czasu podróży z Vancouver w Kanadzie i Seattle w USA do San Francisco w USA i Victorii w Kanadzie.

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 i 2 miejsca docelowe:

Vancouver – San Francisco Vancouver – Victoria
Z Seattle do San Francisco Seattle – Victoria

Wyniki są zwracane w wierszach, z których każdy zawiera 1 miejsce początkowe połączone 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ócona przez interfejs API z pierwotnego żądania. Podobnie jak w przypadku origin_addresses, te elementy są lokalizowane, jeśli jest to odpowiednie. Te treści mają być odczytywane w takiej formie, w jakiej są wyświetlane. Nie analizuj sformatowanych adresów za pomocą oprogramowania.

wymagane Array<string>

Tablica adresów zwrócona przez interfejs API z pierwotnego żądania. Są one formatowane przez geokoder i dostosowywane do języka określonego w parametrze języka przekazanym w żądaniu. Te treści mają być odczytywane w takiej postaci, w jakiej są. Nie analizuj sformatowanych adresów automatycznie.

wymagane Array<DistanceMatrixRow>

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

Więcej informacji znajdziesz w sekcji DistanceMatrixRow.

wymagane DistanceMatrixStatus

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

Więcej informacji znajdziesz w sekcji DistanceMatrixStatus.

opcjonalnie tekst

Ciąg znaków zawierający tekst w postaci zrozumiałej dla człowieka z informacjami o błędach, które wystąpiły podczas przetwarzania żądania.

DistanceMatrixStatus

Kody stanu zwracane przez usługę.

  • Symbol OK oznacza, że odpowiedź zawiera prawidłowy wynik.
  • INVALID_REQUEST oznacza, że przesłane żądanie było nieprawidłowe.
  • MAX_ELEMENTS_EXCEEDED oznacza, że liczba miejsc docelowych i źródeł przekracza limit zapytań.
  • MAX_DIMENSIONS_EXCEEDED – liczba punktów początkowych lub docelowych przekracza limit na zapytanie.
  • Symbol 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 ustalony limit wykorzystania.
    • Podana forma płatności nie jest już ważna (np. karta kredytowa utraciła ważność).
  • OVER_QUERY_LIMIT oznacza, że usługa otrzymała zbyt wiele żądań z Twojej aplikacji w dozwolonym okresie.
  • REQUEST_DENIED oznacza, że usługa odmówiła użycia przez Twoją aplikację usługi Distance Matrix.
  • UNKNOWN_ERROR oznacza, że żądanie interfejsu Distance Matrix API nie mogło zostać przetworzone z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.

DistanceMatrixRow

Pole Wymagane Typ Opis
wymagane Tablica<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 nie istnieją źródła lub miejsca docelowe), funkcja zwraca pustą tablicę.

Wiersze są uporządkowane według wartości parametru origin w żądaniu. Każdy wiersz odpowiada źródłu, a każdy element w tym wierszu – parze źródła i wartości docelowej.

Każda tablica wierszy zawiera co najmniej 1 wpis elementu, który z kolei zawiera informacje o pojedynczej parze miejsc docelowych.

Więcej informacji znajdziesz w sekcji DistanceMatrixElement.

DistanceMatrixElement

Pole Wymagane Typ Opis
wymagane DistanceMatrixElementStatus

Stan elementu.

Więcej informacji znajdziesz w sekcji DistanceMatrixElementStatus.

opcjonalnie TextValueObject

Całkowita długość tej trasy wyrażona w metrach (wartość) i tekstowo. Wartość tekstowa korzysta z układu jednostek określonego za pomocą parametru unit w pierwotnym żądaniu lub regionu pochodzenia.

Więcej informacji znajdziesz w sekcji TextValueObject.

opcjonalnie TextValueObject

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

Więcej informacji znajdziesz w sekcji TextValueObject.

opcjonalnie TextValueObject

Czas potrzebny na pokonanie tej trasy na podstawie aktualnych i historycznych warunków na drodze. W przypadku opcji, których możesz użyć, aby poprosić o zwrócenie wartości optymistycznej, pesymistycznej lub najlepszego oszacowania, zapoznaj się z traffic_modelparametrem żądania. Czas trwania jest wyrażony w sekundach (pole wartości) i w postaci tekstu. Tekst jest lokalizowany 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 sekcji TextValueObject.

opcjonalnie Cena

Jeśli jest dostępna, zawiera całkowitą cenę (czyli całkowity koszt biletu) na tej trasie. Ta właściwość jest zwracana tylko w przypadku zapytań dotyczących transportu publicznego i tylko w przypadku przewoźników, dla których dostępne są informacje o opłatach.

Więcej informacji znajdziesz w sekcji Opłata.

Cena

Całkowita cena za przejazd na danej 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 wybranym języku.
wymagane liczba

Łączna kwota przejazdu w określonej walucie.

DistanceMatrixElementStatus

  • Symbol OK oznacza, że odpowiedź zawiera prawidłowy wynik.
  • Symbol NOT_FOUND oznacza, że nie udało się określić kodu geograficznego źródła lub miejsca docelowego tej pary.
  • ZERO_RESULTS – nie udało się znaleźć trasy między miejscem początkowym a docelowym.
  • MAX_ROUTE_LENGTH_EXCEEDED oznacza, że żądana trasa jest zbyt 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.