Usługa macierzy odległości

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Opis

Usługa macierzy odległości oblicza dystans i czas podróży z wielu punktów początkowych i miejsc docelowych w ramach określonego środka transportu.

Ta usługa nie zwraca szczegółowych informacji o trasie. Informacje o trasie, w tym linie łamane i wskazówki dojazdu, możesz uzyskać, przesyłając do usługi wyznaczania tras odpowiednie pojedyncze miejsce docelowe i miejsce docelowe.

Pierwsze kroki

Zanim zaczniesz korzystać z usługi DISTANCE Matrix w interfejsie Maps JavaScript API, najpierw sprawdź, czy interfejs DISTANCE Matrix API jest włączony w Google Cloud Console w tym samym projekcie skonfigurowanym dla interfejsu Maps JavaScript API.

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

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

Ceny i zasady

Ceny

16 lipca 2018 r. wprowadziliśmy nowy abonament, który pozwoli Ci korzystać z Map Google, tras i miejsc. Więcej informacji o nowych limitach cenowych i użytkowania dotyczących korzystania z usługi macierzy odległości w języku JavaScript znajdziesz w artykule Korzystanie z rozliczeń i interfejs API interfejsu DISTANCE Matrix API.

Uwaga: każde zapytanie wysłane do usługi Odległość ma wartość ograniczoną przez liczbę dozwolonych elementów, w których liczba źródeł pomnożona przez liczbę miejsc docelowych określa liczbę elementów.

Ograniczenia liczby żądań

Weź pod uwagę te ograniczenia dotyczące dodatkowych żądań:

Limit szybkości jest stosowany do każdej sesji użytkownika, niezależnie od tego, ilu użytkowników korzysta z tego samego projektu. Przy pierwszym wczytaniu interfejsu API przydzielany jest początkowy limit elementów. Gdy wykorzystasz ten limit, interfejs API wymusza ograniczenia liczby żądań w ciągu dodatkowych sekund. Jeśli w określonym czasie pojawi się zbyt wiele żądań, interfejs API zwróci kod odpowiedzi OVER_QUERY_LIMIT.

Limit liczby żądań na sesję uniemożliwia korzystanie z usług po stronie klienta w przypadku żądań zbiorczych. W przypadku żądań zbiorczych użyj usługi internetowej interfejsu DISTANCE Matrix API.

Zasady

Korzystanie z usługi typów macierzy odległości musi być zgodne z zasadami opisanymi w interfejsie API odległości.

Żądania macierzy odległości

Dostęp do usługi typów odległości jest asynchroniczny, ponieważ interfejs API Map Google musi wywoływać serwer zewnętrzny. Z tego powodu musisz przekazać metodę wywołania zwrotnego, aby wykonać żądanie, aby przetworzyć wyniki.

Dostęp do usługi macierzy odległości możesz uzyskać w kodzie za pomocą obiektu konstruktora google.maps.DistanceMatrixService. Metoda DistanceMatrixService.getDistanceMatrix() inicjuje żądanie matrycy dystansu, przekazując obiekt literału DistanceMatrixRequest zawierający źródła, 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 (wymagane) – tablica zawierająca co najmniej 1 ciąg adresów, obiekty google.maps.LatLng lub obiekty Place, z których oblicza się 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 chcesz obliczyć odległość i czas.
  • travelMode (opcjonalny) – środek transportu używany przy obliczaniu trasy. Zobacz sekcję dotyczącą trybów podróży.
  • transitOptions (opcjonalny) – opcje stosowane tylko do żądań, w przypadku których travelMode to TRANSIT. Prawidłowe wartości znajdziesz w sekcji dotyczącej opcji transportu.
  • drivingOptions (opcjonalny) określa wartości dotyczące tylko żądań, w przypadku których travelMode to DRIVING. Prawidłowe wartości znajdziesz w sekcji Opcje jazdy.
  • unitSystem (opcjonalny) – system jednostek, który ma wyświetlać odległość. Akceptowane wartości to:
    • google.maps.UnitSystem.METRIC (domyślnie)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (opcjonalny) – jeśli true będzie wyznaczony, trasy będą naliczane w miarę możliwości, dzięki czemu unikniesz autostrad.
  • avoidTolls (opcjonalny) – jeśli true, w miarę możliwości połączenia między punktami będą obliczane na podstawie tras bezpłatnych.

Środki transportu

Przy obliczaniu czasu i dystansu możesz też wybrać środek transportu. Obecnie obsługiwane są te środki transportu:

  • BICYCLING prosi o trasę rowerową przez ścieżki rowerowe i preferowane ulice (obecnie tylko w Stanach Zjednoczonych i niektórych miastach Kanady).
  • DRIVING (opcja domyślna) oznacza standardowe wskazówki dojazdu korzystające z sieci drogowej.
  • TRANSIT prosi o wskazówki dojazdu transportem publicznym. Tę opcję można określić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Informacje o dostępnych opcjach tego typu znajdziesz w sekcji o opcjach transportu publicznego.
  • WALKING prosi o wyznaczenie trasy pieszej za pomocą ścieżek dla pieszych i chodników (jeśli są dostępne).

Opcje transportu publicznego

Usługa transportu publicznego to obecnie „#eksperyment[&93”. Na tym etapie wprowadzimy ograniczenia liczby żądań, aby zapobiec nadużyciom interfejsu API. Ostatecznie wprowadzimy limit na łączną liczbę zapytań na mapę, zgodnie z dozwolonym użyciem interfejsu API.

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

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

Litera obiektu TransitOptions zawiera te pola:

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

Wyjaśniamy te pola:

  • arrivalTime (opcjonalny) określa wymagany czas dotarcia jako obiekt Date. Jeśli określisz godzinę przyjazdu, godzina wyjazdu zostanie zignorowana.
  • departureTime (opcjonalny) określa żądany czas wyjazdu jako obiekt Date. Jeśli zostanie określona właściwość arrivalTime, właściwość departureTime będzie ignorowana. Jeśli w polu departureTime lub arrivalTime nie podasz żadnej wartości, zostanie użyta domyślna wartość, czyli bieżąca data.
  • modes (opcjonalny) to tablica zawierająca co najmniej 1 literalnię obiektu TransitMode. To pole można uwzględnić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Każdy obiekt 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 obejmować podróże pociągiem, tramwajem, tramwajem lub metrem.
    • SUBWAY wskazuje, że obliczona trasa powinna podróżować metrem.
    • TRAIN wskazuje, że obliczona trasa powinna podróżować pociągiem.
    • TRAM wskazuje, że obliczona trasa powinna korzystać z tramwaju i tramwaju.
  • routingPreference (opcjonalny) określa ustawienia tras transportu publicznego. Ta opcja może wpływać na wyświetlane opcje, zamiast akceptować domyślną 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 mieć ograniczoną liczbę transferów.
    • LESS_WALKING wskazuje, że obliczona trasa powinna mieć ograniczoną liczbę spacerów.

Opcje jazdy

Za pomocą obiektu drivingOptions możesz określić czas odjazdu, aby obliczyć najlepszą trasę do miejsca docelowego przy przewidywanych warunkach na drodze. Możesz też określić, czy szacowany czas ruchu jest pesymistyczny, optymistyczny, czy najlepszy szacowany na podstawie historycznych warunków ruchu i ruchu na żywo.

Obiekt drivingOptions zawiera te pola:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Wyjaśniamy te pola:

  • departureTime (wymagany w przypadku literału obiektu drivingOptions) wymagany czas wyjazdu jako obiekt Date. Wartość musi być ustawiona na bieżącą lub godzinę w przyszłości. Nie może być datą z przeszłości. (Aby zapewnić spójność obsługi stref czasowych, interfejs API konwertuje wszystkie daty na UTC). Jeśli w żądaniu umieścisz parametr departureTime, interfejs API zwróci najlepszą trasę zgodnie z oczekiwanymi warunkami ruchu i będzie uwzględniać w odpowiedzi przewidywany czas (duration_in_traffic). Jeśli nie określisz godziny odjazdu (tzn. jeśli żądanie nie obejmuje drivingOptions), zwracana trasa jest zasadniczo właściwą trasą bez uwzględniania warunków na drodze.

    Uwaga: jeśli czas wylotu nie jest określony, wybór trasy i czasu trwania zależy od sieci drogowej i średniego natężenia ruchu niezależnego od czasu. Wyniki danego żądania mogą się zmieniać z upływem czasu ze względu na zmiany w sieci drogowej, zaktualizowane warunki średniego ruchu i rozproszony charakter usługi. Wyniki mogą się też różnić w przypadku prawie odpowiednich tras w dowolnym momencie i z różną częstotliwością.

  • trafficModel (opcjonalny) określa założenia, które mają być używane podczas obliczania czasu w ruchu. To ustawienie wpływa na wartość zwracaną w polu duration_in_traffic w odpowiedzi, która zawiera przewidywany czas na podstawie średnich wartości historycznych. Domyślna wartość to best_guess. Dozwolone są te wartości:
    • bestguess (wartość domyślna) wskazuje, że zwrócony znacznik duration_in_traffic powinien być najlepszym szacowanym czasem podróży przy uwzględnieniu zarówno historycznych danych o ruchu, jak i aktualnego ruchu. Ruch na żywo staje się ważniejszy, gdy departureTime jest bliżej.
    • pessimistic wskazuje, że zwrócony obiekt duration_in_traffic powinien być dłuższy niż rzeczywisty czas podróży w większości dni, ale czasami dni o szczególnie złym natężeniu ruchu mogą przekraczać tę wartość.
    • optimistic wskazuje, że zwrócony czas duration_in_traffic powinien być krótszy niż rzeczywisty czas podróży w większości dni, chociaż w przypadku dni, w których natężenie ruchu jest wyjątkowo dobre, może być szybsze niż ta wartość.

Poniżej znajdziesz przykładowy atrybut DistanceMatrixRequest dla tras dojazdu, w tym czas odjazdu i model 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 tablicy 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 każdej pary punktu początkowego i docelowego, 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 tablicy odległości

Obsługiwane pola w odpowiedzi zostały opisane poniżej.

  • originAddresses to tablica zawierająca lokalizacje przekazane w polu origins żądania w macierze dystansu. Adresy są zwracane w formacie zgodnym z geokoderem.
  • destinationAddresses to tablica zawierająca lokalizacje przekazane w polu destinations w formacie zwracanym przez koder.
  • rows to tablica obiektów DistanceMatrixResponseRow. Każdy wiersz odpowiada źródło.
  • Elementy elements są elementami podrzędnymi elementu rows i odpowiadają powiązaniu wiersza z poszczególnymi miejscami docelowymi. Zawierają informacje o stanie, czasie trwania, odległości i cenie (jeśli są dostępne) dla każdej pary punktu początkowego i miejsca docelowego.
  • Każdy element element zawiera te pola:
    • status: Sprawdź kody stanu, aby poznać listę możliwych kodów stanu.
    • duration: czas trwania tej trasy wyrażony w sekundach (pole value) oraz podany jako text. Wartość tekstowa jest formatowana zgodnie z wartością unitSystem określoną w żądaniu (lub w danych, jeśli nie podano preferencji).
    • duration_in_traffic: czas potrzebny na pokonanie tej trasy z uwzględnieniem bieżących warunków ruchu (wyrażony w sekundach (pole value) oraz w postaci text. Wartość tekstowa jest formatowana zgodnie z wartością unitSystem określoną w żądaniu (lub w danych, jeśli nie podano preferencji). Element duration_in_traffic jest zwracany tylko do klientów korzystających z abonamentu Premium w Google Maps Platform, w których dostępne są dane o ruchu. Parametr mode ma wartość driving, a pole departureTime jest zawarte w polu distanceMatrixOptions w żądaniu.
    • distance: łączny dystans na tej trasie wyrażony w metrach (value) i jako text. Wartość tekstowa jest formatowana zgodnie z wartością unitSystem określoną w żądaniu (lub w danych, jeśli nie podano preferencji).
    • fare: podaje łączną cenę (czyli łączne koszty biletów) na tej trasie. Ta właściwość jest zwracana tylko w przypadku żądań transportu publicznego i tylko dla przewoźników, dla których dostępne są informacje o opłatach. Obejmują one:
      • currency: kod waluty 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ść oraz stan każdego elementu.

Kody stanu odpowiedzi

W obiekcie DistanceMatrixStatus przekazywane są kody stanu dotyczące DistanceMatrixResponse, które zawierają:

  • OK – żądanie jest prawidłowe; Ten stan może zostać zwrócony nawet wtedy, gdy nie znaleziono tras między żadnym źródłem a miejscem docelowym. Informacje o stanie na poziomie elementu znajdziesz w sekcji Kody stanu elementu.
  • INVALID_REQUEST – podane żą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 punktów początkowych i miejsc docelowych przekracza limit na zapytanie.
  • MAX_DIMENSIONS_EXCEEDED – żądanie zawierało ponad 25 źródeł lub więcej niż 25 miejsc docelowych.
  • OVER_QUERY_LIMIT – Twoja aplikacja żąda zbyt wielu elementów w dozwolonym okresie. Żądanie powinno się zakończyć pomyślnie, jeśli po upływie określonego czasu spróbujesz jeszcze raz.
  • REQUEST_DENIED – usługa odmówiła dostępu do usługi Matryca odległości przez Twoją stronę.
  • UNKNOWN_ERROR – nie udało się przetworzyć żądania tablicy odległości z powodu błędu serwera. Żądanie może się udać, jeśli spróbujesz ponownie.

Kody stanu elementu

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

  • NOT_FOUND – nie udało się zakodować źródła miejsca docelowego lub miejsca docelowego tej pary.
  • OK – odpowiedź zawiera prawidłowy wynik.
  • ZERO_RESULTS – nie znaleziono trasy między miejscem wylotu a miejscem docelowym.

Analiza wyników

Obiekt DistanceMatrixResponse zawiera 1 element row na każde źródło, które zostało przekazane w żądaniu. Każdy wiersz zawiera pole element dla każdego parowania tego ź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];
      }
    }
  }
}