Przegląd
Usługa macierzy odległości od Google oblicza odległość i czas podróży między różnymi punktami początkowymi i miejscami docelowymi, korzystając z danego środka transportu.
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 wybrane pojedyncze miejsce początkowe i miejsce docelowe do usługi wyznaczania wskazówek dojazdu.
Pierwsze kroki
Zanim użyjesz usługi Macierz odległości w Maps JavaScript API, upewnij się, że interfejs DISTANCE Matrix API jest włączony w konsoli Google Cloud w tym samym projekcie, który konfigurujesz 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 ten sam projekt, który został skonfigurowany dla interfejsu Maps JavaScript API, i kliknij Otwórz.
- Na liście interfejsów API w panelu znajdź Reach Matrix API.
- Jeśli interfejs API jest widoczny na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
- U góry strony wybierz WŁĄCZ API, aby wyświetlić kartę Biblioteka. Możesz też w menu po lewej stronie wybrać Biblioteka.
- Wyszukaj DISTANCE Matrix API, a potem wybierz go z listy wyników.
- Kliknij WŁĄCZ. Gdy proces się zakończy, na liście interfejsów API w panelu pojawi się Reach Matrix API.
Ceny i zasady
Ceny
16 lipca 2018 r. wszedł w życie nowy abonament z płatnościami według wykorzystania w Mapach, trasach i miejscach. Aby dowiedzieć się więcej o nowych cenach i limitach wykorzystania w związku z korzystaniem z usługi macierzy odległości w języku JavaScript, przeczytaj artykuł na temat użytkowania i płatności za pomocą 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 elementów origins pomnożona przez liczbę miejsc docelowych określa liczbę elementów.
Zasady
Korzystanie z usługi Macierz odległości musi być zgodne z zasadami dotyczącymi jej interfejsu.
Żądania macierzy odległości
Dostęp do usługi Macierz odległości jest asynchroniczny, ponieważ interfejs Google Maps API musi wywołać serwer zewnętrzny. Z tego powodu w celu przetworzenia wyników musisz przekazać metodę wywołania zwrotnego, która zostanie wykonana po zakończeniu żądania.
Dostęp do usługi macierzy odległości w kodzie uzyskujesz za pomocą obiektu konstruktora google.maps.DistanceMatrixService
.
Metoda DistanceMatrixService.getDistanceMatrix()
inicjuje żądanie do usługi macierzy odległości, przekazując mu 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. }
DistanceMatrixRequest
zawiera te pola:
origins
(wymagany) – tablica zawierająca co najmniej 1 ciąg adresu, obiektygoogle.maps.LatLng
lub obiekty Place, z których ma zostać obliczona odległość i czas.destinations
(wymagany) – tablica zawierająca co najmniej 1 ciąg adresu, obiektygoogle.maps.LatLng
lub obiekty Place, do których mają zostać obliczone czas i odległość.travelMode
(opcjonalny) – środek transportu używany przy obliczaniu wskazówek dojazdu. Zapoznaj się z sekcją dotyczącą środków transportu.transitOptions
(opcjonalny) – opcje dotyczące tylko żądań, w którychtravelMode
toTRANSIT
. Prawidłowe wartości zostały opisane w sekcji dotyczącej opcji transportu.drivingOptions
(opcjonalny) określa wartości, które mają zastosowanie tylko do żądań, w którychtravelMode
toDRIVING
. Prawidłowe wartości znajdziesz 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śli jesttrue
, trasy między miejscem wylotu a celem podróży będą obliczane w taki sposób, by w miarę możliwości ominąć autostrady.avoidTolls
(opcjonalny) – jeśli jesttrue
, wskazówki dojazdu między punktami będą obliczane z wykorzystaniem tras innych niż płatne, gdy tylko będzie to możliwe.
Środki transportu
Podczas obliczania czasu i odległości możesz wybrać środek transportu. Obecnie obsługiwane są te środki transportu:
BICYCLING
prosi o wskazówki dojazdu rowerem i preferowane ulice (obecnie dostępne tylko w niektórych miastach w USA i niektórych Kanadzie).DRIVING
(domyślnie) wskazuje standardowe wskazówki dojazdu przez sieć drogową.TRANSIT
prosi o wskazówki dojazdu transportem publicznym. Tę opcję można określić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Listę opcji dostępnych w przypadku tego typu żądań znajdziesz w sekcji dotyczącej opcji przesyłania.WALKING
prosi o wskazówki dojazdu przebiegające wzdłuż ścieżek dla pieszych i chodników (jeśli są dostępne).
Opcje transportu publicznego
Usługa Transport publiczny jest obecnie „eksperymentalna”. Na tym etapie będziemy wprowadzać limity liczby żądań, aby zapobiegać nadużywaniu interfejsu API. Ostatecznie nałożymy ograniczenie łącznej liczby zapytań na wczytanie mapy na podstawie dozwolonego użytku interfejsu API.
Dostępne opcje żądania macierzy odległości różnią się w zależności od środka transportu.
W przypadku żądań związanych z transportem publicznym opcje avoidHighways
i avoidTolls
są ignorowane. Opcje routingu dla transportu publicznego możesz określić za pomocą literału obiektu TransitOptions
.
Prośby o transport publiczny są pilne. 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śniono te pola:
arrivalTime
(opcjonalny) określa żądaną godzinę przyjazdu jako obiektDate
. Jeśli podasz godzinę przyjazdu, zostanie ona zignorowana.departureTime
(opcjonalny) określa docelową godzinę odjazdu w postaci obiektuDate
. Jeśli określisz parametrarrivalTime
, poledepartureTime
zostanie zignorowane. Jeśli nie podasz żadnej wartości w poludepartureTime
ani w zasadziearrivalTime
, przyjmuje się wartość domyślną teraz (czyli aktualnej godziny).modes
(opcjonalny) to tablica zawierająca co najmniej 1 literał obiektuTransitMode
. To pole można uwzględnić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Każdy atrybutTransitMode
określa preferowany środek transportu. Dozwolone są te wartości:BUS
oznacza, że obliczona trasa powinna preferować podróż autobusem.RAIL
oznacza, że obliczona trasa powinna preferować podróż pociągiem, tramwajem, tramwajem i 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ć podróż tramwajem i kolejką lekką.
routingPreference
(opcjonalny) określa preferencje dotyczące tras transportu publicznego. Dzięki tej opcji możesz zniekształcać 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
oznacza, że obliczona trasa powinna preferować ograniczoną długość trasy pieszej.
Opcje jazdy
Użyj obiektu drivingOptions
, aby określić czas odjazdu, który pozwoli Ci wyznaczyć najlepszą trasę do miejsca docelowego przy oczekiwanych warunkach na drodze. Możesz też określić, czy szacowany czas w ruchu ma być pesymistyczny, optymistyczny czy optymistyczny 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, aby literał obiektudrivingOptions
był prawidłowy) określa żądany czas wylotu jako obiektDate
. Wartość musi być ustawiona na bieżącą godzinę lub datę w przyszłości. Nie może to być data w przeszłości. Interfejs API konwertuje wszystkie daty na UTC, aby zapewnić spójność obsługi w różnych strefach czasowych. Jeśli w żądaniu umieściszdepartureTime
, interfejs API zwróci najlepszą trasę przy spodziewanych w danym momencie warunkach na drodze, a w odpowiedzi uwzględni przewidywany czas wystąpienia ruchu (duration_in_traffic
). Jeśli nie określisz godziny odjazdu (czyli jeśli żądanie nie zawiera atrybutudrivingOptions
), zwrócona trasa jest zwykle dobrą trasą bez uwzględnienia warunków drogowych.trafficModel
(opcjonalny) określa założenia, które należy stosować przy obliczaniu czasu w ruchu. To ustawienie wpływa na wartość zwracaną w poluduration_in_traffic
w odpowiedzi, która zawiera przewidywany czas ruchu na podstawie średnich wartości historycznych. Domyślna wartość tobest_guess
. Dozwolone są te wartości:bestguess
(wartość domyślna) wskazuje, że zwrócona wartośćduration_in_traffic
powinna być najdokładniejszym szacowanym czasem podróży, biorąc pod uwagę zarówno historyczne warunki, jak i aktualne natężenie ruchu. Aktualne natężenie ruchu staje się ważniejsze, im bliżej jestdepartureTime
.pessimistic
oznacza, że zwrócona wartośćduration_in_traffic
powinna być dłuższy niż rzeczywisty czas podróży w większość dni, choć w dni o szczególnie niekorzystnych warunkach na drogach może on przekraczać tę wartość.optimistic
oznacza, że zwrócona wartośćduration_in_traffic
powinna być krótsza niż rzeczywisty czas podróży w większość dni, ale w niektórych dniach, w których panuje wyjątkowo dobre warunki na drodze, może być on krótszy od tej wartości.
Poniżej znajdziesz przykładowy DistanceMatrixRequest
dotyczący tras dojazdu z uwzględnieniem czasu 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 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 punktu początkowego i docelowego, dla której można wyznaczyć 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 w odpowiedzi zostały objaśnione poniżej.
originAddresses
to tablica zawierająca lokalizacje przekazane w poluorigins
żądania macierzy odległości. Adresy są zwracane w miarę ich formatowania przez geokoder.destinationAddresses
to tablica zawierająca lokalizacje przekazane w poludestinations
w formacie zwracanym przez geokoder.rows
to tablica obiektówDistanceMatrixResponseRow
, przy czym każdy wiersz odpowiada swojemu punktowi początkowemu.elements
to elementy podrzędne tagurows
i odpowiadają parowaniu punktu początkowego wiersza z każdym miejscem docelowym. Zawierają one stan, czas trwania podróży, odległość i informacje o cenie (jeśli są dostępne) dla każdej pary wylotu i celu podróży.- Każdy element
element
zawiera te pola:status
: lista możliwych kodów stanu znajduje się na stronie Kody stanu.duration
: czas potrzebny na pokonanie tej trasy, wyrażony w sekundach (polevalue
) i jakotext
. Wartość tekstowa jest sformatowana zgodnie z atrybutemunitSystem
określonym w żądaniu (lub w danych, jeśli nie określono preferencji).duration_in_traffic
: czas potrzebny na przebycie tej trasy z uwzględnieniem bieżących warunków na drodze, wyrażony w sekundach (polevalue
) i w formacietext
. Wartość tekstowa jest sformatowana zgodnie z atrybutemunitSystem
określonym w żądaniu (lub w danych, jeśli nie określono preferencji). Poleduration_in_traffic
jest zwracane tylko wtedy, gdy są dostępne dane o ruchu,mode
ma wartośćdriving
, a poledepartureTime
jest zawarte w poludistanceMatrixOptions
w żądaniu.distance
: łączna odległość na tej trasie wyrażona w metrach (value
) i jakotext
. Wartość tekstowa jest sformatowana zgodnie z zasadąunitSystem
określoną w żądaniu (lub w wskaźniku, jeśli nie określono preferencji).fare
: zawiera łączną cenę (czyli łączne koszty biletu) na tej trasie. Ta właściwość jest zwracana tylko w przypadku zapytań dotyczących transportu publicznego i tylko w przypadku przewoźników, którzy mają dostęp do informacji o cenie. Są to między innymi:currency
: kod waluty w formacie 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ści oraz stan każdego elementu.
Kody stanu odpowiedzi
Kody stanu dotyczące obiektu 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 żadnym miejscem wylotu a miejscem docelowym. Informacje o stanie na poziomie elementu znajdziesz w sekcji Kody stanu elementu.INVALID_REQUEST
– przesłane żądanie było nieprawidłowe. Przyczyną tej sytuacji jest często brak wymaganych pól. Zobacz listę obsługiwanych pól powyżej.MAX_ELEMENTS_EXCEEDED
– iloczyn miejsc wylotu i miejsc docelowych przekracza limit dla poszczególnych zapytań.MAX_DIMENSIONS_EXCEEDED
– Twoja prośba zawierała 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 jeszcze raz, żądanie może zostać zrealizowane.
Kody stanu elementu
Te kody stanu mają zastosowanie do konkretnych obiektów DistanceMatrixElement
:
NOT_FOUND
– nie udało się przetworzyć danych geograficznych punktu początkowego lub docelowego pary.OK
– odpowiedź zawiera prawidłowy wynik.ZERO_RESULTS
– nie udało się znaleźć trasy między miejscem wylotu a celem podróży.
Analiza wyników
Obiekt DistanceMatrixResponse
zawiera po 1 obiekcie row
dla każdego punktu początkowego, który został przekazany w żądaniu. Każdy wiersz zawiera pole element
na potrzeby każdego parowania 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]; } } } }