Usługa macierzy odległości

Omówienie

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

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

Pierwsze kroki

Zanim użyjesz usługi Distance Matrix w interfejsie Maps JavaScript API, najpierw sprawdź, czy interfejs Distance Matrix API jest włączony w Konsoli Google Cloud w tym samym projekcie, który został skonfigurowany pod kątem interfejsu 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 skonfigurowany dla interfejsu Maps JavaScript API i kliknij Otwórz.
  3. Na liście interfejsów API w panelu odszukaj interfejs Distance Matrix API.
  4. Jeśli interfejs API jest widoczny na liście, nie musisz nic więcej robić. Jeśli interfejs API nie jest wymieniony, włącz go:
    1. U góry strony kliknij WŁĄCZ INTERFEJS API, aby wyświetlić kartę Biblioteka. Możesz też w menu po lewej stronie wybrać Biblioteka.
    2. Wyszukaj Distance Matrix API i wybierz go z listy wyników.
    3. Wybierz WŁĄCZ. Po zakończeniu procesu interfejs Distance Matrix API pojawi się na liście interfejsów API w panelu.

Ceny i zasady

Ceny

Od 16 lipca 2018 r. w przypadku Map, Tras i Miejsc obowiązuje nowy plan taryfowy „Pay-as-you-go”. Więcej informacji o nowych cenach i limitach korzystania z usługi Distance Matrix w JavaScript znajdziesz w sekcji Korzystanie i płatności w Distance Matrix API.

Uwaga: każde zapytanie wysłane do usługi Distance Matrix jest ograniczone liczbą dozwolonych elementów, gdzie liczba początków pomnożona przez liczbę miejsc docelowych definiuje liczbę elementów.

Zasady

Korzystanie z usługi Distance Matrix musi być zgodne z zasadami opisanymi w Distance Matrix API.

Prośby o macierz odległości

Dostęp do usługi Distance Matrix jest asynchroniczny, ponieważ interfejs API Map Google musi wykonać wywołanie do zewnętrznego serwera. W tym celu musisz przekazać metodę callback, która zostanie wykonana po zakończeniu przetwarzania żądania.

Dostęp do usługi Distance Matrix w kodzie uzyskujesz za pomocą obiektu konstruktora google.maps.DistanceMatrixService. Metoda DistanceMatrixService.getDistanceMatrix() inicjuje żądanie do usługi Distance Matrix, przekazując jej literał obiektu DistanceMatrixRequest zawierający punkty początkowe, punkty docelowe i tryb podróży, a także metodę wywołania, która zostanie 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

Formularz DistanceMatrixRequest zawiera te pola:

  • origins (wymagany) – tablica zawierająca co najmniej 1 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 znaków adresu, obiekty google.maps.LatLng lub obiekty Place, dla których ma zostać obliczona odległość i czas.
  • travelMode (opcjonalnie) – środek transportu, którego należy użyć podczas obliczania trasy. Zobacz sekcję o środkach transportu.
  • transitOptions (opcjonalnie) – opcje, które mają zastosowanie tylko do żądań, w których travelMode to TRANSIT. Prawidłowe wartości są opisane w sekcji Opcje tranzytu.
  • drivingOptions (opcjonalnie) określa wartości, które mają zastosowanie tylko do żądań, w których travelMode to DRIVING. Prawidłowe wartości są opisane w sekcji Opcje sterowania.
  • unitSystem (opcjonalnie) – system jednostek do stosowania podczas wyświetlania odległości. Akceptowane wartości to:
    • google.maps.UnitSystem.METRIC (domyślnie)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (opcjonalnie) – jeśli true, trasy między punktami początkowymi a docelowymi będą obliczane w taki sposób, aby w miarę możliwości unikać autostrad.
  • avoidTolls (opcjonalny) – jeśli true, trasy między punktami będą obliczane z użyciem tras bezpłatnych, o ile to możliwe.

Tryby podróży

Podczas obliczania czasu i odległości możesz określić, jaki środek transportu ma być użyty. Obecnie obsługiwane są te tryby podróży:

  • BICYCLING żądania wskazówek 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 samochodem korzystające z sieci drogowej.
  • TRANSIT zapytania o trasę dojazdu transportem publicznym. Tę opcję można określić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Więcej informacji o dostępnych opcjach tego typu prośby znajdziesz w sekcji Opcje dotyczące przejazdu.
  • WALKING żądania wskazówek dojazdu pieszo po chodnikach i ścieżkach (gdzie są dostępne).

Opcje transportu

Usługa dotycząca transportu publicznego jest obecnie w fazie eksperymentalnej. W tym czasie wprowadzimy limity szybkości, aby zapobiec nadużywaniu interfejsu API. Ostatecznie wprowadzimy limit łącznej liczby zapytań na pobieranie mapy na podstawie zasad uczciwego korzystania z interfejsu API.

Dostępne opcje w przypadku zapytania o macierz odległości różnią się w zależności od trybu podróży. W przypadku żądań dotyczących tranzytu opcje avoidHighways i avoidTolls są ignorowane. Opcje kierowania dotyczące transportu możesz określić za pomocą literału obiektu TransitOptions.

Prośby o przeniesienie są pilne. Obliczenia będą zwracane tylko dla przyszłych momentów.

Obiekt TransitOptions zawiera te pola:

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

Poniżej opisujemy te pola:

  • arrivalTime (opcjonalnie) określa żądany czas przybycia jako obiekt Date. Jeśli podany jest czas przyjazdu, czas wyjazdu jest ignorowany.
  • departureTime (opcjonalnie) określa żądany czas wyjazdu jako obiekt Date. Jeśli podano wartość arrivalTime, wartość departureTime zostanie zignorowana. Jeśli nie określono wartości dla właściwości departureTime ani arrivalTime, domyślnie zostanie przyjęta bieżąca data i godzina.
  • modes (opcjonalnie) to tablica zawierająca co najmniej jeden literał obiektu TransitMode. To pole może być uwzględnione tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Każdy element TransitModeokreśla preferowany środek transportu. Dozwolone wartości:
    • BUS oznacza, że obliczona trasa powinna preferować podróż autobusem.
    • RAIL oznacza, że obliczona trasa powinna preferować podróż pociągiem, tramwajem, kolejką miejską lub 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ć przejazd tramwajem i koleją miejską.
  • routingPreference (opcjonalny) określa preferencje dotyczące tras tranzytowych. Dzięki tej opcji możesz wpływać na zwracane opcje, zamiast akceptować domyślną najlepszą trasę wybraną przez interfejs API. To pole może być określone tylko wtedy, gdy żądanie zawiera klucz API. Dozwolone wartości:
    • FEWER_TRANSFERSWskazuje, że obliczona trasa powinna preferować ograniczoną liczbę przesiadek.
    • LESS_WALKINGWskazuje, że obliczona trasa powinna preferować ograniczone spacery piesze.

Opcje jazdy

Użyj obiektu drivingOptions, aby określić czas wyjazdu na potrzeby obliczenia najlepszej trasy do miejsca docelowego z uwzględnieniem spodziewanych warunków na drodze. Możesz też określić, czy przewidywany czas w korku ma być pesymistyczny, optymistyczny czy najlepszy szacowany na podstawie historycznych warunków ruchu i ruchu na żywo.

Obiekt drivingOptions zawiera te pola:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Poniżej opisujemy te pola:

  • departureTime (wymagany, aby literalny obiekt drivingOptions był prawidłowy) określa żądany czas wyjazdu jako obiekt Date. Wartość musi być ustawiona na bieżącą godzinę lub godzinę w przyszłości. Nie może ona przypadać w przeszłości. (Aby zapewnić spójne działanie w różnych strefach czasowych, interfejs API konwertuje wszystkie daty na czas UTC). Jeśli w żądaniu uwzględnisz parametr departureTime, API zwróci najlepszą trasę z uwzględnieniem przewidywanych warunków na drodze w danym czasie, a w odpowiedzi – przewidywany czas przejazdu (duration_in_traffic). Jeśli nie określisz godziny wyjazdu (czyli jeśli żądanie nie zawiera parametru drivingOptions), zwrócona trasa będzie ogólnie dobra, ale nie będzie uwzględniać warunków na drodze.
  • trafficModel (opcjonalny) określa założenia stosowane podczas obliczania czasu w ruchu. To ustawienie wpływa na wartość zwróconą w polu duration_in_traffic w odpowiedzi, która zawiera przewidywany czas w ruchu na podstawie średnich wartości historycznych. Domyślna wartość to best_guess. Dozwolone wartości:
    • bestguess (domyślnie) wskazuje, że zwrócona wartość duration_in_traffic powinna być najlepszą estymacją czasu przejazdu na podstawie znanych danych o historycznych warunkach ruchu i ruchu w czasie rzeczywistym. Im bliżej daty departureTime, tym większy wpływ na wyniki ma ruch na żywo.
    • pessimistic oznacza, że zwrócona wartość duration_in_traffic powinna być dłuższa niż rzeczywisty czas podróży w większości dni, ale w niektórych dniach, gdy warunki drogowe są szczególnie niekorzystne, może przekroczyć tę wartość.
    • optimistic oznacza, że zwrócona wartość duration_in_traffic powinna być krótsza niż rzeczywisty czas podróży w większości dni, ale w niektóre dni o szczególnie dobrych warunkach na drodze może być krótsza niż ta wartość.

Poniżej znajduje się przykładowa DistanceMatrixRequest dla tras samochodowych, zawierająca godzinę wyjazdu 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 w ramach usługi Distance Matrix

Pomyślne wywołanie usługi Distance Matrix 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 miejsc docelowych/źródeł, dla których 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 Distance Matrix

Poniżej znajdziesz opis obsługiwanych pól w odpowiedzi.

  • originAddresses to tablica zawierająca lokalizacje przekazane w polu origins żądania Distance Matrix. Adresy są zwracane w formacie określonym przez geokoder.
  • 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 jednemu źródłu.
  • elements są elementami podrzędnymi elementu rows i odpowiadają parze źródła wiersza z każdym miejscem docelowym. Zawierają one informacje o stanie, czasie trwania, odległości i cenie (jeśli są dostępne) dla każdej pary miejsc początkowych i docelowych.
  • Każdy element element zawiera te pola:
    • status: lista możliwych kodów stanu – Kody stanu.
    • duration: czas przejazdu po tej trasie wyrażony w sekundach (pole value) i w formie text. Wartość tekstowa jest formatowana zgodnie z wartością unitSystem określoną w żądaniu (lub w przypadku braku preferencji – zgodnie z danymi).
    • duration_in_traffic: czas potrzebny na pokonanie tej trasy z uwzględnieniem bieżących warunków na drodze, wyrażony w sekundach (pole value) i jako text. Wartość tekstowa jest formatowana zgodnie z wartością unitSystem określoną w żądaniu (lub w przypadku braku preferencji – zgodnie z danymi). Argument duration_in_traffic jest zwracany tylko wtedy, gdy są dostępne dane o ruchu, parametr mode ma wartość driving, a w żądaniu występuje pole distanceMatrixOptions z wartością departureTime.
    • distance: łączna odległość na tej trasie wyrażona w metrach (value) i w formie text. Wartość tekstowa jest formatowana zgodnie z wartością unitSystem określoną w żądaniu (lub w systemie metrycznym, jeśli nie podano preferencji).
    • fare: zawiera łączną cenę (czyli łączny koszt biletu) na tej trasie. Ta właściwość jest zwracana tylko w przypadku zapytań dotyczących transportu publicznego i tylko w przypadku dostawców transportu publicznego, którzy podają informacje o cenie. Informacje obejmują:
      • currency: kod waluty w formacie ISO 4217 wskazujący walutę, w której wyrażona jest kwota.
      • value: łączna kwota opłat za przejazd w walucie określonej powyżej.

Kody stanu

Odpowiedź Distance Matrix zawiera kod stanu odpowiedzi jako całości, a także stan każdego elementu.

Kody stanu odpowiedzi

Kody stanu 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 dowolnymi punktami początkowymi i docelowymi. Informacje o stanie na poziomie elementu znajdziesz w sekcji Kod stanu elementu.
  • INVALID_REQUEST – przesłane żądanie było nieprawidłowe. Zwykle jest to spowodowane brakiem wymaganych pól. Zobacz listę obsługiwanych pól powyżej.
  • MAX_ELEMENTS_EXCEEDED – produkt miejsc pochodzenia i miejsc docelowych przekracza limit na zapytanie.
  • MAX_DIMENSIONS_EXCEEDED – Twoje żądanie zawierało więcej niż 25 miejsc początkowych lub więcej niż 25 miejsc docelowych.
  • OVER_QUERY_LIMIT – Twoja aplikacja poprosiła o zbyt wiele elementów w dozwolonym czasie. Ponowne przesłanie żądania po upływie odpowiedniego czasu powinno się powieść.
  • REQUEST_DENIED – usługa odmówiła stronie internetowej korzystania z usługi Distance Matrix.
  • UNKNOWN_ERROR – nie udało się przetworzyć żądania Distance Matrix z powodu błędu serwera. Żądanie może się powieść, jeśli spróbujesz ponownie.

Kody stanu elementów

W przypadku poszczególnych obiektów DistanceMatrixElement obowiązują te kody stanu:

  • NOT_FOUND – nie udało się zgeokodować źródła lub miejsca docelowego tego pairingu.
  • 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 jeden element row dla każdego źródła przekazanego w żądaniu. Każdy wiersz zawiera pole element dla każdego połączenia źródła 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];
      }
    }
  }
}