Usługa macierzy odległości

Przegląd

Usługa macierzy odległości od Google oblicza odległość i czas podróży między różnymi punktami początkowymi i miejscami docelowymi, korzystając z danego środka transportu.

Usługa nie zwraca szczegółowych informacji o trasie. Informacje o trasie, w tym linie łamane i wskazówki tekstowe, można uzyskać, przekazując wybrane pojedyncze miejsce początkowe i miejsce docelowe do usługi wyznaczania wskazówek dojazdu.

Pierwsze kroki

Zanim użyjesz usługi Macierz odległości w Maps JavaScript API, upewnij się, że interfejs DISTANCE Matrix API jest włączony w konsoli Google Cloud w tym samym projekcie, który konfigurujesz dla Maps JavaScript API.

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

1. Otwórz konsolę Google Cloud.
2. Kliknij przycisk Wybierz projekt, a następnie wybierz ten sam projekt, który został skonfigurowany dla interfejsu Maps JavaScript API, i kliknij Otwórz.
3. Na liście interfejsów API w panelu znajdź Reach Matrix API.
4. Jeśli interfejs API jest widoczny na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
   1. U góry strony wybierz WŁĄCZ API, aby wyświetlić kartę Biblioteka. Możesz też w menu po lewej stronie wybrać Biblioteka.
   2. Wyszukaj DISTANCE Matrix API, a potem wybierz go z listy wyników.
   3. Kliknij WŁĄCZ. Gdy proces się zakończy, na liście interfejsów API w panelu pojawi się Reach Matrix API.

Ceny i zasady

Ceny

16 lipca 2018 r. wszedł w życie nowy abonament z płatnościami według wykorzystania w Mapach, trasach i miejscach. Aby dowiedzieć się więcej o nowych cenach i limitach wykorzystania w związku z korzystaniem z usługi macierzy odległości w języku JavaScript, przeczytaj artykuł na temat użytkowania i płatności za pomocą interfejsu DISTANCE Matrix API.

Uwaga: każde zapytanie wysłane do usługi macierzy odległości jest ograniczone liczbą dozwolonych elementów, gdzie liczba elementów origins pomnożona przez liczbę miejsc docelowych określa liczbę elementów.

Zasady

Korzystanie z usługi Macierz odległości musi być zgodne z zasadami dotyczącymi jej interfejsu.

Żądania macierzy odległości

Dostęp do usługi Macierz odległości jest asynchroniczny, ponieważ interfejs Google Maps API musi wywołać serwer zewnętrzny. Z tego powodu w celu przetworzenia wyników musisz przekazać metodę wywołania zwrotnego, która zostanie wykonana po zakończeniu żądania.

Dostęp do usługi macierzy odległości w kodzie uzyskujesz za pomocą obiektu konstruktora google.maps.DistanceMatrixService. Metoda DistanceMatrixService.getDistanceMatrix() inicjuje żądanie do usługi macierzy odległości, przekazując mu literał obiektu DistanceMatrixRequest zawierający miejsca początkowe, miejsca docelowe i tryb podróży, a także metodę wywołania zwrotnego, która ma zostać wykonana 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 1 ciąg adresu, obiekty google.maps.LatLng lub obiekty Place, z których ma zostać obliczona odległość i czas.
• destinations (wymagany) – tablica zawierająca co najmniej 1 ciąg adresu, obiekty google.maps.LatLng lub obiekty Place, do których mają zostać obliczone czas i odległość.
• travelMode (opcjonalny) – środek transportu używany przy obliczaniu wskazówek dojazdu. Zapoznaj się z sekcją dotyczącą środków transportu.
• transitOptions (opcjonalny) – opcje dotyczące tylko żądań, w których travelMode to TRANSIT. Prawidłowe wartości zostały opisane w sekcji dotyczącej opcji transportu.
• drivingOptions (opcjonalny) określa wartości, które mają zastosowanie tylko do żądań, w których travelMode to DRIVING. Prawidłowe wartości znajdziesz w sekcji Opcje jazdy.
• unitSystem (opcjonalny) – system jednostek używany do wyświetlania odległości. Akceptowane wartości:
  • google.maps.UnitSystem.METRIC (domyślnie)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (opcjonalny) – jeśli jest true, trasy między miejscem wylotu a celem podróży będą obliczane w taki sposób, by w miarę możliwości ominąć autostrady.
• avoidTolls (opcjonalny) – jeśli jest true, wskazówki dojazdu między punktami będą obliczane z wykorzystaniem tras innych niż płatne, gdy tylko będzie to możliwe.

Środki transportu

Podczas obliczania czasu i odległości możesz wybrać środek transportu. Obecnie obsługiwane są te środki transportu:

• BICYCLING prosi o wskazówki dojazdu rowerem i preferowane ulice (obecnie dostępne tylko w niektórych miastach w USA i niektórych Kanadzie).
• DRIVING (domyślnie) wskazuje standardowe wskazówki dojazdu przez sieć drogową.
• TRANSIT prosi o wskazówki dojazdu transportem publicznym. Tę opcję można określić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Listę opcji dostępnych w przypadku tego typu żądań znajdziesz w sekcji dotyczącej opcji przesyłania.
• WALKING prosi o wskazówki dojazdu przebiegające wzdłuż ścieżek dla pieszych i chodników (jeśli są dostępne).

Opcje transportu publicznego

Usługa Transport publiczny jest obecnie „eksperymentalna”. Na tym etapie będziemy wprowadzać limity liczby żądań, aby zapobiegać nadużywaniu interfejsu API. Ostatecznie nałożymy ograniczenie łącznej liczby zapytań na wczytanie mapy na podstawie dozwolonego użytku interfejsu API.

Dostępne opcje żądania macierzy odległości różnią się w zależności od środka transportu. W przypadku żądań związanych z transportem publicznym opcje avoidHighways i avoidTolls są ignorowane. Opcje routingu dla transportu publicznego możesz określić za pomocą literału obiektu TransitOptions.

Prośby o transport publiczny są pilne. Obliczenia będą zwracane tylko dla okresów w przyszłości.

Literał obiektu TransitOptions zawiera te pola:

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

Poniżej objaśniono te pola:

• arrivalTime (opcjonalny) określa żądaną godzinę przyjazdu jako obiekt Date. Jeśli podasz godzinę przyjazdu, zostanie ona zignorowana.
• departureTime (opcjonalny) określa docelową godzinę odjazdu w postaci obiektu Date. Jeśli określisz parametr arrivalTime, pole departureTime zostanie zignorowane. Jeśli nie podasz żadnej wartości w polu departureTime ani w zasadzie arrivalTime, przyjmuje się wartość domyślną teraz (czyli aktualnej godziny).
• modes (opcjonalny) to tablica zawierająca co najmniej 1 literał obiektu TransitMode. To pole można uwzględnić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Każdy atrybut TransitMode określa preferowany środek transportu. Dozwolone są te wartości:
  • BUS oznacza, że obliczona trasa powinna preferować podróż autobusem.
  • RAIL oznacza, że obliczona trasa powinna preferować podróż pociągiem, tramwajem, tramwajem i metrem.
  • 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 i kolejką lekką.
• routingPreference (opcjonalny) określa preferencje dotyczące tras transportu publicznego. Dzięki tej opcji możesz zniekształcać zwracane opcje, 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 są te wartości:
  • FEWER_TRANSFERS wskazuje, że obliczona trasa powinna preferować ograniczoną liczbę przesiadek.
  • LESS_WALKING oznacza, że obliczona trasa powinna preferować ograniczoną długość trasy pieszej.

Opcje jazdy

Użyj obiektu drivingOptions, aby określić czas odjazdu, który pozwoli Ci wyznaczyć najlepszą trasę do miejsca docelowego przy oczekiwanych warunkach na drodze. Możesz też określić, czy szacowany czas w ruchu ma być pesymistyczny, optymistyczny czy optymistyczny na podstawie historycznych danych o warunkach i aktualnym natężeniu ruchu.

Obiekt drivingOptions zawiera te pola:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Poniżej objaśniono te pola:

• departureTime (wymagany, aby literał obiektu drivingOptions był prawidłowy) określa żądany czas wylotu jako obiekt Date. Wartość musi być ustawiona na bieżącą godzinę lub datę w przyszłości. Nie może to być data w przeszłości. Interfejs API konwertuje wszystkie daty na UTC, aby zapewnić spójność obsługi w różnych strefach czasowych. Jeśli w żądaniu umieścisz departureTime, interfejs API zwróci najlepszą trasę przy spodziewanych w danym momencie warunkach na drodze, a w odpowiedzi uwzględni przewidywany czas wystąpienia ruchu (duration_in_traffic). Jeśli nie określisz godziny odjazdu (czyli jeśli żądanie nie zawiera atrybutu drivingOptions), zwrócona trasa jest zwykle dobrą trasą bez uwzględnienia warunków drogowych.
• trafficModel (opcjonalny) określa założenia, które należy stosować przy obliczaniu czasu w ruchu. To ustawienie wpływa na wartość zwracaną w polu duration_in_traffic w odpowiedzi, która zawiera przewidywany czas ruchu na podstawie średnich wartości historycznych. Domyślna wartość to best_guess. Dozwolone są te wartości:
  • bestguess (wartość domyślna) wskazuje, że zwrócona wartość duration_in_traffic powinna być najdokładniejszym szacowanym czasem podróży, biorąc pod uwagę zarówno historyczne warunki, jak i aktualne natężenie ruchu. Aktualne natężenie ruchu staje się ważniejsze, im bliżej jest departureTime.
  • pessimistic oznacza, że zwrócona wartość duration_in_traffic powinna być dłuższy niż rzeczywisty czas podróży w większość dni, choć w dni o szczególnie niekorzystnych warunkach na drogach może on przekraczać tę wartość.
  • optimistic oznacza, że zwrócona wartość duration_in_traffic powinna być krótsza niż rzeczywisty czas podróży w większość dni, ale w niektórych dniach, w których panuje wyjątkowo dobre warunki na drodze, może być on krótszy od tej wartości.

Poniżej znajdziesz przykładowy DistanceMatrixRequest dotyczący tras dojazdu z uwzględnieniem czasu odjazdu i modelu natężenia 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 macierzy odległości

Udane wywołanie usługi macierzy odległości 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 punktu początkowego i docelowego, dla której można wyznaczyć 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 zostały objaśnione poniżej.

• originAddresses to tablica zawierająca lokalizacje przekazane w polu origins żądania macierzy odległości. Adresy są zwracane w miarę ich formatowania przez geokoder.
• destinationAddresses to tablica zawierająca lokalizacje przekazane w polu destinations w formacie zwracanym przez geokoder.
• rows to tablica obiektów DistanceMatrixResponseRow, przy czym każdy wiersz odpowiada swojemu punktowi początkowemu.
• elements to elementy podrzędne tagu rows i odpowiadają parowaniu punktu początkowego wiersza z każdym miejscem docelowym. Zawierają one stan, czas trwania podróży, odległość i informacje o cenie (jeśli są dostępne) dla każdej pary wylotu i celu podróży.
• Każdy element element zawiera te pola:
  • status: lista możliwych kodów stanu znajduje się na stronie Kody stanu.
  • duration: czas potrzebny na pokonanie tej trasy, wyrażony w sekundach (pole value) i jako text. Wartość tekstowa jest sformatowana zgodnie z atrybutem unitSystem określonym w żądaniu (lub w danych, jeśli nie określono preferencji).
  • duration_in_traffic: czas potrzebny na przebycie tej trasy z uwzględnieniem bieżących warunków na drodze, wyrażony w sekundach (pole value) i w formacie text. Wartość tekstowa jest sformatowana zgodnie z atrybutem unitSystem określonym w żądaniu (lub w danych, jeśli nie określono preferencji). Pole duration_in_traffic jest zwracane tylko wtedy, gdy są dostępne dane o ruchu, mode ma wartość driving, a pole departureTime jest zawarte w polu distanceMatrixOptions w żądaniu.
  • distance: łączna odległość na tej trasie wyrażona w metrach (value) i jako text. Wartość tekstowa jest sformatowana zgodnie z zasadą unitSystem określoną w żądaniu (lub w wskaźniku, jeśli nie określono preferencji).
  • fare: zawiera łączną cenę (czyli łączne koszty 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, którzy mają dostęp do informacji o cenie. Są to między innymi:
    • 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ź macierzy odległości zawiera kod stanu odpowiedzi jako całości oraz stan każdego elementu.

Kody stanu odpowiedzi

Kody stanu dotyczące obiektu DistanceMatrixResponse są przekazywane w obiekcie DistanceMatrixStatus i obejmują:

• OK – żądanie jest prawidłowe. Ten stan może zostać zwrócony nawet wtedy, gdy nie znaleziono żadnych tras między żadnym miejscem wylotu a miejscem docelowym. Informacje o stanie na poziomie elementu znajdziesz w sekcji Kody stanu elementu.
• INVALID_REQUEST – przesłane żądanie było nieprawidłowe. Przyczyną tej sytuacji jest często brak wymaganych pól. Zobacz listę obsługiwanych pól powyżej.
• MAX_ELEMENTS_EXCEEDED – iloczyn miejsc wylotu i miejsc docelowych przekracza limit dla poszczególnych zapytań.
• MAX_DIMENSIONS_EXCEEDED – Twoja prośba zawierała ponad 25 punktów początkowych lub ponad 25 miejsc docelowych.
• OVER_QUERY_LIMIT – Twoja aplikacja zażądała zbyt wielu elementów w dozwolonym czasie. Żądanie powinno zostać zrealizowane, jeśli spróbujesz ponownie po upływie rozsądnego czasu.
• REQUEST_DENIED – usługa odmówiła użycia usługi macierzy odległości przez Twoją stronę internetową.
• UNKNOWN_ERROR – nie udało się przetworzyć żądania macierzy odległości z powodu błędu serwera. Jeśli spróbujesz jeszcze raz, żądanie może zostać zrealizowane.

Kody stanu elementu

Te kody stanu mają zastosowanie do konkretnych obiektów DistanceMatrixElement:

• NOT_FOUND – nie udało się przetworzyć danych geograficznych punktu początkowego lub docelowego pary.
• OK – odpowiedź zawiera prawidłowy wynik.
• ZERO_RESULTS – nie udało się znaleźć trasy między miejscem wylotu a celem podróży.

Analiza wyników

Obiekt DistanceMatrixResponse zawiera po 1 obiekcie row dla każdego punktu początkowego, który został przekazany w żądaniu. Każdy wiersz zawiera pole element na potrzeby każdego parowania tego punktu początkowego 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];
      }
    }
  }
}