wprowadzenie

interfejs API Distance Matrix jest usługą, która zapewnia odległość i czas podróży dla macierzy początków i miejsc docelowych. Interfejs API zwraca informacje na podstawie zalecanej trasy między punktami początkowymi i końcowymi, obliczonej przez interfejs API Map Google, i składa się z wierszy zawierających wartości duration I distance dla każdej pary.

Uwaga: Ta usługa nie zwraca szczegółowych informacji o trasie. Informacje o trasie można uzyskać, przekazując żądany pojedynczy punkt początkowy i docelowy do interfejsu API Directions.

przed rozpoczęciem

ten dokument jest przeznaczony dla programistów, którzy chcą obliczyć odległość i czas podróży między kilkoma punktami w ramach map dostarczonych przez jeden z interfejsów API Map Google. Stanowi wprowadzenie do korzystania z API i materiałów referencyjnych na temat dostępnych parametrów.

przed rozpoczęciem tworzenia interfejsu API macierzy odległości zapoznaj się z wymaganiami uwierzytelniania (potrzebny jest klucz API) oraz informacjami o użytkowaniu i rozliczeniach API (musisz włączyć rozliczanie w projekcie).

żądania macierzy odległości

żądanie API macierzy odległości ma następującą postać:

gdzie outputFormat może być jedną z następujących wartości:

• json (zalecane), wskazuje wyjście w JavaScript Object Notation (JSON); lub
• xml, wskazuje wyjście jako XML.

Uwaga: adresy URL muszą być poprawnie zakodowane i są ograniczone do 8192 znaków dla wszystkich serwisów internetowych. Pamiętaj o tym limicie podczas konstruowania adresów URL. Należy pamiętać, że różne przeglądarki, Serwery Proxy i serwery mogą mieć różne limity znaków URL.

bezpieczeństwo HTTPS lub HTTP

jest ważne, a protokół HTTPS jest zalecany w miarę możliwości, szczególnie w przypadku aplikacji zawierających wrażliwe dane użytkownika, takie jak lokalizacja użytkownika, w żądaniach. Korzystanie z szyfrowania HTTPS sprawia, że aplikacja jest bezpieczniejsza i bardziej odporna na szpiegowanie lub manipulowanie.

Jeśli HTTPS nie jest możliwy, aby uzyskać dostęp do API macierzy odległości przez HTTP, użyj:

parametry żądania

niektóre parametry są wymagane, podczas gdy inne są opcjonalne. Standardowo w adresach URL wszystkie parametry są oddzielane znakiem ampersand (&). Wszystkie zastrzeżone znaki (na przykład znak plus „+”) muszą być zakodowane URL.Poniżej znajduje się lista parametrów i ich Możliwe wartości.

wymagane parametry

• origins — punkt wyjścia do obliczania odległości i czasu przejazdu. Możesz podać jedną lub więcej lokalizacji oddzielonych znakiem potoku(|), w postaci identyfikatora miejsca, adresu lub współrzędnych szerokości/długości geograficznej:
  • Jeśli podasz identyfikator miejsca, musisz go poprzedzić place_id:. Identyfikator miejsca można podać tylko wtedy, gdy żądanie zawiera klucz API lub identyfikator klienta planu Premium Google Maps Platform. Identyfikatory miejsc można pobrać z interfejsów API geokodowania i API miejsc (w tym autouzupełniania miejsc). Przykład użycia identyfikatorów place z funkcji Place Autocomplete: umieść Autocomplete i wskazówki. Aby uzyskać więcej informacji o identyfikatorach miejsc, zobacz Przegląd identyfikatorów miejsc.
  • Jeśli podasz adres, usługa geokoduje łańcuch i konwertuje go na współrzędną szerokości / długości geograficznej, aby obliczyć odległość. Ta współrzędna może się różnić od tej zwracanej przez API kodowania Geologicznego, na przykład wejście do budynku, a nie jego środek.

    origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON

    Uwaga: preferowane jest używanie identyfikatorów miejsc zamiast adresów lub współrzędnych szerokości/długości geograficznej. Użycie współrzędnych zawsze spowoduje, że punkt zostanie przyciągnięty do drogi najbliższej tym współrzędnym-co może nie być punktem dostępu do nieruchomości, a nawet drogą, która szybko lub bezpiecznie doprowadzi do celu.
  • jeśli przejdziesz współrzędne szerokości / długości geograficznej, będą one przyciągać do najbliższej drogi. Preferowane jest przekazywanie identyfikatora miejsca. Jeśli przekażesz współrzędne, upewnij się, że między wartościami szerokości i długości geograficznej nie ma odstępu.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • kody Plus muszą być sformatowane jako kod globalny lub kod złożony. Formatuj kody plus, Jak pokazano tutaj (znaki plus to url-escape do %2B I spacje to url-escape do %20):
    • kod Globalny to 4-znakowy kod obszaru i 6-znakowy lub dłuższy kod lokalny (849VCWC8+R9 to 849VCWC8%2BR9).
    • kod złożony to 6-znakowy lub dłuższy kod lokalny z wyraźną lokalizacją (CWC8 + R9 Mountain View, CA, USA to CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Alternatywnie możesz podać zakodowany zestaw współrzędnych za pomocą zakodowanego algorytmu polilinii. Jest to szczególnie przydatne, jeśli masz dużą liczbę punktów początkowych, ponieważ adres URL jest znacznie krótszy podczas korzystania z zakodowanej polilinii.
    • zakodowane poliliny muszą być poprzedzone enc:, a następnie dwukropkiem (:).Na przykład: origins=enc:gfo}EtohhU:
    • Możesz również dołączyć wiele zakodowanych polilinii, oddzielonych znakiem potoku (|). Na przykład: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — jedno lub więcej miejsc do wykorzystania jako punkt końcowy do obliczania odległości i czasu podróży. Opcje dla parametrudestinations są takie same jak dla parametruorigins, opisanego powyżej.
• key — klucz API Twojej aplikacji. Ten klucz identyfikuje Twoją aplikację do celów zarządzania kwotami. Dowiedz się, jak zdobyć klucz.

  Uwaga: Klienci planu Premium Google Maps Platform mogą używać klucza API lub ważnego identyfikatora klienta i podpisu cyfrowego w żądaniach macierzy odległości. Uzyskaj więcej informacji na temat parametrów uwierzytelniania dla klientów planu Premium.

poniższy przykład używa współrzędnych szerokości / długości geograficznej, aby określić współrzędne docelowe:

poniższy przykład używa kodów plus, aby określić współrzędne docelowe:

poniższy przykład pokazuje to samo żądanie za pomocą zakodowanej polilinii:

parametry opcjonalne

• mode (domyślniedriving) — określa rodzaj transportu, który ma być użyty przy obliczaniu odległości. Prawidłowe wartości i inne szczegóły żądania są określone w sekcji tryby podróży tego dokumentu.
• language — język, w którym zwracane są wyniki.
  • Zobacz listę obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być wyczerpująca.
  • Jeśli language nie jest dostarczany, API próbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub języka ojczystego domeny, z której wysyłane jest żądanie.
  • API dokłada wszelkich starań, aby zapewnić adres ulicy, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby osiągnąć ten cel, zwraca adresy ulic w lokalnym języku, transliteracji na skrypt czytelny przez użytkownika, w razie potrzeby, z zachowaniem preferowanego języka. Wszystkie pozostałe adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który jest wybrany z pierwszego komponentu.
  • Jeśli nazwa nie jest dostępna w preferowanym języku, API używa najbliższego dopasowania.
  • preferowany język ma niewielki wpływ na zbiór wyników, które API wybiera do zwrócenia, oraz kolejność, w jakiej są zwracane. Geocoder interpretuje skróty w różny sposób w zależności od języka, na przykład skróty dla typów ulic lub synonimy, które mogą być ważne w jednym języku, ale nie w innym. Na przykład utca i tér są synonimami ulicy w języku węgierskim.
• region — Kod Regionu, określony jako dwuznakowa wartość ccTLD (domena najwyższego poziomu kodu kraju). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z pewnymi wyjątkami. Parametr ten wpĹ 'ywa jedynie na, a nie caĹ’ kowicie ograniczy, wyniki z geokodera. Jeżeli istnieją bardziej istotne wyniki poza określonym regionem, można je uwzględnić.
• avoid — wprowadza ograniczenia do trasy. Prawidłowe wartości są określone w sekcji Ograniczenia tego dokumentu. Można określić tylko jedno ograniczenie.
• units — określa system jednostek, który ma być używany przy wyrażaniu odległości jako tekst. Więcej informacji można znaleźć w sekcji Systemy jednostek tego dokumentu.
• arrival_time — określa żądany czas przybycia dla żądań tranzytowych, w sekundach od północy, 1 stycznia 1970 UTC. Możesz określić departure_time lub arrival_time, ale nie oba. Należy zauważyć, że arrival_time musi być podana jako liczba całkowita.
• departure_time — żądany czas odjazdu. Możesz określić czas jako liczbę całkowitą w sekundach od północy, 1 stycznia 1970 UTC. Jeśli podano departure_time później niż 9999-12-31t23:59:59.99999999999 z, API cofnie departure_time do 9999-12-31t23:59:59.9999999999 Z. Alternatywnie można określić wartość now, który ustawia czas odjazdu na czas bieżący (poprawny do najbliższej sekundy). Czas wyjazdu może być określony w dwóch przypadkach:
  • dla wniosków, w których tryb podróży jest tranzyt: Opcjonalnie można podać jeden z departure_time lub arrival_time. Jeśli nie podano żadnego czasu, departure_time domyślnie ustawia się na now (tzn. czas odjazdu domyślnie na czas bieżący).
  • dla żądań, w których tryb jazdy jest Jazdy: możesz określić departure_time, aby otrzymać trasę i czas trwania podróży (pole odpowiedzi: duration_in_traffic), które uwzględniają warunki drogowe. Ta opcja jest dostępna tylko wtedy, gdy żądanie zawiera prawidłowy klucz API lub prawidłowy identyfikator i podpis klienta planu Google Maps Platform Premium. departure_time musi być ustawiony na bieżący czas lub jakiś czas w przyszłości. To nie może być przeszłość.

    Uwaga :Jeśli czas odjazdu nie jest określony, wybór trasy i czasu trwania zależy od sieci drogowej i średnich warunków ruchu niezależnych od czasu. Wyniki dla danego żądania mogą się zmieniać w czasie ze względu na zmiany w sieci drogowej, zaktualizowane średnie warunki ruchu oraz rozproszony charakter usługi. Wyniki mogą się również różnić w zależności od prawie równoważnych tras w dowolnym momencie lub z dowolnej częstotliwości.

    Uwaga: żądania macierzy odległości określającedeparture_time, gdymode=driving są ograniczone do maksymalnie 100 elementów na żądanie. Liczba początków razy liczba miejsc docelowych określa liczbę elementów.

• traffic_model(domyślniebest_guess) — określa założenia do wykorzystania przy obliczaniu czasu w ruchu. To ustawienie wpływa na wartość zwróconą w poluduration_in_traffic w odpowiedzi, które zawiera przewidywany czas ruchu na podstawie średnich historycznych. Parametrtraffic_model może być określony tylko dla żądań, w których tryb podróży todriving I gdzie żądanie zawieradeparture_time I tylko wtedy, gdy żądanie zawiera klucz API lub identyfikator klienta planu Premium Google Maps Platform. Dostępne wartości dla tego parametru to:
  • best_guess(domyślnie) wskazuje, że zwróconyduration_in_traffic powinien być najlepszym oszacowaniem czasu podróży, biorąc pod uwagę to, co wiadomo zarówno o historycznych warunkach drogowych, jak i ruchu na żywo. Ruch na żywo staje się ważniejszy im bliżej departure_time jest do teraz.
  • pessimisticwskazuje, że zwracanyduration_in_traffic powinien być dłuższy niż rzeczywisty czas podróży w większości dni, chociaż sporadyczne dni o szczególnie złych warunkach drogowych mogą przekraczać tę wartość.
  • optimisticwskazuje, że zwracanyduration_in_traffic powinien być krótszy niż rzeczywisty czas podróży w większości dni, choć okazjonalne dni o szczególnie dobrych warunkach drogowych mogą być szybsze niż ta wartość.
• transit_mode — określa jeden lub więcej preferowanych trybów transportu. Ten parametr może być określony tylko dla żądań, w których mode jest transit. Parametr obsługuje następujące argumenty:
  • bus wskazuje, że obliczona trasa powinna preferować podróż autobusem.
  • 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 lekką koleją.
  • rail wskazuje, że obliczona trasa powinna preferować podróż pociągiem, tramwajem, lekką koleją i metrem. Jest to odpowiednik transit_mode=train|tram|subway.
• transit_routing_preference — określa preferencje dla zapytań tranzytowych. Korzystając z tego parametru, możesz zmienić ustawienia zwracanych opcji, zamiast akceptować domyślną najlepszą trasę wybraną przez API. Ten parametr może być określony tylko dla żądań, w których mode jest transit. Parametr obsługuje następujące argumenty:
  • less_walking wskazuje, że obliczona trasa powinna preferować ograniczone ilości chodzenia.
  • fewer_transfers wskazuje, że obliczona trasa powinna preferować ograniczoną liczbę transferów.

tryby podróży

do obliczania odległości można określić transportmode, którego należy użyć. Domyślnie odległości są obliczane dla trybu jazdy. Obsługiwane są następujące tryby jazdy:

• driving (domyślnie) wskazuje Obliczanie odległości z wykorzystaniem sieci drogowej.
• walking żąda obliczenia odległości do chodzenia po ścieżkach dla pieszych& chodniki (jeśli są dostępne).
• bicycling żąda obliczenia odległości do jazdy rowerem po ścieżkach rowerowych& preferowane ulice (jeśli są dostępne).
• transit żąda obliczenia odległości za pomocą publicznych tras tranzytowych (jeśli są dostępne). Wartość ta może zostać określona tylko wtedy, gdy żądanie zawiera klucz API lub identyfikator klienta planu Premium Google Maps Platform. Jeśli ustawisz tryb na transit, możesz opcjonalnie określić departure_time lub arrival_time. Jeśli nie podano żadnego czasu, departure_time domyślnie ustawia się na now (tzn. czas odjazdu domyślnie na czas bieżący). Możesz również opcjonalnie dołączyć transit_mode I/lub transit_routing_preference.

informacje o ruchu drogowym

informacje o ruchu drogowym są używane, gdy mają zastosowanie wszystkie poniższe warunki (są to warunki wymagane do otrzymania pola duration_in_traffic w odpowiedzi na matrycę odległości):

• parametr podróży mode to driving, lub nie jest określony (driving jest domyślnym trybem podróży).
• żądanie zawiera poprawny parametrdeparture_timedeparture_time można ustawić na bieżący czas lub jakiś czas w przyszłości. To nie może być przeszłość.

opcjonalnie w zapytaniu można uwzględnić parametrtraffic_model w celu określenia założeń do obliczenia czasu w ruchu.

poniższy URL inicjuje żądanie macierzy odległości Dla odległości jazdy między Boston, MA lub Charlestown, MA, a Lexington, MA i Concord, MA. Żądanie Zawiera czas odjazdu, spełniający wszystkie wymagania, aby zwrócić poleduration_in_traffic w odpowiedzi macierzy odległości.

ograniczenia

odległości mogą być obliczane zgodnie z pewnymi ograniczeniami. Ograniczenia są wskazywane przez użycie parametruavoid I argumentu do tego parametru wskazującego ograniczenie, którego należy unikać. Obsługiwane są następujące ograniczenia:

• avoid=tolls
• avoid=highways
• avoid=ferries
• avoid=indoor

* uwaga: dodanie ograniczeń nie wyklucza tras, które zawierają funkcję Restricted; powoduje przesunięcie wyniku na bardziej korzystne trasy.

Układy jednostek

wyniki macierzy odległości zawierajątext wdistance pola wskazujące odległość obliczonej trasy. Można określić system jednostek:

• units=metric (domyślnie) zwraca odległości w kilometrach i metrach.
• units=imperial zwraca odległości w milach i stopach.

* Uwaga: To ustawienie systemu jednostek wpływa tylko natext wyświetlane wdistance pola. Poladistance zawierają równieżvalues, które są zawsze wyrażone w metrach.

odpowiedzi macierzy odległości

odpowiedzi na zapytania API macierzy odległości są zwracane w formacie wskazanym przez znacznik output w ścieżce żądania URL.

Poniżej przedstawiono dwa przykładowe żądania HTTP, z prośbą o odległość i czas trwania z Vancouver, BC, Kanada i z Seattle, WA, USA, do San Francisco, CA, USA i Victoria, BC, Kanada.

to żądanie demonstruje użycie flagi JSONoutput :

to żądanie demonstruje użycie znacznika XMLoutput:

to żądanie zwróci cztery elementy – dwa początki razy dwa miejsca docelowe:

wyniki są zwracane w wierszach, każdy wiersz zawiera jeden początek sparowany z każdym miejscem docelowym.

możesz to przetestować, wprowadzając adres URL do przeglądarki internetowej (pamiętaj, aby zastąpićYOUR_API_KEY rzeczywistym kluczem API).

Wybierz zakładki poniżej, aby zobaczyć przykładowe odpowiedzi JSON i XML.

reszta dokumentacji będzie używać składni JSON.

Elementy odpowiedzi macierzy odległości

odpowiedzi macierzy odległości zawierają następujące elementy główne:

• status zawiera metadane dotyczące żądania. Zobacz kody statusu poniżej.
• origin_addresses zawiera tablicę adresów zwróconych przez API z pierwotnego żądania. Są one sformatowane przez geocoder i zlokalizowane zgodnie z parametremlanguage przekazanym wraz z żądaniem.
• destination_addresses zawiera tablicę adresów zwróconych przez API z pierwotnego żądania. Podobnie jak w przypadku origin_addresses, w razie potrzeby są one zlokalizowane.
• rowszawiera tablicęelements, które z kolei zawierająstatusdurationIdistance element.

kody stanu

polastatus w obiekcie odpowiedzi zawierają status żądania i mogą zawierać przydatne informacje o debugowaniu. Interfejs API Distance Matrix zwraca pole statusu najwyższego poziomu, zawierające ogólne informacje o żądaniu,a także pole statusu dla każdego pola elementu, zawierające informacje o danym parowaniu pochodzenie-cel.

kody statusu najwyższego poziomu

• OK wskazuje, że odpowiedź zawiera poprawnyresult.
• INVALID_REQUEST wskazuje, że dostarczone żądanie było nieprawidłowe.
• MAX_ELEMENTS_EXCEEDED oznacza, że produkt pochodzenia i przeznaczenia przekracza limit dla zapytania.
• MAX_DIMENSIONS_EXCEEDED oznacza, że liczba początków lub miejsc docelowych przekracza limit dla zapytania.
• OVER_DAILY_LIMIT wskazuje którekolwiek z poniższych:
  • brakuje klucza API lub jest on nieprawidłowy.
  • Fakturowanie nie zostało włączone na twoim koncie.
  • przekroczono narzucony przez siebie limit użycia.
  • podana metoda płatności nie jest już ważna (na przykład karta kredytowa wygasła).

  zobacz FAQ Maps, aby dowiedzieć się, jak to naprawić.

• OVER_QUERY_LIMIT wskazuje, że usługa otrzymała zbyt wiele żądań z Twojej aplikacji w dozwolonym czasie.
• REQUEST_DENIED wskazuje, że usługa odmówiła korzystania z usługi macierzy odległości przez Twoją aplikację.
• UNKNOWN_ERROR wskazuje, że żądanie macierzy odległości nie mogło zostać przetworzone z powodu błędu serwera. Żądanie może się udać, jeśli spróbujesz ponownie.

kody stanu elementów

• OK wskazuje, że odpowiedź zawiera poprawnyresult.
• NOT_FOUND wskazuje, że pochodzenie i / lub przeznaczenie tego parowania nie może być geokodowane.
• ZERO_RESULTS wskazuje, że nie można znaleźć trasy między miejscem pochodzenia a miejscem docelowym.
• MAX_ROUTE_LENGTH_EXCEEDED wskazuje, że żądana trasa jest zbyt długa i nie może być przetworzona.

komunikaty o błędach

gdy kod stanu najwyższego poziomu jest inny niżOK, może istnieć dodatkowe poleerror_message w obiekcie odpowiedzi macierzy odległości. To pole zawiera bardziej szczegółowe informacje na temat przyczyn podanego kodu statusu.

Uwaga: To pole nie ma gwarancji, że będzie zawsze obecne, a jego treść może ulec zmianie.

wiersze

gdy API macierzy odległości zwraca wyniki, umieszcza je w tablicy JSONrows. Nawet jeśli nie są zwracane żadne wyniki (np. gdy nie istnieją źródła i/lub cele docelowe), to i tak zwraca pustą tablicę. Odpowiedzi XML składają się z zero lub więcej elementów <row>.

wiersze są uporządkowane według wartości w parametrze origin żądania. Każdy wiersz odpowiada początkowi, a każdy element w tym wierszu odpowiada parowaniu początku z wartością destination.

każda tablicarow zawiera jeden lub więcej wpisówelement, które z kolei zawierają informacje o pojedynczym parowaniu pochodzenie-cel.

Elementy

informacje o każdym parowaniu origin-destination są zwracane w pozycji elementelement zawiera następujące pola:

• status: Zobacz kody statusu, aby uzyskać listę możliwych kodów statusu.
• duration: czas potrzebny na przebycie tej trasy, wyrażony w sekundach (polevalue) oraz jakotext. Reprezentacja tekstowa jest zlokalizowana zgodnie z parametrem language zapytania.

• duration_in_traffic: czas potrzebny na pokonanie tej trasy, w oparciu o aktualne i historyczne warunki ruchu. Zobacztraffic_model parametr żądania dla opcji, których możesz użyć, aby zażądać, aby zwrócona wartość była optymistyczna, pesymistyczna lub Szacunkowa. Czas trwania jest wyrażony w sekundach (pole value) I jako text. Reprezentacja tekstowa jest zlokalizowana zgodnie z parametrem language zapytania. Czas trwania ruchu jest zwracany tylko wtedy, gdy wszystkie z poniższych wartości są prawdziwe:

  • żądanie zawiera parametr departure_time.
  • żądanie zawiera ważny klucz API lub prawidłowy identyfikator i podpis klienta planu Google Maps Platform Premium.
  • warunki ruchu są dostępne dla żądanej trasy.
  • parametrmode jest ustawiony nadriving.
• distance: całkowita odległość tej trasy wyrażona w metrach (value) I jakotext. Wartość tekstowa wykorzystuje system jednostek określony parametremunit pierwotnego żądania lub regionu pochodzenia.
• fare: jeśli istnieje, zawiera całkowitą taryfę (czyli całkowite koszty biletu) na tej trasie. Ta nieruchomość jest zwracana tylko w przypadku wniosków tranzytowych i tylko dla dostawców usług tranzytowych, w których dostępne są informacje o taryfach. Informacje obejmują:
  • currency: Kod waluty ISO 4217 wskazujący walutę, w której wyrażona jest kwota.
  • value: całkowita kwota taryfy, w walucie określonej powyżej.
  • text: całkowita kwota taryfy sformatowana w żądanym języku.

poniżej znajduje się przykład element zawierający informacje o taryfie:

parametr czujnika

interfejs API Map Google wymagał wcześniej podania parametrusensor, aby wskazać, czy Twoja aplikacja używała asensora do określania lokalizacji użytkownika. Ten parametr nie jest dłuższywymagane.