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:
- Otwórz konsolę Google Cloud.
- Kliknij przycisk Wybierz projekt, a następnie wybierz projekt skonfigurowany na potrzeby interfejsu Maps JavaScript API i kliknij Otwórz.
- Na liście interfejsów API w panelu znajdź Distance Matrix API.
- Jeśli widzisz interfejs API na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
- Aby wyświetlić kartę Biblioteka, u góry strony wybierz WŁĄCZ API. Możesz też wybrać Biblioteka w menu po lewej stronie.
- Wyszukaj Distance Matrix API, a następnie wybierz go z listy wyników.
- 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. }
DistanceMatrixRequest
zawiera te pola:
origins
(wymagany) – tablica zawierająca co najmniej 1 ciąg adresu, obiektygoogle.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, obiektygoogle.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órychtravelMode
toTRANSIT
. 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órychtravelMode
toDRIVING
. 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ślitrue
, 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 totrue
, 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 obiektDate
. Jeśli podasz godzinę przyjazdu, godzina odjazdu zostanie zignorowana.departureTime
(opcjonalny) określa żądaną godzinę odjazdu jako obiektDate
. Jeśli określonoarrivalTime
,departureTime
zostanie zignorowana. Jeśli w poludepartureTime
aniarrivalTime
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ówTransitMode
. To pole można uwzględnić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Każdy elementTransitMode
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 obiektudrivingOptions
) określa wymagany czas odjazdu jako obiektDate
. 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ściszdepartureTime
, 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 onodrivingOptions
), 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 poluduration_in_traffic
w odpowiedzi, które zawiera przewidywany czas w ruchu określony na podstawie średnich historycznych. Domyślna wartość tobest_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żejdepartureTime
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 poluorigins
w żądaniu macierzy odległości. Adresy są zwracane, ponieważ są sformatowane przez geokodera.destinationAddresses
to tablica zawierająca lokalizacje przekazane w poludestinations
w formacie zwróconym przez geokodera.rows
to tablica obiektówDistanceMatrixResponseRow
, z których każdy wiersz odpowiada pochodzeniu.elements
są elementami podrzędnymi elementurows
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 (polevalue
) i w postacitext
. 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 (polevalue
) i w postacitext
. 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
, adepartureTime
jest zawarty w poludistanceMatrixOptions
w żądaniu.distance
: całkowita odległość tej trasy wyrażona w metrach (value
) i w postacitext
. 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]; } } } }