Usługa macierzy odległości

Przegląd

Usługa Distance Matrix Google oblicza odległość i czas podróży między wieloma punktami początkowymi i docelowymi przy użyciu określonego środka transportu.

Ta usługa nie zwraca szczegółowych informacji o trasie. Informacje o trasie, w tym polilinie i wskazówki tekstowe, można uzyskać, przekazując do usługi wyznaczania trasy pojedynczy punkt początkowy i docelowy.

Pierwsze kroki

Zanim zaczniesz korzystać z usługi macierzy odległości w interfejsie Maps JavaScript API, upewnij się, że interfejs Distance Matrix API (starszy) jest włączony w konsoli Google Cloud w tym samym projekcie, w którym skonfigurowano interfejs Maps JavaScript API.

Aby wyświetlić listę włączonych interfejsów API:

1. Otwórz konsolę Google Cloud.
2. Kliknij przycisk Wybierz projekt, a potem wybierz ten sam projekt, który został skonfigurowany na potrzeby interfejsu Maps JavaScript API, i kliknij Otwórz.
3. Na liście interfejsów API w panelu znajdź Distance Matrix API (starsza wersja).
4. Jeśli widzisz interfejs API na liście, nie musisz nic więcej robić. Jeśli interfejsu API nie ma na liście, włącz go na stronie https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com

Ceny i zasady

Ceny

Więcej informacji o cenach i zasadach korzystania z usługi macierzy odległości w JavaScript znajdziesz w sekcji Korzystanie i rozliczenia dotyczącej interfejsu Distance Matrix API (starsza wersja).

Uwaga: każde zapytanie wysyłane do usługi Distance Matrix jest ograniczone liczbą dozwolonych elementów, gdzie liczba punktów początkowych pomnożona przez liczbę punktów docelowych określa liczbę elementów.

Zasady

Korzystanie z usługi Distance Matrix musi być zgodne z zasadami opisanymi w przypadku interfejsu Distance Matrix API (starszego).

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

Dostęp do usługi macierzy odległości jest asynchroniczny, ponieważ interfejs Google Maps API musi wywołać zewnętrzny serwer. Dlatego musisz przekazać metodę wywołania zwrotnego, która zostanie wykonana po zakończeniu żądania, aby przetworzyć wyniki.

Dostęp do usługi Distance Matrix uzyskujesz w kodzie za pomocą obiektu konstruktora google.maps.DistanceMatrixService. Metoda DistanceMatrixService.getDistanceMatrix() inicjuje żądanie do usługi Distance Matrix, przekazując do niej literał obiektu DistanceMatrixRequest zawierający punkty początkowe, miejsca docelowe i tryb podróży, a także metodę wywołania zwrotnego do wykonania po otrzymaniu odpowiedzi.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

Zobacz przykład

DistanceMatrixRequest zawiera te pola:

• origins (wymagany) – tablica zawierająca co najmniej jeden ciąg znaków adresu, obiekt google.maps.LatLng lub obiekt Place, na podstawie których można obliczyć odległość i czas.
• destinations (wymagany) – tablica zawierająca co najmniej 1 ciąg adresu, obiekt google.maps.LatLng lub obiekt Place, dla którego chcesz obliczyć odległość i czas.
• travelMode (opcjonalny) – środek transportu, który ma być używany podczas obliczania wskazówek dojazdu. Zobacz sekcję dotyczącą środków transportu.
• transitOptions (opcjonalny) – opcje, które mają zastosowanie tylko do żądań, w których travelMode ma wartość TRANSIT. Prawidłowe wartości są opisane w sekcji opcje transportu.
• drivingOptions (opcjonalny) określa wartości, które mają zastosowanie tylko w przypadku żądań, w których travelMode ma wartość DRIVING. Prawidłowe wartości są opisane w sekcji Opcje jazdy.
• unitSystem (opcjonalny) – system jednostek, który ma być używany do wyświetlania odległości. Akceptowane wartości to:
  • google.maps.UnitSystem.METRIC (domyślnie)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (opcjonalny) – jeśli true, trasy między miejscami docelowymi i początkowymi będą obliczane tak, aby w miarę możliwości unikać autostrad.
• avoidTolls (opcjonalny) – jeśli true, trasa między punktami zostanie obliczona z użyciem dróg bez opłat, o ile to możliwe.

Tryby podróży

Podczas obliczania czasu i odległości możesz określić, z jakiego środka transportu chcesz skorzystać. Obecnie obsługiwane są te środki transportu:

• BICYCLING prośby o wskazówki dojazdu rowerem po ścieżkach rowerowych i preferowanych ulicach (obecnie dostępne tylko w Stanach Zjednoczonych i niektórych miastach w Kanadzie);
• DRIVING (domyślnie) oznacza standardowe wskazówki dojazdu z wykorzystaniem sieci dróg.
• TRANSIT prosi o wskazówki dojazdu transportem publicznym. Tę opcję można określić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. W sekcji opcje transportu publicznego znajdziesz dostępne opcje w przypadku tego typu żądań.
• WALKING prośby o wskazówki dojazdu pieszo po ścieżkach i chodnikach (jeśli są dostępne).

Opcje transportu publicznego

Usługa transportu publicznego jest obecnie w wersji eksperymentalnej. W tym etapie wprowadzimy limity szybkości, aby zapobiec nadużywaniu interfejsu API. W przyszłości wprowadzimy limit łącznej liczby zapytań na wczytanie mapy, aby zapewnić sprawiedliwe korzystanie z interfejsu API.

Dostępne opcje w przypadku żądania macierzy odległości różnią się w zależności od trybu podróży. W przypadku żądań w trakcie przesyłania opcje avoidHighways i avoidTolls są ignorowane. Możesz określić opcje routingu dotyczące transportu publicznego za pomocą literału obiektu TransitOptions.

Żądania dotyczące transportu publicznego są wrażliwe na czas. Obliczenia będą zwracane tylko dla terminów w przyszłości.

Literał obiektu TransitOptions zawiera te pola:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

Poniżej znajdziesz wyjaśnienia tych pól:

• arrivalTime (opcjonalny) określa żądany czas przyjazdu jako obiekt Date. Jeśli podasz czas przyjazdu, czas odjazdu zostanie zignorowany.
• departureTime (opcjonalny) określa żądany czas odjazdu jako obiekt Date. Element departureTime zostanie zignorowany, jeśli określono element arrivalTime. Jeśli nie podasz wartości dla departureTime ani arrivalTime, domyślnie zostanie przyjęta bieżąca data i godzina.
• modes (opcjonalny) to tablica zawierająca co najmniej 1 TransitMode literał obiektu. To pole może być uwzględnione tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Każdy element TransitMode określa preferowany środek transportu. Dozwolone wartości:
  • BUS oznacza, że obliczona trasa powinna uwzględniać przejazd autobusem.
  • RAIL oznacza, że obliczona trasa powinna uwzględniać przede wszystkim podróż pociągiem, tramwajem, koleją miejską i metrem.
  • SUBWAY oznacza, że obliczona trasa powinna uwzględniać podróż metrem.
  • TRAIN oznacza, że obliczona trasa powinna preferować podróż pociągiem.
  • TRAM oznacza, że obliczona trasa powinna uwzględniać podróż tramwajem lub koleją miejską.
• routingPreference (opcjonalny) określa preferencje dotyczące tras transportu publicznego. Dzięki tej opcji możesz zmienić preferencje dotyczące zwracanych opcji, zamiast akceptować domyślną najlepszą trasę wybraną przez interfejs API. To pole można określić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Dozwolone wartości:
  • FEWER_TRANSFERS oznacza, że obliczona trasa powinna uwzględniać ograniczoną liczbę przesiadek.
  • LESS_WALKING oznacza, że obliczona trasa powinna uwzględniać ograniczone ilości chodzenia.

Opcje jazdy

Użyj obiektu drivingOptions, aby określić godzinę odjazdu na potrzeby obliczenia najlepszej trasy do miejsca docelowego z uwzględnieniem przewidywanych warunków drogowych. Możesz też określić, czy szacowany czas dojazdu w ruchu ma być pesymistyczny, optymistyczny czy najbardziej prawdopodobny na podstawie historycznych i bieżących warunków drogowych.

Obiekt drivingOptions zawiera te pola:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Poniżej znajdziesz wyjaśnienia tych pól:

• departureTime (wymagany, aby literał obiektu drivingOptions był prawidłowy) określa żądany czas odjazdu jako obiekt Date. Wartość musi być ustawiona na bieżącą godzinę lub na godzinę w przyszłości. Nie może przypadać w przeszłości. (Interfejs API konwertuje wszystkie daty na UTC, aby zapewnić spójną obsługę w różnych strefach czasowych). Jeśli w żądaniu uwzględnisz parametr departureTime, interfejs API zwróci najlepszą trasę, biorąc pod uwagę oczekiwane warunki drogowe w danym momencie, a w odpowiedzi poda przewidywany czas przejazdu w korku (duration_in_traffic). Jeśli nie określisz godziny odjazdu (czyli jeśli żądanie nie zawiera parametru drivingOptions), zwrócona trasa będzie ogólnie dobrą trasą, która nie uwzględnia warunków drogowych.
• trafficModel (opcjonalny) określa założenia, które należy uwzględnić podczas obliczania czasu w ruchu. To ustawienie wpływa na wartość zwracaną w polu duration_in_traffic w odpowiedzi, która zawiera przewidywany czas przejazdu w warunkach ruchu na podstawie średnich wartości historycznych. Domyślna wartość to best_guess. Dozwolone wartości:
  • bestguess (domyślnie) oznacza, że zwrócona wartośćduration_in_traffic powinna być najlepszym oszacowaniem czasu podróżyduration_in_traffic na podstawie historycznych i bieżących informacji o natężeniu ruchu. Im bliżej departureTime jest do teraźniejszości, tym większe znaczenie ma ruch na żywo.
  • pessimistic oznacza, że zwrócony czas duration_in_traffic powinien być dłuższy niż rzeczywisty czas podróży duration_in_traffic w większości dni, chociaż w niektóre dni, gdy warunki drogowe są szczególnie złe, może być dłuż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, podróż może trwać krócej.

Poniżej znajdziesz przykładowy DistanceMatrixRequest dla tras przejazdu, w tym godzinę odjazdu i model ruchu:

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Odpowiedzi Distance Matrix API

Wywołanie usługi Distance Matrix zakończone powodzeniem zwraca obiekt DistanceMatrixResponse i obiekt DistanceMatrixStatus. Są one przekazywane do funkcji wywołania zwrotnego określonej w żądaniu.

Obiekt DistanceMatrixResponse zawiera informacje o odległości i czasie trwania dla każdej pary punktów początkowych i docelowych, dla której można było obliczyć trasę.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

Wyniki macierzy odległości

Obsługiwane pola w odpowiedzi są opisane poniżej.

• originAddresses to tablica zawierająca lokalizacje przekazane w polu origins żądania interfejsu Distance Matrix API. Adresy są zwracane w formacie geokodera.
• destinationAddresses to tablica zawierająca lokalizacje przekazane w polu destinations w formacie zwróconym przez geokoder.
• rows to tablica obiektów DistanceMatrixResponseRow, w której każdy wiersz odpowiada źródłu.
• elements są elementami podrzędnymi rows i odpowiadają parze składającej się z pochodzenia wiersza i każdego miejsca docelowego. Zawierają one informacje o stanie, czasie trwania, odległości i cenie (jeśli są dostępne) dla każdej pary miejsc docelowych.
• Każdy element element zawiera te pola:
  • status: listę możliwych kodów stanu znajdziesz w sekcji Kody stanu.
  • duration: czas potrzebny na pokonanie tej trasy, wyrażony w sekundach (pole value) i jako text. Wartość tekstowa jest sformatowana zgodnie z unitSystem podanym w żądaniu (lub w jednostkach metrycznych, jeśli nie podano preferencji).
  • duration_in_traffic: czas potrzebny na pokonanie tej trasy z uwzględnieniem aktualnych warunków drogowych, wyrażony w sekundach (pole value) i jako text. Wartość tekstowa jest sformatowana zgodnie z unitSystem podanym w żądaniu (lub w jednostkach metrycznych, jeśli nie podano preferencji). Wartość duration_in_traffic jest zwracana tylko wtedy, gdy dostępne są dane o ruchu, wartość mode jest ustawiona na driving, a wartość departureTime jest uwzględniona w polu distanceMatrixOptions w żądaniu.
  • distance: całkowita odległość na tej trasie wyrażona w metrach (value) i jako text. Wartość tekstowa jest sformatowana zgodnie z unitSystem określonym w żądaniu (lub w jednostkach metrycznych, jeśli nie podano preferencji).
  • fare: zawiera całkowitą cenę biletu (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. Informacje obejmują:
    • currency: kod waluty w formacie ISO 4217 wskazujący walutę, w której wyrażona jest kwota.
    • value: łączna kwota opłaty w walucie określonej powyżej.

Kody stanu

Odpowiedź interfejsu Distance Matrix API zawiera kod stanu dla całej odpowiedzi, a także stan każdego elementu.

Kody stanu odpowiedzi

Kody stanu, które mają zastosowanie do DistanceMatrixResponse, są przekazywane w obiekcie DistanceMatrixStatus i obejmują:

• OK – żądanie jest prawidłowe. Ten stan może być zwracany nawet wtedy, gdy nie znaleziono żadnych tras między miejscami początkowymi a docelowymi. Informacje o stanie na poziomie elementu znajdziesz w sekcji Kody stanu elementu.
• INVALID_REQUEST – podane żądanie było nieprawidłowe. Często jest to spowodowane brakiem wymaganych pól. Zobacz listę obsługiwanych pól powyżej.
• MAX_ELEMENTS_EXCEEDED – liczba kombinacji miejsc docelowych i początkowych przekracza limit zapytań.
• MAX_DIMENSIONS_EXCEEDED – Twoje żądanie zawierało więcej niż 25 punktów początkowych lub więcej niż 25 punktów docelowych.
• OVER_QUERY_LIMIT – Twoja aplikacja poprosiła o zbyt wiele elementów w dozwolonym czasie. Jeśli spróbujesz ponownie po upływie odpowiedniego czasu, żądanie powinno się powieść.
• REQUEST_DENIED – usługa odmówiła użycia usługi Macierz odległości przez Twoją stronę internetową.
• UNKNOWN_ERROR – nie udało się przetworzyć żądania interfejsu Distance Matrix API z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.

Kody stanu elementu

W przypadku poszczególnych obiektów DistanceMatrixElement stosowane są te kody stanu:

• NOT_FOUND – nie udało się określić współrzędnych geograficznych źródła lub miejsca docelowego tej pary.
• OK – odpowiedź zawiera prawidłowy wynik.
• ZERO_RESULTS – nie udało się znaleźć trasy między miejscem początkowym a docelowym.

Analizowanie wyników

Obiekt DistanceMatrixResponse zawiera jeden obiekt row dla każdego źródła przekazanego w żądaniu. Każdy wiersz zawiera pole element dla każdej pary danego pochodzenia z podanymi miejscami docelowymi.

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}