Usługa wyznaczania trasy

Opis

Możesz wyznaczyć trasę dojazdu (przy użyciu różnych środków transportu) za pomocą obiektu DirectionsService. Ten obiekt komunikuje się z usługą wyznaczania trasy przez interfejs API Map Google, która odbiera żądania wskazówek dojazdu i zwraca efektywną ścieżkę. Czas podróży jest optymalizowanym głównym czynnikiem, ale uwzględniane są też inne czynniki, takie jak odległość, liczba skrętów i wiele innych. Możesz wykonać te instrukcje samodzielnie lub użyć obiektu DirectionsRenderer do wyrenderowania tych wyników.

Określając miejsce początkowe lub miejsce docelowe w pytaniu o wskazówki dojazdu, możesz podać ciąg zapytania (np. „Chicago, IL” lub „Darwin, NSW, Australia”), wartość LatLng lub obiekt Place.

Usługa wskazówek dojazdu może zwracać wieloczęściowe wskazówki za pomocą serii punktów na trasie. Wskazówki dojazdu są wyświetlane w postaci linii łamanej rysującej ją na mapie lub dodatkowo w postaci opisu tekstowego w elemencie <div> (np. „Skręć w prawo na rampę na moście Williamsburg”).

Pierwsze kroki

Zanim skorzystasz z usługi Directions w interfejsie Maps JavaScript API, sprawdź, czy interfejs Directions API jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany dla interfejsu Maps JavaScript API.

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

  1. Otwórz konsolę Google Cloud.
  2. Kliknij przycisk Wybierz projekt, a następnie wybierz projekt skonfigurowany na potrzeby interfejsu Maps JavaScript API i kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Directions API.
  4. Jeśli widzisz interfejs API na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
    1. Aby wyświetlić kartę Biblioteka, u góry strony wybierz WŁĄCZ API. Możesz też wybrać Biblioteka w menu po lewej stronie.
    2. Wyszukaj Directions API, a następnie wybierz go z listy wyników.
    3. Wybierz WŁĄCZ. Po zakończeniu procesu Directions API pojawi się na liście interfejsów API w panelu.

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. Więcej informacji o nowych cenach i limitach wykorzystania usługi Directions API znajdziesz w artykule Użycie i rozliczenia dotyczącym interfejsu Directions API.

Zasady

Korzystanie z usługi Directions API musi być zgodne z zasadami dotyczącymi interfejsu Directions API.

Zapytania o wskazówki dojazdu

Dostęp do usługi wskazówek dojazdu 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 zakończeniu żądania. Ta metoda wywołania zwrotnego powinna przetworzyć wyniki. Pamiętaj, że usługa „Wyznacz trasę” może zwrócić więcej niż 1 możliwy plan podróży w formie tablicy oddzielnych routes[].

Aby użyć wskazówek w interfejsie Maps JavaScript API, utwórz obiekt typu DirectionsService i wywołaj DirectionsService.route(), aby zainicjować żądanie do usługi Directions, przekazując do niego literał obiektu DirectionsRequest zawierający hasła wejściowe i metodę wywołania zwrotnego do wykonania po otrzymaniu odpowiedzi.

Literał obiektu DirectionsRequest zawiera te pola:

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

Poniżej objaśniamy te pola:

  • origin (wymagany) określa lokalizację początkową, z której mają być wyznaczane wskazówki dojazdu. Tę wartość można określić jako String (np. „Chicago, IL”), jako wartość LatLng lub jako obiekt Place. Jeśli używasz obiektu Place, możesz podać identyfikator miejsca, ciąg zapytania lub lokalizację LatLng. Identyfikatory miejsc możesz pobierać z usług geokodowania, wyszukiwania miejsc i autouzupełniania w interfejsie Maps JavaScript API. Przykład korzystania z identyfikatorów miejsc z autouzupełniania miejsc znajdziesz w artykule o autouzupełnianiu i wyznaczanie trasy.
  • destination (wymagany) określa lokalizację końcową, do której należy wyznaczać trasę. Dostępne opcje są takie same jak w przypadku pola origin opisanego powyżej.
  • travelMode (wymagany) określa środek transportu używany przy obliczaniu wskazówek dojazdu. Prawidłowe wartości podano poniżej w sekcji Tryby podróży.
  • transitOptions (opcjonalny) określa wartości mające zastosowanie tylko do żądań, w których travelMode to TRANSIT. Prawidłowe wartości opisano w sekcji Opcje transportu publicznego poniżej.
  • drivingOptions (opcjonalny) określa wartości mające zastosowanie tylko do żądań, w których travelMode to DRIVING. Prawidłowe wartości są opisane poniżej w sekcji Opcje jazdy.
  • unitSystem (opcjonalny) określa system jednostek, który ma być używany podczas wyświetlania wyników. Prawidłowe wartości podano poniżej w sekcji Systemy jednostek.

  • waypoints[] (opcjonalny) określa tablicę DirectionsWaypoints. Punkty pośrednie zmieniają trasę, kierując ją przez określone lokalizacje. Punkt pośredni jest określony jako literał obiektu z polami wymienionymi poniżej:

    • location określa lokalizację punktu pośredniego jako LatLng, jako obiekt Place lub String, który jest geokodowany.
    • stopover to wartość logiczna, która wskazuje, że punkt pośredni to przystanek na trasie, co skutkuje podzieleniem trasy na 2 trasy.

    Więcej informacji o punktach pośrednich znajdziesz poniżej w sekcji Korzystanie z punktów pośrednich na trasach.

  • optimizeWaypoints (opcjonalny) określa, że trasa korzystająca z podanego parametru waypoints może być optymalizowana przez zmianę kolejności punktów na trasie w sposób bardziej wydajny. Jeśli true, usługa wskazówek dojazdu zwróci ponownie zmodyfikowaną wartość waypoints w polu waypoint_order. Więcej informacji znajdziesz poniżej w sekcji Używanie punktów pośrednich na trasach.
  • provideRouteAlternatives (opcjonalny) ustawiony na true wskazuje, że usługa wskazówek dojazdu może udostępnić w odpowiedzi więcej niż 1 alternatywną trasę. Pamiętaj, że podanie alternatywnych tras może wydłużyć czas odpowiedzi serwera. Ta opcja jest dostępna tylko w przypadku żądań bez pośrednich punktów pośrednich.
  • avoidFerries (opcjonalny) gdy ustawisz wartość true, wskazuje, że na obliczonych trasach w miarę możliwości unikaj przepraw promowych.
  • avoidHighways (opcjonalny) gdy ustawisz wartość true, wskazuje, że wytyczone trasy powinny w miarę możliwości unikać głównych autostrad.
  • avoidTolls (opcjonalny) gdy ustawisz wartość true, wskazuje, że na wyliczonych trasach powinny w miarę możliwości omijać drogi płatne.
  • region (opcjonalny) określa kod regionu, który jest wartością dwuznakową domeny ccTLD („domena najwyższego poziomu”). Więcej informacji znajdziesz w sekcji Promowanie regionów poniżej.

Poniżej znajduje się przykładowy DirectionsRequest:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Środki transportu

Przy obliczaniu wskazówek dojazdu musisz określić środek transportu, którego chcesz użyć. Obecnie obsługiwane są te środki transportu:

  • DRIVING (domyślny) wskazuje standardowe wskazówki dojazdu z sieci dróg.
  • BICYCLING prosi o trasę rowerową ścieżkami rowerowymi i preferowanymi ulicami.
  • TRANSIT prosi o wskazówki dojazdu transportem publicznym.
  • WALKING prosi o trasę pieszej dla pieszych i chodników.

Aby dowiedzieć się, w jakim stopniu wskazówki dojazdu są obsługiwane w danym kraju, zapoznaj się ze szczegółami pokrycia kosztów Google Maps Platform. Jeśli poprosisz o wskazówki dojazdu do regionu, w którym dany typ wskazówek jest niedostępny, w odpowiedzi pojawi się wartość DirectionsStatus=„ZERO_RESULTS”.

Uwaga: trasa piesza może nie obejmować czystych ścieżek dla pieszych, dlatego ostrzeżenia te mogą pojawić się w interfejsie DirectionsResult. Te ostrzeżenia muszą być zawsze wyświetlane użytkownikowi. Jeśli nie używasz domyślnych ustawień DirectionsRenderer, odpowiadasz za wyświetlanie ostrzeżeń.

Opcje transportu publicznego

W przypadku zapytań o wskazówki dojazdu dostępne są różne opcje podróży. Przy wysyłaniu prośby o wskazówki dojazdu transportem publicznym opcje avoidHighways, avoidTolls, waypoints[] i optimizeWaypoints będą ignorowane. Opcje routingu w przypadku transportu publicznego możesz określić za pomocą literału obiektu TransitOptions.

Wskazówki dojazdu transportem publicznym są zależne od czasu. Wskazówki będą zwracane tylko w przyszłości.

Literał obiektu TransitOptions zawiera te pola:

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

Poniżej objaśniamy te pola:

  • arrivalTime (opcjonalny) określa żądaną godzinę przyjazdu jako obiekt Date. Jeśli podasz godzinę przyjazdu, godzina odjazdu zostanie zignorowana.
  • departureTime (opcjonalny) określa żądaną godzinę odjazdu jako obiekt Date. Jeśli określono arrivalTime, departureTime zostanie zignorowana. Jeśli w polu departureTime ani arrivalTime 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ów TransitMode. To pole można uwzględnić tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Każdy element 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 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.

Poniżej znajdziesz przykład trasy dojazdu transportem publicznym (DirectionsRequest):

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Opcje jazdy

Opcje wyznaczania trasy dojazdu możesz określić w obiekcie DrivingOptions.

Obiekt DrivingOptions zawiera te pola:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Poniżej objaśniamy te pola:

  • departureTime (wymagany do prawidłowego literału obiektu drivingOptions) określa wymagany czas odjazdu jako obiekt Date. 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). W przypadku klientów korzystających z abonamentu Premium Google Maps Platform, jeśli umieścisz w żądaniu pole departureTime, interfejs API zwróci najlepszą trasę przy oczekiwanych warunkach natężenia ruchu w danym momencie i w odpowiedzi wyświetli przewidywany czas w ruchu (duration_in_traffic). Jeśli nie podasz godziny odjazdu (czyli nie zawiera ono drivingOptions), 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 polu duration_in_traffic w odpowiedzi, które zawiera przewidywany czas w ruchu określony na podstawie średnich historycznych. Domyślna wartość to bestguess. 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, im bliżej departureTime jest.
    • 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 znajduje się przykładowy DirectionsRequest zawierający wskazówki dojazdu:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Systemy jednostkowe

Domyślnie wskazówki dojazdu są obliczane i wyświetlane zgodnie z systemem jednostek kraju lub regionu miejsca wylotu. (Uwaga: miejsca początkowe wyrażone za pomocą współrzędnych szerokości i długości geograficznej zamiast adresów zawsze są określane domyślnie jako jednostki metryczne). Na przykład w przypadku trasy z „Chicago, IL” do „Toronto, ONT” wyniki będą podawane w milach, a w przypadku trasy odwrotnej – w kilometrach. Możesz zastąpić ten system jednostek, ustawiając go bezpośrednio w żądaniu, używając jednej z tych wartości UnitSystem:

  • UnitSystem.METRIC określa wykorzystanie systemu metrycznego. Odległości są wyświetlane w kilometrach.
  • UnitSystem.IMPERIAL określa użycie systemu Imperial (angielskiego). Odległości są wyświetlane w milach.

Uwaga: to ustawienie systemu jednostek ma wpływ tylko na tekst wyświetlany użytkownikowi. Wynik wyznaczania trasy zawiera też wartości odległości, które nie są wyświetlane użytkownikowi, zawsze wyrażone w metrach.

Promowanie wskazówek dojazdu według regionu

Usługa wyznaczania tras interfejsu API Map Google zwraca wyniki dotyczące adresów, na które ma wpływ domena (region lub kraj), z której został wczytany plik wczytywania JavaScript. (Większość użytkowników wczytuje adres https://maps.googleapis.com/, co powoduje ustawienie domeny niejawnej na Stany Zjednoczone). Jeśli załadujesz proces wczytywania z innej obsługiwanej domeny, otrzymasz wyniki, na które wpływa ta domena. Na przykład wyszukiwanie hasła „San Francisco” może zwrócić inne wyniki niż w przypadku aplikacji ładującej https://maps.googleapis.com/ (Stany Zjednoczone) niż ładującej się aplikacji http://maps.google.es/ (Hiszpania).

Za pomocą parametru region możesz też ustawić w usłudze wskazówek dojazdu tak, aby zwracała wyniki wyświetlane w konkretnym regionie. Ten parametr przyjmuje kod regionu, określony jako dwuznakowy (nienumeryczny) podtag regionu Unicode. W większości przypadków tagi te są odwzorowywane bezpośrednio na dwuznakowe wartości domeny ccTLD („domena najwyższego poziomu”), np. „pl” w „co.uk”. W niektórych przypadkach tag region obsługuje też kody ISO-3166-1, które czasami różnią się od wartości domeny ccTLD (np. „GB” w przypadku słowa „Wielka Brytania”).

Gdy używasz parametru region:

  • Podaj tylko 1 kraj lub region. Wiele wartości zostanie zignorowanych, co może spowodować nieudane żądanie.
  • Używaj tylko dwuznakowych podtagów regionów (format Unicode CLDR). Wszystkie inne dane wejściowe będą powodować błędy.

Promowanie regionu jest obsługiwane tylko w przypadku krajów i regionów obsługujących wskazówki dojazdu. Sprawdź szczegóły pokrycia Google Maps Platform, aby poznać międzynarodowy zasięg interfejsu Directions API.

Wskazówki renderowania

Zainicjowanie żądania wskazówek dojazdu do obiektu DirectionsService za pomocą metody route() wymaga przekazania wywołania zwrotnego, które jest wykonywane po zakończeniu żądania usługi. To wywołanie zwrotne zwróci w odpowiedzi kod DirectionsResult i DirectionsStatus.

Stan zapytania o wskazówki dojazdu

DirectionsStatus może zwracać te wartości:

  • OK oznacza, że odpowiedź zawiera prawidłowy DirectionsResult.
  • NOT_FOUND wskazuje, że co najmniej jedna z lokalizacji podanych w punkcie początkowym, docelowym lub punkcie pośrednim nie może zostać zkodowana geograficznie.
  • ZERO_RESULTS oznacza, że nie znaleziono trasy między miejscem wylotu a celem podróży.
  • MAX_WAYPOINTS_EXCEEDED oznacza, że DirectionsRequest zawiera zbyt wiele pól DirectionsWaypoint. Zapoznaj się z sekcją poniżej, która opisuje limity punktów pośrednich.
  • MAX_ROUTE_LENGTH_EXCEEDED wskazuje, że żądana trasa jest zbyt długa i nie można jej przetworzyć. Ten błąd występuje, gdy zwracane są bardziej złożone kierunki. Spróbuj zmniejszyć liczbę punktów na trasie, skrętów lub instrukcji.
  • INVALID_REQUEST wskazuje, że podana wartość DirectionsRequest jest nieprawidłowa. Najczęstsze przyczyny tego kodu błędu to żądania, w których brakuje punktu początkowego lub docelowego albo żądania transportu publicznego zawierające punkty na trasie.
  • OVER_QUERY_LIMIT oznacza, że strona wysłała zbyt wiele żądań w dozwolonym okresie.
  • REQUEST_DENIED oznacza, że na stronie nie można korzystać z usługi wyznaczania trasy.
  • UNKNOWN_ERROR oznacza, że nie udało się przetworzyć żądania wskazówek dojazdu z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może zostać zrealizowane.

Sprawdź, czy zapytanie o wskazówki dojazdu zwraca prawidłowe wyniki, sprawdzając tę wartość przed ich przetworzeniem.

Wyświetlanie wyniku wskazówek dojazdu

Pole DirectionsResult zawiera wynik zapytania o wskazówki dojazdu, który możesz samodzielnie obsłużyć lub przekazać do obiektu DirectionsRenderer, który może automatycznie wyświetlać ten wynik na mapie.

Aby wyświetlić DirectionsResult za pomocą DirectionsRenderer, musisz wykonać te czynności:

  1. Utwórz obiekt DirectionsRenderer.
  2. Wywołaj setMap() w mechanizmie renderowania, aby powiązać ją z przekazaną mapą.
  3. Wywołaj w mechanizmie renderowania setDirections(), przekazując go jako DirectionsResult (jak wspomniano powyżej). Mechanizm renderowania to MVCObject, dlatego automatycznie wykryje wszelkie zmiany w jego właściwościach i zaktualizuje mapę, gdy zmienią się powiązane z nią wskazówki.

W tym przykładzie obliczamy wskazówki dojazdu między 2 lokalizacjami na drodze 66, gdzie miejsce wylotu i celu podróży są ustawiane przez podane wartości "start" i "end" na listach. DirectionsRenderer obsługuje wyświetlanie linii łamanej między wskazanymi lokalizacjami oraz położeniem znaczników w punkcie początkowym, docelowym i dowolnym punkcie na trasie (jeśli dotyczy).

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(result);
    }
  });
}

W treści HTML:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

Zobacz przykład

Poniższy przykład przedstawia trasę dojazdu z Haight-Ashbury do Ocean Beach w San Francisco za pomocą różnych środków transportu:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

W treści HTML:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

Zobacz przykład

Zasób DirectionsRenderer nie tylko obsługuje wyświetlanie linii łamanej i wszelkich powiązanych z nimi znaczników, ale może też obsługiwać tekstowe wyświetlanie wskazówek w ramach serii kroków. Aby to zrobić, wywołaj setPanel() w DirectionsRenderer i przekaż mu <div>, w którym są wyświetlane te informacje. Dzięki temu będziesz też wyświetlać odpowiednie informacje o prawach autorskich i ostrzeżenia, które mogą się wiązać z wynikiem.

Wskazówki tekstowe są podawane z uwzględnieniem ustawienia preferowanego języka w przeglądarce lub języka określonego podczas wczytywania JavaScriptu interfejsu API za pomocą parametru language. (Więcej informacji znajdziesz w artykule o lokalizacji). W przypadku wskazówek dojazdu transportem publicznym czas będzie wyświetlany w strefie czasowej tego przystanku.

Poniższy przykład jest taki sam jak powyższy, ale zawiera panel <div>, w którym wyświetlane są kierunki:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

W treści HTML:

<div id="map" style="float:left;width:70%;height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height:100%"></div>

Zobacz przykład

Obiekt DirectionsResult

Gdy wysyłasz do obiektu DirectionsService żądanie wskazówek dojazdu, otrzymujesz odpowiedź zawierającą kod stanu oraz wynik (obiektu DirectionsResult). DirectionsResult to literał obiektu z tymi polami:

  • geocoded_waypoints[] zawiera tablicę obiektów DirectionsGeocodedWaypoint, z których każdy zawiera szczegółowe informacje o geokodowaniu miejsca wylotu, miejsca docelowego i punktów na trasie.
  • routes[] zawiera tablicę obiektów DirectionsRoute. Każda trasa wskazuje sposób dotarcia z miejsca wylotu do miejsca docelowego podanego w polu DirectionsRequest. Zwykle w przypadku każdego żądania zwracana jest tylko jedna trasa, chyba że w jego polu provideRouteAlternatives ustawiono wartość true, co oznacza, że można zwrócić wiele tras.

Uwaga: w przypadku alternatywnych tras właściwość via_waypoint jest wycofana. Wersja 3.27 to ostatnia wersja interfejsu API, która wprowadza dodatkowe funkcje za pośrednictwem punktów pośrednich w trasach alternatywnych. W przypadku interfejsu API w wersji 3.28 i nowszych możesz nadal implementować przeciągane trasy za pomocą usługi Directions, wyłączając przeciąganie tras alternatywnych. Do przeciągania powinna być dostępna tylko trasa główna. Użytkownicy mogą przeciągać trasę główną, aż pasuje do trasy alternatywnej.

Wskazówki dojazdu z geokodowanymi punktami Waypoint

DirectionsGeocodedWaypoint zawiera szczegółowe informacje o geokodowaniu źródła, miejsca docelowego i punktów na trasie.

DirectionsGeocodedWaypoint to literał obiektu z tymi polami:

  • geocoder_status wskazuje kod stanu wynikający z operacji geokodowania. To pole może zawierać następujące wartości.
    • "OK" oznacza, że nie wystąpiły żadne błędy. Adres został pomyślnie przeanalizowany i zwrócono co najmniej jeden geokod.
    • "ZERO_RESULTS" oznacza, że geokod został przetworzony pomyślnie, ale nie zwrócił żadnych wyników. Może się tak zdarzyć, jeśli geokoder przekazał nieistniejący obiekt address.
  • partial_match oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, mimo że udało się dopasować część żądanego adresu. Warto sprawdzić w pierwotnej prośbie, czy adres nie zawiera błędów pisowni lub zawiera niepełny adres.

    Dopasowania częściowe najczęściej występują w przypadku adresów, które nie występują w rejonie podanym w żądaniu. Dopasowania częściowe mogą zostać zwrócone, gdy żądanie pasuje do co najmniej 2 lokalizacji w tym samym rejonie. Na przykład zapytanie „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie zarówno do ulicy Henry, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera komponent adresu z błędną pisownią, usługa geokodowania może zaproponować alternatywny adres. Sugestie uruchamiane w ten sposób będą również oznaczane jako dopasowania częściowe.

  • place_id to unikalny identyfikator miejsca, którego można używać z innymi interfejsami API Google. Możesz na przykład użyć obiektu place_id z biblioteką interfejsu Google Places API, aby uzyskać szczegółowe informacje o firmie lokalnej, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. Zobacz omówienie identyfikatorów miejsc.
  • types[] to tablica wskazująca typ zwracanego wyniku. Ta tablica zawiera zestaw tagów składających się z 0 lub więcej tagów identyfikujących typ cechy zwracanej w wyniku. Na przykład kod geograficzny „Chicago” zwraca ciąg „locality”, który wskazuje, że „Chicago” to miasto, i zwraca też słowo „polityczne”, które wskazuje, że podmiot polityczny.

Trasy wskazówek dojazdu

Uwaga: nazwa starszego obiektu DirectionsTrip została zmieniona na DirectionsRoute. Pamiętaj, że trasa odnosi się teraz do całej podróży od początku do końca, a nie tylko do jednego etapu podróży rodzica.

DirectionsRoute zawiera jeden wynik z podanego miejsca wylotu i miejsca docelowego. Ta trasa może składać się z jednego lub większej liczby odcinków (typu DirectionsLeg) w zależności od tego, czy zostały określone jakieś punkty pośrednie. Poza tym trasa zawiera też informacje o prawach autorskich i ostrzeżenia, które muszą być wyświetlane użytkownikowi.

DirectionsRoute to literał obiektu z tymi polami:

  • legs[] zawiera tablicę obiektów DirectionsLeg, z których każdy zawiera informacje o jednym z odcinków trasy z 2 lokalizacji w obrębie danej trasy. Dla każdego podanego punktu pośredniego lub miejsca docelowego będzie dostępny oddzielny odcinek. (Trasa bez punktów pośrednich zawiera dokładnie jeden element DirectionsLeg). Każdy etap składa się z serii DirectionStep.
  • waypoint_order zawiera tablicę wskazującą kolejność punktów pośrednich na obliczonej trasie. Ta tablica może zawierać zmienioną kolejność, jeśli właściwość DirectionsRequest została przekazana optimizeWaypoints: true.
  • overview_path zawiera tablicę LatLng, która reprezentuje przybliżoną (wygładzoną) ścieżkę wynikowych kierunków.
  • overview_polyline zawiera jeden obiekt points, który zawiera zakodowaną linię łamaną reprezentującą trasę. Ta linia łamana to przybliżona (wygładzona) ścieżka wynikowych kierunków.
  • bounds zawiera znak LatLngBounds, który wskazuje granice linii łamanej wzdłuż tej trasy.
  • copyrights zawiera tekst dotyczący praw autorskich, który będzie wyświetlany na tej trasie.
  • warnings[] zawiera tablicę ostrzeżeń, które będą wyświetlane podczas wyświetlania tych wskazówek. Jeśli nie używasz podanego obiektu DirectionsRenderer, musisz samodzielnie obsługiwać i wyświetlać te ostrzeżenia.
  • fare zawiera łączną cenę (czyli łączne koszty biletu) na tej trasie. Ta właściwość jest zwracana tylko w przypadku żądań transportu i tylko w przypadku tras, dla których dostępne są informacje o opłatach dla wszystkich etapów transportu. 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.

Kroki trasy

Uwaga: nazwa starszego obiektu DirectionsRoute została zmieniona na DirectionsLeg.

DirectionsLeg określa jeden etap podróży z miejsca wylotu do miejsca docelowego na obliczonej trasie. W przypadku tras niezawierających punktów pośrednich trasa będzie się składać z jednego „etapu”, natomiast w przypadku tras definiujących co najmniej jeden punkt trasy będzie się ona składać z jednego lub większej liczby etapów odpowiadających konkretnym etapom podróży.

DirectionsLeg to literał obiektu z tymi polami:

  • steps[] zawiera tablicę obiektów DirectionsStep oznaczających informacje o każdym kolejnym etapie podróży.
  • distance wskazuje całkowitą odległość pokonaną przez daną nogę jako obiekt Distance w tym formacie:

    • value wskazuje odległość w metrach.
    • text zawiera odległość w postaci ciągu, która jest domyślnie wyświetlana w jednostkach używanych w punkcie początkowym. (Na przykład mile będą używane w przypadku dowolnego miejsca wylotu na terenie Stanów Zjednoczonych). System jednostek możesz zastąpić, ustawiając w pierwotnym zapytaniu właściwość UnitSystem. Niezależnie od używanego systemu jednostek pole distance.value zawsze zawiera wartość wyrażoną w metrach.

    Te pola mogą być nieokreślone, jeśli odległość jest nieznana.

  • duration wskazuje całkowity czas trwania tego etapu jako obiekt Duration w tej formie:

    • value wskazuje czas trwania w sekundach.
    • text zawiera ciąg znaków reprezentujący czas trwania.

    Te pola mogą być nieokreślone, jeśli czas trwania jest nieznany.

  • duration_in_traffic wskazuje całkowity czas trwania tego etapu z uwzględnieniem bieżących warunków drogowych. duration_in_traffic jest zwracana tylko wtedy, gdy są spełnione wszystkie te warunki:

    • Żądanie nie zawiera punktów pośrednich na trasie. Oznacza to, że nie uwzględniają punktów pośrednich, w których stopover to true.
    • Żądanie dotyczy wskazówek dojazdu – mode jest ustawiony na driving.
    • departureTime występuje w polu drivingOptions w żądaniu.
    • Informacje o natężeniu ruchu są dostępne dla żądanej trasy.

    duration_in_traffic zawiera te pola:

    • value wskazuje czas trwania w sekundach.
    • text zawiera zrozumiałą dla człowieka reprezentację czasu trwania.
  • arrival_time zawiera szacowany czas dotarcia na ten etap. Ta właściwość jest zwracana tylko w przypadku wskazówek dojazdu transportem publicznym. Wynik jest zwracany jako obiekt Time z 3 właściwościami:
    • value czas podany jako obiekt Date w JavaScripcie.
    • text czas podany w formie ciągu znaków. Godzina jest wyświetlana w strefie czasowej przystanku transportu publicznego.
    • time_zone zawiera strefę czasową tej stacji. Wartość jest nazwą strefy czasowej zdefiniowana w bazie danych stref czasowych IANA, np. „Ameryka/Nowy_Jork”.
  • departure_time zawiera szacowany czas odjazdu na tym etapie, określony jako obiekt Time. departure_time jest dostępny tylko w przypadku wskazówek dojazdu transportem publicznym.
  • start_location zawiera LatLng początku tego etapu. Usługa sieciowa wskazówek dojazdu oblicza wskazówki dojazdu między lokalizacjami przy użyciu najbliższego sposobu transportu (zwykle drogi) na punkcie początkowym i końcowym, dlatego start_location może się różnić od podanego początku tego odcinka, jeśli na przykład droga nie znajduje się w pobliżu punktu początkowego.
  • end_location zawiera LatLng miejsca docelowego tego etapu. Ponieważ DirectionsService oblicza wskazówki dojazdu między lokalizacjami na podstawie najbliższego środka transportu (zwykle drogi) na punkcie początkowym i końcowym, end_location może się różnić od podanego celu podróży, jeśli np. droga nie znajduje się w pobliżu miejsca docelowego.
  • start_address zawiera czytelny dla człowieka adres (zwykle adres) na początku tego etapu.

    Nie należy odczytywać tych treści w niezmienionej postaci. Nie analizuj automatycznie sformatowanego adresu.
  • end_address zawiera czytelny dla człowieka adres (zwykle adres) na końcu tego etapu.

    Nie należy odczytywać tych treści w niezmienionej postaci. Nie analizuj automatycznie sformatowanego adresu.

Etapy trasy

DirectionsStep to najbardziej atomowa jednostka trasy, zawierająca pojedynczy krok opisujący konkretną, pojedynczą instrukcję na trasie. Na przykład „Skręć w lewo o W. Ul. Podolska” Etap zawiera nie tylko opis instrukcji, ale także informacje o odległości i czasie trwania dotyczące ostatniego kroku. Na przykład krok oznaczony jako „Wjedź na I-80 West” może mieć czas trwania „37 mil” i „40 minut”, co oznacza, że następny krok to 57 mil/40 minut od tego kroku.

Gdy używasz usługi wskazówek dojazdu do wyszukiwania wskazówek dojazdu transportem publicznym, tablica kroków zawiera dodatkowe informacje o transporcie publicznym w postaci obiektu transit. Jeśli wskazówki dojazdu obejmują kilka środków transportu, szczegółowe wskazówki dojazdu będą podane w tablicy steps[]. Na przykład krok pieszy będzie obejmował wskazówki dojazdu z lokalizacji początkowej i końcowej: „Idź do Innes Ave & Fitch Street”. Zobaczysz tam szczegółowe wskazówki piesze tej trasy w tablicy steps[], na przykład „Skieruj się na północny zachód”, „Skręć w lewo na Arelious Walker” i „Skręć w lewo na Innes Ave”.

DirectionsStep to literał obiektu z tymi polami:

  • instructions zawiera instrukcje dotyczące tego kroku w ciągu tekstowym.
  • distance zawiera odległość pokonaną przez ten krok do następnego kroku jako obiekt Distance. (Zobacz opis w sekcji DirectionsLeg powyżej). To pole może być nieokreślone, jeśli odległość jest nieznana.
  • duration podaje szacowany czas potrzebny na wykonanie kroku do następnego kroku jako obiekt Duration. (Zobacz opis w DirectionsLeg powyżej). To pole może być nieokreślone, jeśli czas trwania jest nieznany.
  • start_location zawiera kod geograficzny LatLng z punktu początkowego tego kroku.
  • end_location zawiera LatLng punktu końcowego tego kroku.
  • polyline zawiera jeden obiekt points, który zawiera zakodowaną linię łamaną reprezentującą krok. Ta linia łamana to przybliżona (wygładzona) ścieżka kroku.
  • steps[] literał obiektu DirectionsStep zawierający szczegółowe wskazówki dojazdu pieszo lub krokami w trasach transportu publicznego. Podetapy są dostępne tylko dla wskazówek dojazdu transportem publicznym.
  • travel_mode zawiera TravelMode użyte w tym kroku. Trasa dojazdu transportem publicznym może obejmować połączenie tras pieszych i transportowych.
  • path zawiera tablicę LatLngs opisującą przebieg tego kroku.
  • transit zawiera informacje dotyczące transportu publicznego, takie jak godziny przyjazdu i odjazdu oraz nazwa linii transportu publicznego.

Informacje o transporcie publicznym

Wskazówki dojazdu transportem publicznym zwracają dodatkowe informacje, które nie są istotne w przypadku innych środków transportu. Te dodatkowe właściwości są ujawniane przez obiekt TransitDetails zwracany jako właściwość DirectionsStep. Z poziomu obiektu TransitDetails możesz uzyskać dostęp do dodatkowych informacji o obiektach TransitStop, TransitLine, TransitAgency i VehicleType, jak opisano poniżej.

Szczegóły dotyczące transportu publicznego

Obiekt TransitDetails ujawnia te właściwości:

  • arrival_stop zawiera obiekt TransitStop reprezentujący stację/przystanek z tymi właściwościami:
    • name nazwa stacji/przystanku. np. „plac Solny”.
    • location lokalizacja stacji/przystanku, podana w postaci LatLng.
  • departure_stop zawiera obiekt TransitStop reprezentujący stację/przystanek odjazdu.
  • arrival_time zawiera godzinę przyjazdu, która jest określona jako obiekt Time z 3 właściwościami:
    • value czas podany jako obiekt Date w JavaScripcie.
    • text czas podany w formie ciągu znaków. Godzina jest wyświetlana w strefie czasowej przystanku transportu publicznego.
    • time_zone zawiera strefę czasową tej stacji. Wartość jest nazwą strefy czasowej zdefiniowana w bazie danych stref czasowych IANA, np. „Ameryka/Nowy_Jork”.
  • departure_time zawiera godzinę odjazdu, która jest określona jako obiekt Time.
  • headsign określa kierunek podróży na tej linii, zgodnie z oznaczeniem na pojeździe lub na przystanku odjazdu. Często będzie to stacja terminalu.
  • headway, jeśli jest dostępny, określa oczekiwaną liczbę sekund między odjazdem z tego samego przystanku w tej chwili. Jeśli na przykład headway ma wartość 600, w razie spóźnienia na autobus spodziewasz się 10 minut oczekiwania.
  • line zawiera literał obiektu TransitLine zawierający informacje o linii transportu publicznego użytego w tym kroku. TransitLine zawiera nazwę i operator wiersza, a także inne właściwości opisane w dokumentacji referencyjnej dotyczącej TransitLine.
  • num_stops zawiera liczbę przystanków w tym kroku. Obejmuje przystanek przyjazdu, ale nie przystanek wylotu. Jeśli np. wskazówki dojazdu obejmują wyruszenie ze przystanku A, przejazd przez przystanki B i C, a dojazd do przystanku D, num_stops zwróci 3.

Linia komunikacyjna

Obiekt TransitLine ujawnia te właściwości:

  • name zawiera pełną nazwę tej linii transportu publicznego. np. „ul. Główna 7” lub „ul. Jagiellońska 14”.
  • short_name zawiera krótką nazwę tej linii transportu publicznego. Zwykle jest to numer wiersza, np. „2” lub „M14”.
  • agencies to tablica zawierająca pojedynczy obiekt TransitAgency. Obiekt TransitAgency zawiera informacje o operatorze tego wiersza, w tym te właściwości:
    • name zawiera nazwę przewoźnika.
    • phone zawiera numer telefonu przewoźnika.
    • url zawiera adres URL przewoźnika.

    Uwaga: jeśli zamiast korzystać z obiektu DirectionsRenderer, renderujesz wskazówki dojazdu transportem publicznym, musisz wyświetlić nazwy i adresy URL przewoźników obsługujących wyniki wyszukiwania.

  • url zawiera adres URL tej linii transportu publicznego podany przez przewoźnika.
  • icon zawiera adres URL ikony powiązanej z tą linią. Większość miast będzie używać ikon ogólnych, które różnią się w zależności od typu pojazdu. Niektóre linie transportu publicznego, np. system metra w Nowym Jorku, mają ikony odnoszące się do tych linii.
  • color zawiera kolor, który jest często używany na szyldach i znakach dotyczących tego transportu. Kolor zostanie określony w postaci ciągu szesnastkowego, np. #FF0033.
  • text_color zawiera kolor tekstu często używany do oznaczania tego wiersza. Kolor zostanie określony w postaci ciągu szesnastkowego.
  • vehicle zawiera obiekt Vehicle z tymi właściwościami:
    • name zawiera nazwę pojazdu w tej linii. np. „Metro”.
    • type zawiera typ pojazdu używanego na tej linii. Pełną listę obsługiwanych wartości znajdziesz w dokumentacji typu pojazdu.
    • icon zawiera adres URL ikony często związanej z tym typem pojazdu.
    • local_icon zawiera adres URL ikony powiązanej z tym typem pojazdu zgodnie z informacjami o lokalnym transporcie.

Typ pojazdu

Obiekt VehicleType ujawnia te właściwości:

Wartość Definicja
VehicleType.RAIL Kolej.
VehicleType.METRO_RAIL Transport kolejowy.
VehicleType.SUBWAY Podziemna kolej miejska.
VehicleType.TRAM Nadziemna kolej miejska.
VehicleType.MONORAIL Kolej jednoszynowa.
VehicleType.HEAVY_RAIL Kolej ciężka.
VehicleType.COMMUTER_TRAIN Kolej podmiejska.
VehicleType.HIGH_SPEED_TRAIN Szybki pociąg.
VehicleType.BUS Autobus.
VehicleType.INTERCITY_BUS Autobus dalekobieżny.
VehicleType.TROLLEYBUS Trolejbus.
VehicleType.SHARE_TAXI Taksówka zbiorowa to rodzaj autobusu z możliwością wysiadania i zabrania pasażerów w dowolnym miejscu na trasie.
VehicleType.FERRY Prom.
VehicleType.CABLE_CAR Pojazd na kablu, zazwyczaj znajdujący się na ziemi. Kolejki linowe mogą należeć do typu VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Kolejka linowa.
VehicleType.FUNICULAR Pojazd podciągnięty linowo po stromym zboczu. Kolej linowo-terenowa zwykle składa się z 2 samochodów, z których każdy pełni rolę przeciwwagi dla drugiego.
VehicleType.OTHER Wszystkie inne pojazdy będą zwracać ten typ.

Sprawdzanie wyników wskazówek dojazdu

Komponenty DirectionsResultsDirectionsRoute, DirectionsLeg, DirectionsStep i TransitDetails – mogą być sprawdzane i używane podczas analizowania odpowiedzi na wskazówki dojazdu.

Ważne: jeśli ręcznie renderujesz wskazówki dojazdu, a nie używasz obiektu DirectionsRenderer, musisz wyświetlić nazwy i adresy URL przewoźników obsługujących wyniki podróży.

W poniższym przykładzie pokazujemy wskazówki piesze do niektórych atrakcji turystycznych w Nowym Jorku. Sprawdzamy DirectionsStep trasy, aby dodać znaczniki na każdym etapie, i dołączamy do elementu InfoWindow informacje z instrukcjami dotyczącymi tego kroku.

Uwaga: ponieważ obliczamy wskazówki piesze, wyświetlamy też użytkownikowi wszelkie ostrzeżenia w osobnym panelu <div>.

var map;
var directionsRenderer;
var directionsService;
var stepDisplay;
var markerArray = [];

function initMap() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

W treści HTML:

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

Zobacz przykład

Używanie punktów pośrednich na trasach

Jak wskazano w żądaniu DirectionsRequest, możesz też określić punkty pośrednie (typu DirectionsWaypoint) podczas obliczania tras pieszych, rowerowych lub samochodowych przy użyciu usługi DirectionsRequest. Punkty pośrednie są niedostępne w przypadku wskazówek dojazdu transportem publicznym. Punkty pośrednie umożliwiają obliczanie tras przez dodatkowe lokalizacje. W takim przypadku zwrócona trasa przechodzi przez określone punkty na trasie.

waypoint składa się z tych pól:

  • location (wymagany) określa adres punktu pośredniego.
  • Element stopover (opcjonalny) wskazuje, czy ten punkt pośredni jest rzeczywistym przystankiem na trasie (true), czy tylko preferencją pokonywania tej trasy (false). Przystanki mają domyślnie wartość true.

Domyślnie usługa Wskazówki dojazdu oblicza trasę przez podane punkty na trasie w podanej ich kolejności. Opcjonalnie możesz wyprzedzić optimizeWaypoints: true w DirectionsRequest, aby umożliwić usłudze Trasa dojazdu optymalizowanie wskazywanej trasy przez zmianę kolejności punktów na trasie w sposób bardziej wydajny. (Ta optymalizacja dotyczy problemu podróżujących pracowników działu sprzedaży). Czas podróży jest optymalizowanym głównym czynnikiem, ale przy wyborze trasy można uwzględnić też inne czynniki, takie jak odległość, liczba skrętów i wiele innych. Aby usługa „Trasa dojazdu” mogła zoptymalizować trasę, wszystkie punkty na trasie muszą być przystankami.

Jeśli nakażesz usłudze wskazówki dojazdu, aby zoptymalizować kolejność punktów na trasie, ich kolejność zostanie zwrócona w polu waypoint_order w obiekcie DirectionsResult.

W tym przykładzie obliczamy trasy biegowe w Stanach Zjednoczonych na podstawie różnych punktów początkowych, końcowych i punktów na trasie. (Aby wybrać wiele punktów na liście, podczas wybierania elementów na liście naciśnij Ctrl i kliknij). Sprawdzamy pola routes.start_address i routes.end_address, aby przekazać nam tekst dla punktu początkowego i końcowego każdej trasy.

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 6,
    center: { lat: 41.85, lng: -87.65 },
  });

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: document.getElementById("start").value,
      destination: document.getElementById("end").value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;

Ograniczenia i ograniczenia dotyczące punktów pośrednich Waypoints

Obowiązują te limity użytkowania:

  • Maksymalna dozwolona liczba punktów na trasie podczas korzystania z usługi Directions w interfejsie Maps JavaScript API to 25 plus miejsce wylotu i docelowe. Limity są takie same w przypadku usługi sieciowej interfejsu Directions API.
  • W przypadku usługi internetowej interfejsu Directions API klienci mogą mieć maksymalnie 25 punktów na trasie oraz miejsce wylotu i docelowe.
  • Klienci korzystający z abonamentu premium Google Maps Platform mogą mieć maksymalnie 25 punktów pośrednich oraz miejsce odjazdu i miejsca docelowego.
  • Punkty pośrednie nie są obsługiwane w przypadku wskazówek dojazdu transportem publicznym.

Przeciąganie wskazówek

Użytkownicy mogą dynamicznie modyfikować wyświetlane wskazówki dojazdu rowerem, pieszo lub samochodem, jeśli są przeciągane. Pozwala to użytkownikom wybierać i zmieniać trasy przez klikanie i przeciąganie powstałych w ten sposób ścieżek na mapie.DirectionsRenderer Aby wskazać, czy na wyświetlaczu mechanizmu renderowania można przeciągać kierunki, ustaw jego właściwość draggable na true. Nie można przeciągnąć trasy dojazdu transportem publicznym.

Gdy wskazówki dojazdu można przeciągać, użytkownik może wybrać dowolny punkt na ścieżce (lub punkt pośredni) z renderowanego wyniku i przenieść wskazany komponent do nowej lokalizacji. Element DirectionsRenderer będzie się dynamicznie aktualizować, pokazując zmodyfikowaną ścieżkę. Po uwolnieniu do mapy zostanie dodany tymczasowy punkt pośredni (oznaczony małym białym znacznikiem). Zaznaczenie i przesunięcie fragmentu ścieżki spowoduje zmianę tego odcinka trasy, natomiast wybranie i przesunięcie znacznika punktu pośredniego (w tym punktu początkowego i końcowego) spowoduje zmianę odcinków trasy przechodzącej przez ten punkt.

Możliwe do przeciągania wskazówki są modyfikowane i renderowane po stronie klienta, dlatego warto monitorować i obsługiwać zdarzenie directions_changed w elemencie DirectionsRenderer, aby otrzymywać powiadomienia, gdy użytkownik zmieni wyświetlane wskazówki.

Poniższy kod przedstawia podróż z Perth na zachodnim wybrzeżu Australii do Sydney na wschodnim wybrzeżu. Kod monitoruje zdarzenie directions_changed, aby aktualizować całkowitą odległość wszystkich etapów podróży.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -24.345, lng: 134.46 }, // Australia.
    }
  );

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
Zobacz przykład

Wypróbuj fragment