Distance Matrix Service (starsza wersja)

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)
Uwaga: biblioteki po stronie serwera

Przegląd

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

Ta 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 do usługi wskazówek dojazdu żądane pojedyncze miejsce początkowe i docelowe.

Pierwsze kroki

Zanim zaczniesz korzystać z usługi macierzy odległości w interfejsie Maps JavaScript API, upewnij się, że interfejs Distance Matrix API (starsza wersja) jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany na potrzeby 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 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ź Distance Matrix API (starsza wersja).
  4. Jeśli interfejs API jest 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

Informacje o cenach i zasadach użytkowania usługi macierzy odległości w języku JavaScript znajdziesz w artykule o korzystaniu z interfejsu Distance Matrix API (starsza wersja) i powiązanych rozliczeniach.

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

Zasady

Korzystanie z usługi macierzy odległości musi być zgodne z zasadami opisanymi w przypadku interfejsu Distance Matrix API (starsza wersja).

Żądania macierzy odległości

Dostęp do usługi macierzy odległości jest asynchroniczny, ponieważ interfejs API Map Google musi wykonać wywołanie do serwera zewnętrznego. Z tego powodu musisz przekazać metodę wywołania zwrotnego, która zostanie wykonana po zakończeniu żądania, aby przetworzyć wyniki.

Dostęp do usługi macierzy odległości uzyskujesz w kodzie za pomocą obiektu konstruktora google.maps.DistanceMatrixService. Metoda DistanceMatrixService.getDistanceMatrix() inicjuje żądanie do usługi macierz 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 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 adresowy, obiekt google.maps.LatLng lub obiekt Place, na podstawie którego ma zostać obliczona odległość i czas.
  • destinations (wymagany) – tablica zawierająca co najmniej 1 ciąg adresowy, obiekt google.maps.LatLng lub obiekt Place, dla którego ma zostać obliczona 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 to TRANSIT. Prawidłowe wartości są 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 są opisane w sekcji Opcje jazdy.
  • unitSystem (opcjonalny) – system jednostek, który ma być używany podczas wyświetlania odległości. Akceptowane wartości:
    • google.maps.UnitSystem.METRIC (domyślnie)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (opcjonalny) – jeśli ma wartość true, trasy między miejscami rozpoczęcia podróży a miejscami docelowymi będą obliczane tak, aby w miarę możliwości unikać autostrad.
  • avoidTolls (opcjonalny) – jeśli ma wartość true, wskazówki dojazdu między punktami będą obliczane z użyciem tras bezpłatnych, o ile to możliwe.

Środki transportu

Podczas obliczania czasu i odległości możesz określić, którego środka transportu chcesz użyć. Obecnie obsługiwane są te środki transportu:

  • BICYCLING – żądanie wskazówek dojazdu rowerem ścieżkami rowerowymi i preferowanymi ulicami (obecnie dostępne tylko w Stanach Zjednoczonych i niektórych miastach Kanady).
  • DRIVING (domyślna) wskazuje standardowe wskazówki dojazdu z wykorzystaniem sieci dróg.
  • TRANSIT prosi o wskazówki dojazdu trasami transportu publicznego. Tę opcję można określić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Informacje o dostępnych opcjach tego typu żądania znajdziesz w sekcji poświęconej opcjom transportu publicznego.
  • WALKING prośba o trasę pieszą ścieżkami dla pieszych i chodnikami (jeśli są dostępne).

Opcje transportu publicznego

Usługa transportu publicznego jest obecnie w wersji eksperymentalnej. W tym okresie będziemy wdrażać limity liczby żądań, aby zapobiegać nadużyciom interfejsu API. W przyszłości wprowadzimy limit łącznej liczby zapytań na wczytanie mapy, który będzie oparty na zasadach uczciwego korzystania z interfejsu API.

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

Prośby o przejazd są ograniczone czasowo. 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
}

Pola te zostały opisane poniżej:

  • arrivalTime (opcjonalny) określa pożądany czas przybycia jako obiekt Date. Jeśli podano czas przyjazdu, czas odjazdu jest ignorowany.
  • departureTime (opcjonalny) określa żądany czas odjazdu jako obiekt Date. Jeśli podasz arrivalTime, departureTime zostanie zignorowany. Jeśli nie podano wartości dla departureTime ani arrivalTime, domyślnie przyjmuje się bieżący czas.
  • 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 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óż pociągiem, tramwajem, koleją miejską 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ć podróż tramwajem i koleją miejską.
  • routingPreference (opcjonalny) określa preferencje dotyczące tras transportu publicznego. Za pomocą tej opcji możesz wpływać na 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 wskazuje, że obliczona trasa powinna preferować ograniczone ilości chodzenia.

Opcje jazdy

Użyj obiektu drivingOptions, aby określić czas wyjazdu i obliczyć najlepszą trasę do miejsca docelowego z uwzględnieniem oczekiwanych warunków na drodze. Możesz też określić, czy szacowany czas w ruchu ma być pesymistyczny, optymistyczny czy najbardziej prawdopodobny na podstawie historycznych i bieżących warunków na drodze.

Obiekt drivingOptions zawiera te pola:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Pola te zostały opisane poniżej:

  • departureTime (wymagany, aby literał obiektu drivingOptions był prawidłowy) określa żądany czas odjazdu jako obiekt Date. Wartość musi być ustawiona na bieżący czas lub czas w przyszłości. Nie może przypadać w przeszłości. (Interfejs API konwertuje wszystkie daty na czas UTC, aby zapewnić spójne działanie w różnych strefach czasowych). Jeśli w żądaniu uwzględnisz parametr departureTime, interfejs API zwróci najlepszą trasę z uwzględnieniem oczekiwanych warunków na drodze w danym momencie i uwzględni w odpowiedzi przewidywany czas w ruchu ulicznym (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, które mają być używane podczas obliczania czasu w ruchu drogowym. To ustawienie wpływa na wartość zwracaną w polu duration_in_traffic w odpowiedzi, które zawiera przewidywany czas w ruchu ulicznym na podstawie średnich historycznych. Domyślna wartość to best_guess. Dozwolone są te wartości:
    • bestguess (domyślny) wskazuje, że zwracany obiekt duration_in_traffic powinien być najlepszym oszacowaniem czasu podróży na podstawie informacji o historycznych i bieżących warunkach na drodze. Ruch na żywo staje się tym ważniejszy, im bliżej obecnego momentu jest departureTime.
    • pessimistic wskazuje, że zwracany 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 przekroczyć tę wartość.
    • optimistic wskazuje, że zwracany 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, czas podróży może być krótszy niż ta wartość.

Poniżej znajdziesz przykładowe zapytanie DistanceMatrixRequest dotyczące tras dojazdu, w tym czasu wyjazdu i modelu 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

Prawidłowe 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 punktów początkowych i docelowych, 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 macierzy odległości

Poniżej znajdziesz objaśnienia obsługiwanych pól w odpowiedzi.

  • originAddresses to tablica zawierająca lokalizacje przekazane w polu origins żądania macierzy odległości. Adresy są zwracane w formacie geokodera.
  • destinationAddresses to tablica zawierająca lokalizacje przekazane w polu destinations w formacie zwracanym przez geokoder.
  • rows to tablica obiektów DistanceMatrixResponseRow, w której każdy wiersz odpowiada miejscu rozpoczęcia podróży.
  • elements są elementami podrzędnymi elementu rows i odpowiadają parom miejsca początkowego i docelowego w wierszu. Zawierają one stan, czas trwania, odległość i informacje o opłatach (jeśli są dostępne) dla każdej pary miejsc początkowych i docelowych.
  • Każdy obiekt 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 parametrem unitSystem określonym w żądaniu (lub w danych, jeśli nie podano preferencji).
    • duration_in_traffic: czas potrzebny na pokonanie tej trasy z uwzględnieniem aktualnych warunków na drodze, wyrażony w sekundach (pole value) i jako text. Wartość tekstowa jest sformatowana zgodnie z parametrem unitSystem określonym w żądaniu (lub w danych, jeśli nie podano preferencji). Wartość duration_in_traffic jest zwracana tylko wtedy, gdy dostępne są dane o natężeniu ruchu, parametr mode jest ustawiony na driving, a parametr departureTime jest uwzględniony 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 parametrem unitSystem określonym w żądaniu (lub w danych, jeśli nie podano preferencji).
    • fare: zawiera łączną opłatę za przejazd (czyli łączny koszt biletów) na tej trasie. Ta właściwość jest zwracana tylko w przypadku żądań dotyczących transportu publicznego i tylko w przypadku dostawców transportu publicznego, u 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 opłaty za przejazd w walucie określonej powyżej.

Kody stanu

Odpowiedź macierzy odległości 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 zostać zwrócony, nawet jeśli nie znaleziono żadnych tras między żadnym z miejsc początkowych i docelowych. Informacje o stanie na poziomie elementu znajdziesz w artykule 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 – iloczyn liczby miejsc początkowych i docelowych przekracza limit na zapytanie.
  • MAX_DIMENSIONS_EXCEEDED – żądanie zawierało więcej niż 25 miejsc początkowych lub więcej niż 25 miejsc docelowych.
  • OVER_QUERY_LIMIT – aplikacja wysłała zbyt wiele żądań w dozwolonym okresie. Jeśli spróbujesz ponownie po upływie odpowiedniego czasu, żądanie powinno zostać zrealizowane.
  • REQUEST_DENIED – usługa odmówiła Twojej stronie internetowej dostępu do usługi macierzy odległości.
  • UNKNOWN_ERROR – nie udało się przetworzyć żądania macierzy odległości z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.

Kody stanu elementu

Te kody stanu dotyczą konkretnych obiektów DistanceMatrixElement:

  • NOT_FOUND – nie udało się wygenerować kodu geograficznego dla miejsca początkowego lub docelowego tej pary.
  • OK – odpowiedź zawiera prawidłowy wynik.
  • ZERO_RESULTS – nie udało się znaleźć trasy między miejscem wyjazdu a miejscem docelowym.

Analizowanie wyników

Obiekt DistanceMatrixResponse zawiera po jednym obiekcie row dla każdego źródła przekazanego w żądaniu. Każdy wiersz zawiera pole element dla każdej pary tego miejsca 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];
      }
    }
  }
}