Usługa macierzy odległości

Opis

Usługa Macierz odległości Google oblicza odległość i czas trwania podróży między wieloma miejscami docelowymi i miejscami docelowymi z wykorzystaniem danego środka podróży.

Ta usługa nie zwraca szczegółowych informacji o trasie. Informacje o trasach, w tym linie łamane i wskazówki tekstowe, można uzyskać, przekazując do usługi wyznaczania tras żądane pojedyncze miejsce wylotu i celu podróży.

Pierwsze kroki

Zanim użyjesz usługi matrycy odległości w interfejsie Maps JavaScript API, sprawdź, czy interfejs Distance Matrix API jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany 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 projekt skonfigurowany na potrzeby interfejsu Maps JavaScript API i kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Distance Matrix API.
  4. Jeśli widzisz interfejs API na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
    1. Aby wyświetlić kartę Biblioteka, u góry strony wybierz WŁĄCZ API. Możesz też wybrać Biblioteka w menu po lewej stronie.
    2. Wyszukaj Distance Matrix API, a następnie wybierz go z listy wyników.
    3. Wybierz WŁĄCZ. Gdy proces się zakończy, na liście w panelu na liście interfejsów API pojawi się Distance Matrix API.

Ceny i zasady

Ceny

16 lipca 2018 roku zaczęliśmy obowiązywać w przypadku Map, tras i miejsc nowy abonament rozliczany według wykorzystania. Aby dowiedzieć się więcej o nowych cenach i limitach wykorzystania związanych z usługą matrycy odległości JavaScript, przeczytaj artykuł Korzystanie i rozliczenia dotyczący 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 źródło razy liczba miejsc docelowych określa liczbę elementów.

Zasady

Korzystanie z usługi matrycy odległości musi być zgodne z zasadami dotyczącymi interfejsu Distance Matrix API.

Żądania macierzy odległości

Dostęp do usługi macierz odległości jest asynchroniczny, ponieważ interfejs API Map Google musi wywoływać serwer zewnętrzny. Dlatego musisz przekazać metodę wywołania zwrotnego, która zostanie wykonana po zrealizowaniu żądania w celu przetworzenia wyników.

Dostęp do usługi tablicy odległości w kodzie uzyskuje się za pomocą obiektu konstruktora google.maps.DistanceMatrixService. Metoda DistanceMatrixService.getDistanceMatrix() inicjuje żądanie do usługi macierzy odległości, przekazując jej literał obiektu DistanceMatrixRequest zawierający miejsca początkowe, miejsca docelowe i tryb podróży, a także metodę wywołania zwrotnego, która jest uruchamiana 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, na podstawie których obliczana jest odległość i czas.
  • destinations (wymagany) – tablica zawierająca co najmniej 1 ciąg adresu, obiekty google.maps.LatLng lub obiekty Place, dla których ma zostać obliczona odległość i czas.
  • travelMode (opcjonalny) – środek transportu używany przy obliczaniu wskazówek dojazdu. Zapoznaj się z sekcją poświęconą trybom podróży.
  • transitOptions (opcjonalny) – opcje mające zastosowanie tylko do żądań, w których travelMode to TRANSIT. Prawidłowe wartości są opisane w sekcji dotyczącej opcji transportu.
  • drivingOptions (opcjonalny) określa wartości mające zastosowanie tylko do żądań, w których travelMode to DRIVING. Prawidłowe wartości są opisane 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 true, trasy między miejscem wylotu a miejscem docelowym będą obliczane tak, aby w miarę możliwości unikać autostrad.
  • avoidTolls (opcjonalny) – jeśli jest to true, wskazówki dojazdu między punktami będą w miarę możliwości obliczane z wykorzystaniem tras bez opłat.

Środki transportu

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

  • BICYCLING prosi o wskazówki dojazdu rowerem po ścieżkach rowerowych i ulubionych ulicach (obecnie ta funkcja jest dostępna tylko w USA i niektórych miastach Kanady).
  • DRIVING (domyślnie) wskazuje standardowe wskazówki dojazdu z użyciem 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. Zapoznaj się z sekcją poświęconą opcjom transportu, aby poznać opcje dostępne w przypadku tego typu próśb.
  • WALKING prosi o wyznaczenie trasy pieszej z uwzględnieniem ścieżek dla pieszych i chodników (w miarę możliwości).

Opcje transportu publicznego

Usługa Transport publiczny ma obecnie charakter „eksperymentalny”. Na tym etapie wdrożymy limity liczby żądań, aby zapobiec nadużyciom interfejsów API. Ostatecznie wprowadzimy limit łącznej liczby zapytań na wczytanie mapy zgodnie z zasadą dozwolonego użytku interfejsu API.

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

Prośby o transport są ważne w czasie. 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śniamy te pola:

  • arrivalTime (opcjonalny) określa żądaną godzinę przyjazdu jako obiekt Date. Jeśli podasz godzinę przyjazdu, godzina odjazdu zostanie zignorowana.
  • departureTime (opcjonalny) określa żądaną godzinę odjazdu jako obiekt Date. Jeśli określono arrivalTime, departureTime zostanie zignorowana. Jeśli w polu departureTime ani arrivalTime nie określono żadnej wartości, przyjmuje się wartość domyślną teraz (czyli bieżący czas).
  • modes (opcjonalny) to tablica zawierająca co najmniej 1 literę obiektów TransitMode. To pole można uwzględnić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Każdy element TransitMode określa preferowany środek transportu. Dozwolone są te wartości:
    • BUS wskazuje, że obliczona trasa powinna preferować podróż autobusem.
    • RAIL wskazuje, że obliczona trasa powinna preferować podróżowanie pociągiem, tramwajem, kolejką linową i metrem.
    • 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ć przejazdy tramwajem i kolejką miejska.
  • routingPreference (opcjonalny) – określa preferencje dotyczące tras transportu publicznego. Dzięki tej opcji możesz odchylić 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ę transferów.
    • LESS_WALKING wskazuje, że obliczona trasa powinna preferować ograniczoną ilość ruchu.

Opcje jazdy

Użyj obiektu drivingOptions, aby podać godzinę wyjazdu na potrzeby obliczenia najlepszej trasy do miejsca docelowego przy oczekiwanych warunkach na drodze. Możesz też określić, czy szacowany czas uwzględniania natężenia ruchu ma być pesymistyczny, optymistyczny czy też najdokładniejszy na podstawie historycznych danych o natężeniu ruchu i aktualnego natężenia ruchu.

Obiekt drivingOptions zawiera te pola:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Poniżej objaśniamy te pola:

  • departureTime (wymagany do prawidłowego literału obiektu drivingOptions) określa wymagany czas odjazdu jako obiekt Date. Wartość musi być ustawiona na bieżącą lub przyszłą godzinę. Nie może przypadać w przeszłości. (Interfejs API konwertuje wszystkie daty na UTC, aby zapewnić spójną obsługę we wszystkich strefach czasowych). Jeśli w żądaniu umieścisz departureTime, interfejs API zwróci najlepszą trasę przy uwzględnieniu oczekiwanych warunków ruchu w danym momencie i uwzględni w odpowiedzi przewidywany czas w ruchu (duration_in_traffic). Jeśli nie podasz godziny odjazdu (czyli nie zawiera ono drivingOptions), zwrócona trasa będzie dobrą trasą bez uwzględniania warunków drogowych.
  • trafficModel (opcjonalny) określa założenia, które zostaną użyte podczas obliczania czasu w ruchu. To ustawienie wpływa na wartość zwracaną w polu duration_in_traffic w odpowiedzi, które zawiera przewidywany czas w ruchu określony na podstawie średnich historycznych. Domyślna wartość to best_guess. Dozwolone są te wartości:
    • bestguess (wartość domyślna) wskazuje, że zwracana wartość duration_in_traffic powinna być najdokładniejszym oszacowaniem czasu podróży na podstawie dostępnych danych zarówno o historycznych warunkach, jak i o aktualnym natężeniu ruchu. Rzeczywisty ruch na stronie staje się ważniejszy, tym bliżej departureTime znajduje się teraz.
    • pessimistic wskazuje, że zwracana wartość duration_in_traffic powinna być w większości dni dłuższy niż rzeczywisty czas podróży, chociaż czasami liczba dni, gdy warunki na drodze są szczególnie złe, może przekraczać tę wartość.
    • optimistic wskazuje, że zwracana wartość duration_in_traffic powinna być krótsza niż rzeczywisty czas podróży w większości dni, chociaż w niektórych dniach, gdy warunki na drodze są szczególnie dobre, czas może być krótszy od tej wartości.

Poniżej znajdziesz przykład DistanceMatrixRequest dotyczący tras samochodowych z podaniem godziny 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

Pomyślne 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 miejsca wylotu i celu podróży, dla której można 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 odpowiedzi zostały opisane poniżej.

  • originAddresses to tablica zawierająca lokalizacje przekazane w polu origins w żądaniu macierzy odległości. Adresy są zwracane, ponieważ są sformatowane przez geokodera.
  • destinationAddresses to tablica zawierająca lokalizacje przekazane w polu destinations w formacie zwróconym przez geokodera.
  • rows to tablica obiektów DistanceMatrixResponseRow, z których każdy wiersz odpowiada pochodzeniu.
  • elements są elementami podrzędnymi elementu rows i odpowiadają parowaniu punktu początkowego wiersza z każdym miejscem docelowym. Zawierają one stan, czas podróży, odległość i informacje o taryfach (jeśli są dostępne) dla każdej pary miejsca wylotu i przylotu.
  • Każdy element element zawiera te pola:
    • status: listę możliwych kodów stanu znajdziesz w sekcji Kody stanu.
    • duration: czas podróży tej trasy wyrażony w sekundach (pole value) i w postaci text. Wartość tekstowa jest sformatowana zgodnie z wartością unitSystem określoną w żądaniu (lub w danych, jeśli nie określono preferencji).
    • duration_in_traffic: czas potrzebny na pokonanie tej trasy z uwzględnieniem aktualnych warunków drogowych, wyrażony w sekundach (pole value) i w postaci text. Wartość tekstowa jest sformatowana zgodnie z wartością unitSystem określoną w żądaniu (lub w danych, jeśli nie określono preferencji). Wartość duration_in_traffic jest zwracana tylko klientom korzystającym z abonamentu Premium Google Maps Platform, jeśli dostępne są dane o ruchu, mode ma wartość driving, a departureTime jest zawarty w polu distanceMatrixOptions w żądaniu.
    • distance: całkowita odległość tej trasy wyrażona w metrach (value) i w postaci text. Wartość tekstowa jest sformatowana zgodnie z wartością unitSystem określoną w żądaniu (lub w danych, jeśli nie określono preferencji).
    • fare: zawiera łączną cenę (czyli łączne koszty biletu) na danej trasie. Ta właściwość jest zwracana tylko w przypadku żądań transportu publicznego i tylko przewoźników, dla których dostępne są informacje o opłatach. Informacje te obejmują:
      • currency: kod waluty w formacie ISO 4217 wskazujący walutę, w której wyrażona jest kwota.
      • value: łączna kwota taryfy w walucie określonej powyżej.

Kody stanu

Odpowiedź tablicy odległości zawiera kod stanu całej odpowiedzi oraz stan każdego elementu.

Kody stanu odpowiedzi

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

  • OK – żądanie jest prawidłowe. Ten stan może zostać zwrócony, nawet jeśli nie znaleziono tras między punktami początkowymi i miejscami docelowymi. Informacje o stanie na poziomie elementu znajdziesz w sekcji Kody stanu elementu.
  • INVALID_REQUEST – przesłane żądanie było nieprawidłowe. Jest to często spowodowane brakiem wymaganych pól. Listę obsługiwanych pól znajdziesz powyżej.
  • MAX_ELEMENTS_EXCEEDED – iloczyn miejsc początkowych i docelowych przekracza limit na zapytanie.
  • MAX_DIMENSIONS_EXCEEDED – Twoje żądanie zawierało 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 to zrobić ponownie, prośba może zostać zrealizowana.

Kody stanu elementu

Te kody stanu mają zastosowanie do określonych obiektów DistanceMatrixElement:

  • NOT_FOUND – nie udało się przetworzyć geokodu miejsca wylotu ani celu podróży.
  • OK – odpowiedź zawiera prawidłowy wynik.
  • ZERO_RESULTS – nie znaleziono trasy między miejscem wylotu a celem podróży.

Analizowanie wyników

Obiekt DistanceMatrixResponse zawiera po jednym obiekcie row dla każdego punktu początkowego przekazanego w żądaniu. Każdy wiersz zawiera pole element dla każdej pary 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];
      }
    }
  }
}