Usługa macierzy odległości

Omówienie

Usługa macierzy odległości od Google oblicza dane dotyczące podróży odległość i czas trwania podróży między wieloma miejscami wylotu i docelowymi za pomocą danego środka transportu.

Usługa nie zwraca szczegółowych informacji o trasie. informacje o trasach, również korzystając z linii łamanych i kierunków tekstowych, można uzyskać, przekazując żądane pojedyncze miejsce wylotu i przylotu do Usługa wskazówek dojazdu.

Pierwsze kroki

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

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

1. Przejdź do Konsola Google Cloud.
2. Kliknij przycisk Wybierz projekt, a potem wybierz ten sam skonfigurowany projekt. Maps JavaScript API i kliknij Otwórz.
3. Na liście interfejsów API w panelu znajdź DISTANCE 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:
   1. U góry strony wybierz WŁĄCZ API, aby wyświetlić Biblioteka. Możesz też w menu po lewej stronie wybierz opcję Biblioteka.
   2. Wyszukaj DISTANCE Matrix API, a potem wybierz go. na liście wyników.
   3. Kliknij WŁĄCZ. Gdy proces się zakończy, DISTANCE Matrix API pojawi się na liście interfejsów Panel.

Ceny i zasady

Ceny

16 lipca 2018 r. zaczęliśmy wprowadzać nowy abonament z płatnością według wykorzystania w Mapach, trasach i miejscach. Aby dowiedzieć się więcej o nowych cenach i limitów wykorzystania przy korzystaniu z usługi macierzy odległości JavaScript, patrz sekcja Korzystanie i rozliczenia dla interfejsu DISTANCE Matrix API.

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

Zasady

Korzystanie z usługi Macierz odległości musi być zgodne z opisanych zasad dla 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łać serwer zewnętrzny. Z tego powodu muszą przekazać metodę wywołania zwrotnego, która zostanie wykonana po zakończeniu aby przetworzyć wyniki.

Dostęp do usługi Macierz odległości można uzyskać z poziomu kodu przez obiektem konstruktora google.maps.DistanceMatrixService. Metoda DistanceMatrixService.getDistanceMatrix() inicjuje żądanie do usługi macierzy odległości, przekazując ją Literał obiektu DistanceMatrixRequest zawierający źródła, miejsce docelowe i środek transportu, a także metodę wywołania zwrotnego, odebranie 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 jeden element ciągi adresów, obiekty google.maps.LatLng lub pole Place obiekty, z których oblicza się odległość i czas.
• destinations (wymagany) – tablica zawiera jeden lub więcej ciągów adresów, obiekty google.maps.LatLng lub pole Place obiekty, dla których należy obliczyć odległość i czas.
• travelMode (opcjonalny) – tryb do użycia przy obliczaniu kierunków. Zapoznaj się z sekcją na temat: trybami podróży.
• transitOptions (opcjonalnie) – opcje mają zastosowanie tylko do żądań, w których parametr travelMode to TRANSIT. Opisujemy prawidłowe wartości w sekcji dotyczącej opcji transportu publicznego.
• drivingOptions (opcjonalny) określa wartości, które mają zastosowanie tylko do żądań, w których travelMode to DRIVING. Opisujemy prawidłowe wartości w sekcji Opcje jazdy.
• unitSystem (opcjonalny) – system jednostek, należy używać 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 przylotem będą obliczamy, by w miarę możliwości unikać autostrad.
• avoidTolls (opcjonalny) – jeśli true, wskazówki dojazdu między punktami zostaną obliczone za pomocą wzoru niepłatnych.

Środki transportu

Przy obliczaniu czasu i odległości można podać którego środka transportu wybrać. Ta podróż obsługiwane tryby:

• BICYCLING prośba trasy rowerowe po ścieżkach rowerowych i preferowane ulice (obecnie ta funkcja jest dostępna tylko w niektórych miastach w Kanadzie i Stanach Zjednoczonych).
• DRIVING (domyślna) wskazuje standardowe wskazówki dojazdu za pomocą sieci drogowej.
• TRANSIT prosi o trasę przez: tras dojazdu transportem publicznym. Tę opcję można określić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Zapoznaj się z sekcją dotyczącą transportu publicznego , aby wyświetlić opcje dostępne w tego typu żądaniach.
• WALKING prośba tras pieszych po ścieżkach rowerowych i chodników (tam, gdzie są dostępne).

Opcje transportu publicznego

Usługa Transport publiczny jest obecnie „eksperymentalna”. W trakcie tego okresu będziemy wprowadzać limity liczby żądań, aby zapobiegać nadużywaniu interfejsu API. Będziemy ostatecznie nałożyć ograniczenie łącznej liczby zapytań na wczytanie mapy na podstawie dozwolonego użytku interfejs API.

Dostępne opcje żądania macierzy odległości różnią się w zależności od środka transportu. W przypadku żądań transportu publicznego avoidHighways i Opcje (avoidTolls) są ignorowane. Możesz określić opcji tras dla transportu publicznego TransitOptions literał obiektu.

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

Literał obiektu TransitOptions zawiera te elementy pola:

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

Poniżej objaśniono te pola:

• arrivalTime (opcjonalny) określa oczekiwaną wartość. czas przybycia jako obiekt Date. Jeśli godzina przyjazdu to czas odjazdu zostanie zignorowany.
• departureTime (opcjonalny) określa oczekiwaną wartość. godzina odjazdu jako obiekt Date. Wartość departureTime zostanie zignorowana, jeśli arrivalTime jest określony. Jeśli żadna wartość nie jest ustawiona, przyjmuje wartość domyślną „bieżący czas”, czyli bieżący czas określono dla departureTime albo arrivalTime
• modes (opcjonalny) to tablica zawierająca jeden lub więcej literałów obiektów TransitMode. To pole może zawierać tylko jest dołączany, jeśli żądanie zawiera klucz interfejsu API. Co TransitMode określa preferowany środek transportu. Następujące wartości są dozwolone:
  • BUS oznacza, że wybrana trasa powinna preferować podróż autobusem.
  • RAIL oznacza, że wybrana trasa powinna preferować podróż pociągiem, tramwajem, tramwajem metrem.
  • SUBWAY oznacza, że wybrana trasa powinna preferować podróż metrem.
  • TRAIN oznacza, że wybrana trasa powinna preferować podróż pociągiem.
  • TRAM oznacza, że wybraną trasą powinno być podróżowanie tramwajem i tramwajem.
• routingPreference (opcjonalny) określa preferencje dla tras transportu publicznego. Korzystając z tej opcji, można zniekształcać wyświetlane 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. Następujące wartości są dozwolone:
  • FEWER_TRANSFERS wskazuje, że wyliczona trasa powinna preferować ograniczoną liczbę transfery danych.
  • LESS_WALKING wskazuje, że wyliczona trasa powinna preferować ograniczone ilości spacer.

Opcje jazdy

Użyj obiektu drivingOptions, aby określić godzinę odjazdu: wytyczanie najlepszej trasy do celu przy oczekiwanych warunkach na drodze. Dostępne opcje określić, czy szacowany czas w ruchu ma być pesymistyczny, optymistyczny najlepsze oszacowanie 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 w przypadku drivingOptions literał obiektu jako prawidłowy) określa żądany czas odjazdu jako obiekt Date. Wartość musi być jest ustawiona na aktualną godzinę lub czas w przyszłości. Nie może znajdować się w sekcji w przeszłości. (API konwertuje wszystkie daty na UTC, aby zapewnić spójną obsługę w różnych strefach czasowych). Jeśli w prośbie umieścisz departureTime, interfejs API zwraca najlepszą trasę przy oczekiwanych w danym momencie warunkach na drodze; obejmuje przewidywany czas ruchu (duration_in_traffic) w odpowiedzi. Jeśli nie określisz godziny odjazdu (tzn. jeśli żądanie nie obejmuje: drivingOptions), zwrócona trasa to zwykle dobra trasa, nie biorąc pod uwagę warunków drogowych.
• trafficModel (opcjonalny) określa założenia do używać do obliczania czasu w ruchu. To ustawienie wpływa na wartość zwracanych w polu duration_in_traffic w odpowiedzi, który zawiera przewidywany czas ruchu na podstawie średnich wartości historycznych. Domyślna wartość to best_guess. Następujące wartości są dozwolone:
  • bestguess (domyślnie) wskazuje, że zwrócona wartość duration_in_traffic to najbardziej optymalna przybliżona długość podróży z uwzględnieniem informacji o historycznych warunkach na drodze aktualny ruch w sieci. Aktualne natężenie ruchu staje się ważniejsze im bliżej departureTime do teraz.
  • pessimistic oznacza, że zwrócony Długość linii duration_in_traffic powinna być dłuższa niż faktyczna długość podróży przez większość dni, czasami jednak ruch jest wyjątkowo duży warunki mogą przekroczyć tę wartość.
  • optimistic oznacza, że zwrócony Wartość duration_in_traffic powinna być krótsza od rzeczywistej wartości czas podróży w większość dni, ale czasami są to dni szczególnie dobre warunki na drodze mogą być szybsze niż ta wartość.

Poniżej znajduje się przykładowy DistanceMatrixRequest dla tras samochodowych, w tym informacje o godzinie 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 błąd DistanceMatrixResponse obiekt i DistanceMatrixStatus obiekt. Są one przekazywane do wywołania zwrotnego funkcji określonej w żądaniu.

Obiekt DistanceMatrixResponse zawiera informacje o odległości i informacje o czasie trwania dla każdej pary miejsca wylotu/przylotu, dla której trasa jak można wyliczyć.

{
  "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 przekazywane w polu origins w żądaniu macierzy odległości. Adresy są zwracane w miarę ich formatowania przez geokoder.
• destinationAddresses to tablica zawierająca lokalizacje przekazywane w polu destinations, w formacie zwrócony przez geokoder.
• rows to tablica DistanceMatrixResponseRow obiektów, przy czym każdy wiersz odpowiada punktowi początkowemu.
• elements to elementy podrzędne względem rows i odpowiadają przez połączenie punktu początkowego wiersza z poszczególnymi miejscami docelowymi. Zawierają one stan, czas trwania, odległość i informacje o cenie (jeśli są dostępne) każdego miejsce docelowe/miejsce docelowe.
• Każdy identyfikator element zawiera te pola:
  • status: zobacz Kody stanu dotyczące listy możliwe kody stanu.
  • duration: czas potrzebny na dotarcie do tego miejsca; trasa wyrażona w sekundach (pole value) oraz jako text Wartość tekstowa jest sformatowana zgodnie z Parametr unitSystem został określony w żądaniu (lub w danych, jeśli nie ma parametru) określono ustawienie).
  • duration_in_traffic: czas potrzebny do wybrać tę trasę, biorąc pod uwagę aktualne warunki drogowe, wyrażony w sekundach (pole value) i jako text Wartość tekstowa jest sformatowana zgodnie z Parametr unitSystem został określony w żądaniu (lub w danych, jeśli nie ma parametru) określono ustawienie). Wartość duration_in_traffic jest zwracana tylko wtedy, gdy dostępne są dane o ruchu, mode ma wartość driving oraz departureTime jest częścią distanceMatrixOptions w żądaniu.
  • distance: całkowita odległość na tej trasie, wyrażona w m (value) i jako text. Wartość tekstowa. jest sformatowany zgodnie z zasadą unitSystem określoną w żądania (lub w danych, jeśli nie określono preferencji).
  • fare: zawiera łączną cenę (czyli łączną cenę). kosztów biletu) na tej trasie. Ta usługa jest zwracana tylko w przypadku transportu publicznego i tylko w przypadku przewoźników, których informacje o cenie są i dostępności informacji. Do informacji tych należą:
    • currency: Waluta w formacie ISO 4217 kod wskazujący walutę, w której wyrażona jest kwota.
    • value: łączna kwota opłaty w określonej walucie. powyżej.

Kody stanu

Odpowiedź macierzy odległości zawiera kod stanu odpowiedzi w postaci wszystkich elementów, a także stan każdego elementu.

Kody stanu odpowiedzi

DistanceMatrixResponse ma następujące kody stanu: przekazywane w obiekcie DistanceMatrixStatus i zawierają:

• OK – żądanie jest prawidłowe. Może on mieć zwracany nawet wtedy, gdy nie znaleziono żadnej trasy między dowolnym punktem początkowym miejsca docelowe. Zobacz Element Kody stanu zawierające informacje o stanie na poziomie elementu.
• INVALID_REQUEST – przesłane żądanie to jest nieprawidłowa. Przyczyną tej sytuacji jest często brak wymaganych pól. Zobacz listę obsługiwanych pól znajdziesz powyżej.
• MAX_ELEMENTS_EXCEEDED – produkt miejsca wylotu i miejsca przeznaczenia przekracza limitu zapytań.
• MAX_DIMENSIONS_EXCEEDED – Twoje żądanie zawierało więcej ponad 25 źródeł lub więcej niż 25 miejsc docelowych.
• OVER_QUERY_LIMIT – Twoja aplikacja zażądała zbyt wiele elementów w dozwolonym czasie. Prośba powinna możesz spróbować ponownie po upływie odpowiedniego czasu.
• REQUEST_DENIED – usługa odmówiła użycia Usługa Macierz odległości na stronie internetowej.
• UNKNOWN_ERROR – nie udało się wysłać żądania macierzy odległości zostaną przetworzone z powodu błędu serwera. Żądanie może zostać zrealizowane, jeśli spróbujesz ponownie.

Kody stanu elementu

Poniższe kody stanu mają zastosowanie do określonych DistanceMatrixElement obiekty:

• NOT_FOUND – miejsce wylotu lub przylotu nie można zakodować danych geograficznych.
• OK – odpowiedź zawiera prawidłowy wynik.
• ZERO_RESULTS – nie znaleziono trasy między wylot i cel podróży.

Analiza wyników

Obiekt DistanceMatrixResponse zawiera jeden row dla każdego punktu początkowego, który został przekazany w żądaniu. Każdy wiersz zawiera pole element dla każdej pary tego punktu początkowego z podane miejsca docelowe.

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];
      }
    }
  }
}