Directions Service (starsza wersja)

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)
Uwaga: biblioteki po stronie serwera

Przegląd

Możesz obliczać wskazówki dojazdu (korzystając z różnych środków transportu) za pomocą obiektu DirectionsService. Ten obiekt komunikuje się z usługą wskazówek dojazdu interfejsu API Map Google, która odbiera żądania wskazówek dojazdu i zwraca optymalną trasę. Czas podróży jest głównym czynnikiem, który jest optymalizowany, ale pod uwagę mogą być brane inne czynniki, takie jak odległość, liczba zakrętów i wiele innych. Możesz samodzielnie obsłużyć te wyniki kierunkowe lub użyć obiektu DirectionsRenderer, aby je wyrenderować.

Podczas określania miejsca wyjazdu lub miejsca docelowego w żądaniu wskazówek dojazdu możesz podać ciąg zapytania (np. „Chicago, IL” lub „Darwin, NSW, Australia”), wartość LatLng lub obiekt Place.

Usługa Directions może zwracać wieloczęściowe wskazówki dojazdu, korzystając z serii punktów pośrednich. Wskazówki dojazdu są wyświetlane jako linia łamana przedstawiająca trasę na mapie lub dodatkowo jako seria opisów tekstowych w elemencie <div> (np. „Skręć w prawo na zjazd na most Williamsburg Bridge”).

Pierwsze kroki

Zanim zaczniesz korzystać z usługi wskazówek dojazdu w Maps JavaScript API, upewnij się, że interfejs Directions API (starsza wersja) jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany na potrzeby 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 ten sam projekt, który został skonfigurowany dla interfejsu Maps JavaScript API, i kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Directions API (starsza wersja).
  4. Jeśli interfejs API jest na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go na stronie https://console.cloud.google.com/apis/library/directions-backend.googleapis.com.

Ceny i zasady

Ceny

Informacje o cenach i zasadach korzystania z usługi JavaScript Directions znajdziesz w sekcji Korzystanie i rozliczenia dotyczącej interfejsu Directions API (starsza wersja).

Zasady

Korzystanie z usługi Directions musi być zgodne z zasadami opisanymi w przypadku interfejsu Directions API (starsza wersja).

Zapytania o trasę

Dostęp do usługi wskazówek dojazdu jest asynchroniczny, ponieważ interfejs API Map Google musi wywołać serwer zewnętrzny. Z tego powodu 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 wskazówek dojazdu może zwrócić więcej niż 1 możliwy plan podróży jako tablicę oddzielnych obiektów routes[].

Aby używać wskazówek dojazdu w interfejsie Maps JavaScript API, utwórz obiekt typu DirectionsService i wywołaj DirectionsService.route(), aby zainicjować żądanie do usługi wskazówek dojazdu, przekazując jej literał obiektu DirectionsRequest zawierający dane wejściowe i metodę wywołania zwrotnego, która ma zostać wykonana 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
}

Pola te zostały opisane poniżej:

  • origin (wymagany) określa lokalizację początkową, od której mają być obliczane 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 określić identyfikator miejsca, ciąg zapytania lub lokalizację LatLng. Identyfikatory miejsc możesz pobierać z usług geokodowania, wyszukiwania miejsc i autouzupełniania miejsc w interfejsie Maps JavaScript API. Przykład użycia identyfikatorów miejsc z autouzupełniania miejsc znajdziesz w artykule Autouzupełnianie miejsc i wskazówki dojazdu.
  • destination (wymagany) określa lokalizację końcową, do której mają zostać wyznaczone wskazówki dojazdu. Opcje są takie same jak w przypadku pola origin opisanego powyżej.
  • travelMode (wymagany) określa środek transportu, który ma być używany podczas obliczania wskazówek dojazdu. Prawidłowe wartości są podane poniżej w sekcji Środki transportu.
  • transitOptions (opcjonalny) określa wartości, które mają zastosowanie tylko do żądań, w których travelMode to TRANSIT. Prawidłowe wartości są opisane poniżej w sekcji Opcje transportu.
  • drivingOptions (opcjonalny) określa wartości, które mają 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, jakiego systemu jednostek używać podczas wyświetlania wyników. Prawidłowe wartości są podane w sekcji Układy jednostek poniżej.

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

    • location określa lokalizację punktu pośredniego jako LatLng, obiekt Place lub String, który zostanie poddany geokodowaniu.
    • stopover to wartość logiczna, która wskazuje, że punkt pośredni jest przystankiem na trasie, co powoduje podzielenie trasy na 2 trasy.

    (Więcej informacji o punktach pośrednich znajdziesz w sekcji Używanie punktów pośrednich w trasach poniżej).

  • optimizeWaypoints (opcjonalny) określa, że trasa z użyciem podanego waypoints może zostać zoptymalizowana przez zmianę kolejności punktów na trasie na bardziej efektywną. Jeśli true, usługa Directions zwróci zmienioną kolejność waypoints w polu waypoint_order.(Więcej informacji znajdziesz poniżej w sekcji Używanie punktów pośrednich w trasach).
  • provideRouteAlternatives (opcjonalny) – jeśli jest ustawiony na true, określa, że usługa wskazówek dojazdu może podać w odpowiedzi więcej niż 1 trasę alternatywną. Pamiętaj, że podanie alternatywnych tras może wydłużyć czas odpowiedzi serwera. Ta funkcja jest dostępna tylko w przypadku żądań bez pośrednich punktów orientacyjnych.
  • avoidFerries (opcjonalny) – ustawienie wartości true wskazuje, że obliczone trasy powinny w miarę możliwości omijać promy.
  • avoidHighways (opcjonalny) – gdy jest ustawiony na true, wskazuje, że obliczone trasy powinny w miarę możliwości omijać główne autostrady.
  • avoidTolls (opcjonalny) – gdy jest ustawiony na true, wskazuje, że obliczone trasy powinny w miarę możliwości unikać dróg płatnych.
  • region (opcjonalny) określa kod regionu jako dwuznakową wartość ccTLD („domena najwyższego poziomu”). (Więcej informacji znajdziesz w sekcji Faworyzowanie regionu poniżej).

Poniżej znajdziesz przykładowy plik 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

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

  • DRIVING (Default) – wskazuje standardowe wskazówki dojazdu z wykorzystaniem sieci dróg.
  • BICYCLING prosi o wskazówki dojazdu rowerem ścieżkami rowerowymi i preferowanymi ulicami.
  • TRANSIT prosi o wskazówki dojazdu trasami transportu publicznego.
  • WALKING prosi o trasę pieszą ścieżkami dla pieszych i chodnikami.

Aby dowiedzieć się, w jakim stopniu dany kraj obsługuje wskazówki dojazdu, zapoznaj się z szczegółami dotyczącymi zasięgu Google Maps Platform. Jeśli poprosisz o wskazówki dojazdu w regionie, w którym dany typ wskazówek jest niedostępny, odpowiedź zwróci DirectionsStatus="ZERO_RESULTS".

Uwaga: trasy piesze mogą nie obejmować wyraźnych ścieżek dla pieszych, dlatego w DirectionsResult będą wyświetlane ostrzeżenia. Te ostrzeżenia muszą być zawsze wyświetlane użytkownikowi. Jeśli nie używasz domyślnego elementu DirectionsRenderer, musisz zadbać o to, aby ostrzeżenia były wyświetlane.

Opcje transportu publicznego

Dostępne opcje prośby o wskazówki dojazdu różnią się w zależności od środka transportu. Podczas wysyłania prośby o wskazówki dojazdu transportem publicznym opcje avoidHighways, avoidTolls, waypoints[] i optimizeWaypoints będą ignorowane. Możesz określić opcje wyznaczania trasy dla transportu publicznego za pomocą literału obiektu TransitOptions.

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

Literał obiektu TransitOptions zawiera te pola:

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

Pola te zostały opisane poniżej:

  • arrivalTime (opcjonalny) określa pożądany czas przybycia jako obiekt Date. Jeśli podano czas przyjazdu, czas odjazdu jest ignorowany.
  • departureTime (opcjonalny) określa żądany czas odjazdu jako obiekt Date. Jeśli podasz arrivalTime, departureTime zostanie zignorowany. Jeśli nie podano wartości dla departureTime ani arrivalTime, domyślnie przyjmuje się bieżący czas.
  • modes[] (opcjonalny) to tablica zawierająca co najmniej 1 literał obiektu 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óż pociągiem, tramwajem, koleją miejską 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ć podróż tramwajem i koleją miejską.
  • routingPreference (opcjonalny) określa preferencje dotyczące tras transportu publicznego. Za pomocą tej opcji możesz wpływać na 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 wskazuje, że obliczona trasa powinna preferować ograniczone ilości chodzenia.

Poniżej znajduje się przykładowy DirectionsRequest transportem publicznym:

{
  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 dla wskazówek dojazdu możesz określić za pomocą obiektu DrivingOptions.

Obiekt DrivingOptions zawiera te pola:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Pola te zostały opisane poniżej:

  • departureTime (wymagany, aby literał obiektu drivingOptions był prawidłowy) określa żądany czas odjazdu jako obiekt Date. Wartość musi być ustawiona na bieżący czas lub czas w przyszłości. Nie może przypadać w przeszłości. (Interfejs API konwertuje wszystkie daty na czas UTC, aby zapewnić spójne działanie w różnych strefach czasowych). Jeśli klienci korzystający z abonamentu Premium Google Maps Platform uwzględnią w żądaniu parametr departureTime, interfejs API zwróci najlepszą trasę z uwzględnieniem przewidywanych warunków na drodze w danym momencie i poda w odpowiedzi przewidywany czas jazdy w ruchu ulicznym (duration_in_traffic). Jeśli nie określisz godziny wyjazdu (czyli jeśli żądanie nie zawiera parametru drivingOptions), zwrócona trasa będzie ogólnie dobra, ale nie będzie uwzględniać warunków na drodze.
  • trafficModel (opcjonalny) określa założenia, które mają być używane podczas obliczania czasu w ruchu drogowym. To ustawienie wpływa na wartość zwracaną w polu duration_in_traffic w odpowiedzi, które zawiera przewidywany czas w ruchu ulicznym na podstawie średnich historycznych. Domyślna wartość to bestguess. Dozwolone są te wartości:
    • bestguess (domyślny) wskazuje, że zwracany obiekt duration_in_traffic powinien być najlepszym oszacowaniem czasu podróży na podstawie informacji o historycznych i bieżących warunkach na drodze. Im bliżej bieżącego momentu znajduje się departureTime, tym ważniejsze stają się informacje o ruchu na żywo.
    • pessimistic wskazuje, że zwracany czas duration_in_traffic powinien być dłuższy niż rzeczywisty czas podróży w większości dni, chociaż w niektóre dni, gdy warunki na drodze są szczególnie złe, może przekroczyć tę wartość.
    • optimistic wskazuje, że zwracany czas duration_in_traffic powinien być krótszy niż rzeczywisty czas podróży w większości dni, chociaż w niektóre dni, gdy warunki na drodze są szczególnie dobre, czas podróży może być krótszy niż ta wartość.

Poniżej znajdziesz przykładowy obiekt DirectionsRequest ze wskazówkami 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'
  }
}

Układy jednostek

Domyślnie wskazówki dojazdu są obliczane i wyświetlane przy użyciu systemu jednostek kraju lub regionu, z którego pochodzi zapytanie. (Uwaga: miejsca początkowe wyrażone za pomocą współrzędnych geograficznych, a nie adresów, są zawsze domyślnie podawane w jednostkach metrycznych). Na przykład trasa z „Chicago, IL” do „Toronto, ONT” będzie wyświetlać wyniki w milach, a trasa w odwrotnym kierunku – w kilometrach. Możesz zastąpić ten system jednostek, ustawiając go bezpośrednio w żądaniu za pomocą jednej z tych wartości UnitSystem:

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

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

Dostosowywanie wskazówek dojazdu do regionu

Usługa wskazówek dojazdu interfejsu API Map Google zwraca wyniki adresowe, na które wpływa domena (region lub kraj), z której wczytano kod JavaScript. (Ponieważ większość użytkowników wczytuje https://maps.googleapis.com/, ustawia to niejawną domenę na Stany Zjednoczone). Jeśli wczytasz kod początkowy z innej obsługiwanej domeny, otrzymasz wyniki, na które ta domena będzie miała wpływ. Na przykład wyszukiwanie hasła „San Francisco” może zwracać inne wyniki w aplikacjach, które wczytują https://maps.googleapis.com/ (Stany Zjednoczone), niż w tych, które wczytują http://maps.google.es/ (Hiszpania).

Możesz też ustawić usługę wskazówek dojazdu tak, aby zwracała wyniki faworyzujące dany region, używając parametru region. Ten parametr przyjmuje kod regionu określony jako dwuznakowy (nienumeryczny) podtag regionu Unicode. W większości przypadków te tagi są mapowane bezpośrednio na dwuznakowe wartości ccTLD („domena najwyższego poziomu”), np. „uk” 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 ccTLD (np. „GB” dla „Wielkiej Brytanii”).

Podczas korzystania z parametru region:

  • Podaj tylko jeden kraj lub region. Wiele wartości jest ignorowanych i może spowodować niepowodzenie żądania.
  • Używaj tylko 2-znakowych podtagów regionu (format Unicode CLDR). Wszystkie inne dane wejściowe spowodują błędy.

Ustalanie regionu jest obsługiwane tylko w krajach i regionach, w których obsługiwane są wskazówki dojazdu. Aby sprawdzić zasięg międzynarodowy interfejsu Directions API (starsza wersja), zapoznaj się z szczegółami zasięgu Google Maps Platform.

Renderowanie wskazówek dojazdu

Inicjowanie zapytania o trasę dojazdu do DirectionsService za pomocą metody route() wymaga przekazania wywołania zwrotnego, które jest wykonywane po zakończeniu zapytania o usługę. To wywołanie zwrotne zwróci w odpowiedzi kod DirectionsResult i DirectionsStatus.

Stan zapytania o trasę

DirectionsStatus może zwracać te wartości:

  • OK wskazuje, że odpowiedź zawiera prawidłowy DirectionsResult.
  • NOT_FOUND oznacza, że nie udało się znaleźć kodu geograficznego co najmniej jednej z lokalizacji określonych w żądaniu jako punkt początkowy, punkt docelowy lub punkt pośredni.
  • ZERO_RESULTS oznacza, że nie udało się znaleźć trasy między miejscem początkowym a docelowym.
  • MAX_WAYPOINTS_EXCEEDED wskazuje, że w DirectionsRequest podano zbyt wiele pól DirectionsWaypoint. Więcej informacji znajdziesz w sekcji Limity dotyczące punktów na trasie poniżej.
  • MAX_ROUTE_LENGTH_EXCEEDED oznacza, że żądana trasa jest za długa i nie można jej przetworzyć. Ten błąd występuje, gdy zwracane są bardziej złożone wskazówki dojazdu. Spróbuj zmniejszyć liczbę punktów na trasie, skrętów lub instrukcji.
  • INVALID_REQUEST wskazuje, że podany parametr DirectionsRequest był nieprawidłowy. Najczęstsze przyczyny tego kodu błędu to żądania, w których brakuje miejsca początkowego lub docelowego, albo żądania dotyczące transportu publicznego, które zawierają punkty pośrednie.
  • OVER_QUERY_LIMIT oznacza, że strona internetowa wysłała zbyt wiele żądań w dozwolonym okresie.
  • REQUEST_DENIED oznacza, że strona internetowa nie może korzystać z usługi wskazówek dojazdu.
  • UNKNOWN_ERROR oznacza, że nie udało się przetworzyć prośby o wskazówki dojazdu z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.

Przed przetworzeniem wyniku sprawdź tę wartość, aby upewnić się, że zapytanie o wskazówki dojazdu zwróciło prawidłowe wyniki.

Wyświetlanie DirectionsResult

Obiekt DirectionsResult zawiera wynik zapytania o trasę, który możesz obsłużyć samodzielnie lub przekazać do obiektu DirectionsRenderer, który może automatycznie obsłużyć wyświetlanie wyniku na mapie.

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

  1. Utwórz obiekt DirectionsRenderer.
  2. Wywołaj funkcję setMap() w rendererze, aby powiązać go z przekazaną mapą.
  3. Wywołaj metodę setDirections() w rendererze, przekazując jej obiekt DirectionsResult, jak opisano powyżej. Ponieważ moduł renderujący jest obiektem MVCObject, automatycznie wykrywa wszelkie zmiany swoich właściwości i aktualizuje mapę, gdy powiązane z nią wskazówki dojazdu ulegną zmianie.

W tym przykładzie obliczane są wskazówki dojazdu między 2 lokalizacjami na Route 66, gdzie miejsce rozpoczęcia i zakończenia trasy są określone przez podane wartości "start" i "end" na listach. DirectionsRenderer obsługuje wyświetlanie linii łamanej między wskazanymi lokalizacjami oraz umieszczanie znaczników w miejscu początkowym, docelowym i w punktach pośrednich (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 pokazuje wskazówki dojazdu różnymi środkami transportu z Haight-Ashbury do Ocean Beach w San Francisco w Kalifornii:

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

Obiekt DirectionsRenderer nie tylko obsługuje wyświetlanie linii łamanej i powiązanych z nią znaczników, ale może też wyświetlać wskazówki dojazdu w formie serii kroków. Aby to zrobić, wywołaj setPanel() na DirectionsRenderer, przekazując <div>, w którym mają być wyświetlane te informacje. Dzięki temu wyświetlisz też odpowiednie informacje o prawach autorskich i wszelkie ostrzeżenia, które mogą być powiązane z wynikiem.

Wskazówki tekstowe będą podawane w języku preferowanym w przeglądarce lub w języku określonym podczas wczytywania interfejsu API JavaScript za pomocą parametru language. (więcej informacji znajdziesz w artykule na temat lokalizacji). W przypadku wskazówek dojazdu transportem publicznym godzina będzie wyświetlana w strefie czasowej przystanku.

Poniższy przykład jest identyczny z powyższym, ale zawiera panel <div>, w którym wyświetlane są wskazówki dojazdu:

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 żądanie wskazówek do interfejsu DirectionsService, otrzymujesz odpowiedź zawierającą kod stanu i wynik, który jest obiektem 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 rozpoczęcia, miejsca docelowego i punktów pośrednich.
  • routes[] zawiera tablicę obiektów DirectionsRoute. Każda trasa wskazuje sposób dotarcia z miejsca wyjazdu do miejsca docelowego podanego w parametrze DirectionsRequest. Zwykle w odpowiedzi na dane żądanie zwracana jest tylko jedna trasa, chyba że pole provideRouteAlternatives żądania ma wartość true. W takim przypadku może zostać zwróconych kilka tras.

Uwaga: właściwość via_waypoint jest wycofana w trasach alternatywnych. Wersja 3.27 to ostatnia wersja interfejsu API, która dodaje dodatkowe punkty pośrednie na trasach alternatywnych. W przypadku interfejsu API w wersji 3.28 lub nowszej możesz nadal implementować wskazówki dojazdu z możliwością przeciągania za pomocą usługi Directions, wyłączając przeciąganie tras alternatywnych. Można przeciągać tylko główną trasę. Użytkownicy mogą przeciągać główną trasę, aż będzie pasować do trasy alternatywnej.

Punkty trasy z geokodowaniem w Directions API

DirectionsGeocodedWaypoint zawiera szczegółowe informacje o kodowaniu geograficznym miejsca rozpoczęcia podróży, miejsca docelowego i punktów pośrednich.

DirectionsGeocodedWaypoint to literał obiektu z tymi polami:

  • geocoder_status wskazuje kod stanu wynikający z operacji geokodowania. To pole może zawierać te wartości:
    • "OK" oznacza, że nie wystąpiły żadne błędy, adres został pomyślnie przeanalizowany i zwrócono co najmniej 1 kod geograficzny.
    • "ZERO_RESULTS" oznacza, że kodowanie geograficzne zakończyło się powodzeniem, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli do geokodera przekazano nieistniejący element address.

  • partial_match wskazuje, że geokoder nie zwrócił dopasowania ścisłego do pierwotnego żądania, ale udało mu się dopasować część żądanego adresu. Sprawdź, czy w pierwotnym żądaniu nie ma błędów pisowni lub niekompletnego adresu.

    Częściowe dopasowania występują najczęściej w przypadku adresów, które nie istnieją w miejscowości podanej w żądaniu. Częściowe dopasowania mogą być też zwracane, gdy żądanie pasuje do co najmniej 2 lokalizacji w tej samej miejscowości. Na przykład „Hillpar St, Bristol, UK” zwróci częściowe dopasowanie zarówno dla Henry Street, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera błędnie wpisany element adresu, usługa geokodowania może zasugerować alternatywny adres. Sugestie wywołane w ten sposób będą również oznaczone jako częściowe dopasowanie.

  • place_id to unikalny identyfikator miejsca, którego można używać z innymi interfejsami API Google. Możesz na przykład użyć place_id z biblioteką Google Places API, aby uzyskać szczegółowe informacje o firmie działającej lokalnie, takie jak numer telefonu, godziny otwarcia, opinie użytkowników i inne. Zobacz omówienie identyfikatorów miejsc.
  • types[] to tablica wskazująca typ zwróconego wyniku. Ta tablica zawiera zbiór co najmniej 1 tagu identyfikującego typ obiektu zwróconego w wyniku. Na przykład kod geograficzny „Chicago” zwraca „locality”, co oznacza, że „Chicago” to miasto, a także „political”, co oznacza, że jest to jednostka polityczna.

Trasy 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 etapu podróży nadrzędnej.

DirectionsRoute zawiera pojedynczy wynik z określonego miejsca początkowego i docelowego. Trasa może składać się z co najmniej 1 etapu (typu DirectionsLeg) w zależności od tego, czy określono punkty pośrednie. Trasa zawiera też informacje o prawach autorskich i ostrzeżenia, które oprócz informacji o trasie 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 odcinku trasy między 2 lokalizacjami na danej trasie. Dla każdego określonego punktu na trasie lub miejsca docelowego będzie dostępny oddzielny odcinek. (Trasa bez punktów pośrednich będzie zawierać dokładnie 1 element DirectionsLeg). Każdy odcinek składa się z serii elementów DirectionStep.
  • waypoint_order zawiera tablicę wskazującą kolejność punktów pośrednich na obliczonej trasie. Ta tablica może zawierać zmienioną kolejność, jeśli przekazano parametr DirectionsRequest optimizeWaypoints: true.
  • overview_path zawiera tablicę obiektów LatLng, które reprezentują przybliżoną (wygładzoną) ścieżkę wynikowych wskazówek dojazdu.
  • overview_polyline zawiera pojedynczy obiekt points, który przechowuje reprezentację trasy w postaci zakodowanej linii łamanej. Ta linia łamana jest przybliżoną (wygładzoną) ścieżką wynikowych wskazówek dojazdu.
  • bounds zawiera element LatLngBounds wskazujący granice linii łamanej wzdłuż danej trasy.
  • copyrights zawiera tekst dotyczący praw autorskich, który ma być wyświetlany dla tej trasy.
  • warnings[] zawiera tablicę ostrzeżeń, które mają być wyświetlane podczas pokazywania tych wskazówek dojazdu. Jeśli nie używasz podanego obiektu DirectionsRenderer, musisz samodzielnie obsługiwać i wyświetlać te ostrzeżenia.
  • fare zawiera łączną opłatę (czyli łączny koszt biletów) na tej trasie. Ta właściwość jest zwracana tylko w przypadku żądań dotyczących transportu publicznego i tylko w przypadku tras, na których informacje o opłatach są dostępne dla wszystkich odcinków transportu publicznego. Informacje te obejmują:
    • currency: kod waluty w formacie ISO 4217 wskazujący walutę, w której wyrażona jest kwota.
    • value: łączna kwota opłaty za przejazd w walucie określonej powyżej.

Etapy trasy

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

DirectionsLeg definiuje pojedynczy etap podróży od miejsca wyjazdu do miejsca docelowego na obliczonej trasie. W przypadku tras, które nie zawierają punktów pośrednich, trasa będzie składać się z jednego „etapu”, ale w przypadku tras, które definiują co najmniej 1 punkt pośredni, trasa będzie składać się z co najmniej 1 etapu, odpowiadającego konkretnym etapom podróży.

DirectionsLeg to literał obiektu z tymi polami:

  • steps[] zawiera tablicę obiektów DirectionsStep, które zawierają informacje o każdym osobnym etapie podróży.

  • distance wskazuje łączną odległość pokonaną na tym etapie jako obiekt Distance w tej postaci:

    • value – odległość w metrach,
    • text zawiera ciąg znaków reprezentujący odległość, która domyślnie jest wyświetlana w jednostkach używanych w miejscu początkowym. (np. mile będą używane w przypadku dowolnego miejsca wylotu w Stanach Zjednoczonych). Możesz zastąpić ten system jednostek, ustawiając parametr UnitSystem w pierwotnym zapytaniu. Pamiętaj, że niezależnie od używanego systemu jednostek pole distance.value zawsze zawiera wartość wyrażoną w metrach.

    Jeśli odległość jest nieznana, te pola mogą być niezdefiniowane.

  • duration wskazuje łączny czas trwania tego odcinka jako obiekt Duration w następującej postaci:

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

    Jeśli czas trwania jest nieznany, te pola mogą być niezdefiniowane.

  • duration_in_traffic wskazuje łączny czas trwania tego odcinka z uwzględnieniem aktualnych warunków na drodze. Wartość duration_in_traffic jest zwracana tylko wtedy, gdy są spełnione wszystkie te warunki:

    • Żądanie nie zawiera punktów pośrednich. Oznacza to, że nie obejmuje punktów pośrednich, w których stopover ma wartość true.
    • Prośba dotyczy konkretnie wskazówek dojazdu – parametr mode jest ustawiony na driving.
    • departureTime jest częścią pola drivingOptions w żądaniu.
    • Warunki na drodze są dostępne dla wybranej 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 tym odcinku. 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 określony jako obiekt Date w JavaScripcie.
    • text – czas określony jako ciąg znaków. Godzina jest wyświetlana w strefie czasowej przystanku transportu publicznego.
    • time_zone zawiera strefę czasową tej stacji. Wartość to nazwa strefy czasowej zdefiniowana w bazie danych stref czasowych IANA, np. „America/New_York”.
  • departure_time zawiera szacowany czas odjazdu na tym odcinku, określony jako obiekt Time. Parametr departure_time jest dostępny tylko w przypadku wskazówek dojazdu transportem publicznym.
  • start_location zawiera LatLng miejsca rozpoczęcia tego odcinka. Ponieważ usługa internetowa wskazówek dojazdu oblicza wskazówki dojazdu między lokalizacjami, korzystając z najbliższej opcji transportu (zwykle drogi) w punktach początkowym i końcowym, start_location może się różnić od podanego miejsca rozpoczęcia tego etapu, jeśli na przykład w pobliżu miejsca rozpoczęcia nie ma drogi.
  • end_location zawiera LatLng miejsca docelowego tego etapu. DirectionsService oblicza wskazówki dojazdu między lokalizacjami, korzystając z najbliższej opcji transportu (zwykle drogi) w punktach początkowym i końcowym. Dlatego end_location może się różnić od podanego miejsca docelowego tego etapu, jeśli np. w pobliżu miejsca docelowego nie ma drogi.
  • start_address zawiera zrozumiały dla człowieka adres (zwykle adres ulicy) początku tego odcinka.

    Te treści powinny być odczytywane w takiej postaci, w jakiej są. Nie analizuj sformatowanego adresu programowo.
  • end_address zawiera zrozumiały dla człowieka adres (zwykle adres ulicy) końca tego odcinka.

    Te treści powinny być odczytywane w takiej postaci, w jakiej są. Nie analizuj sformatowanego adresu programowo.

Kroki trasy

DirectionsStep to najbardziej podstawowa jednostka trasy, która zawiera pojedynczy krok opisujący konkretną instrukcję dotyczącą podróży. np. „Skręć w lewo na skrzyżowaniu z ulicą W. 4th St." Krok zawiera nie tylko instrukcję, ale też informacje o odległości i czasie trwania, które pokazują, jak ten krok odnosi się do następnego. Na przykład krok oznaczony jako „Zjedź na I-80 West” może zawierać czas trwania „37 mil” i „40 minut”, co oznacza, że następny krok jest oddalony o 37 mil lub 40 minut od tego kroku.

Gdy używasz usługi Directions do wyszukiwania wskazówek dojazdu transportem publicznym, tablica steps będzie zawierać dodatkowe informacje dotyczące transportu publicznego w postaci obiektu transit. Jeśli wskazówki dojazdu obejmują kilka środków transportu, szczegółowe wskazówki dotyczące pieszych lub samochodowych etapów trasy zostaną podane w tablicy steps[]. Na przykład krok dotyczący chodzenia będzie zawierał wskazówki dojazdu z lokalizacji początkowej i końcowej: „Idź do Innes Ave & Fitch St”. Ten krok będzie zawierać szczegółowe wskazówki dotyczące trasy pieszej w tablicy steps[], takie jak „Kieruj się na północny zachód”, „Skręć w lewo w Arelious Walker” i „Skręć w lewo w 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ą w tym kroku do następnego kroku jako obiekt Distance. (patrz opis w sekcji DirectionsLeg powyżej). Jeśli odległość jest nieznana, to pole może być niezdefiniowane.
  • duration zawiera szacowany czas potrzebny na wykonanie kroku do następnego kroku jako obiekt Duration. (patrz opis w sekcji DirectionsLeg powyżej). Jeśli czas trwania jest nieznany, to pole może być niezdefiniowane.
  • start_location zawiera zakodowane geograficznie LatLng punktu początkowego tego kroku.
  • end_location zawiera LatLng punktu końcowego tego kroku.
  • polyline zawiera pojedynczy obiekt points, który przechowuje reprezentację kroku w postaci zakodowanej linii łamanej. Ta linia łamana to przybliżona (wygładzona) ścieżka kroku.
  • steps[] – literał obiektu DirectionsStep, który zawiera szczegółowe wskazówki dojazdu samochodem lub pieszo w ramach wskazówek dojazdu transportem publicznym. Podetapy są dostępne tylko w przypadku wskazówek dojazdu transportem publicznym.
  • travel_mode zawiera TravelMode używany w tym kroku. Wskazówki dojazdu transportem publicznym mogą obejmować połączenie wskazówek dojazdu transportem publicznym i wskazówek dojazdu pieszo.
  • 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.

Informacje o transporcie publicznym

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

Szczegóły transportu publicznego

Obiekt TransitDetails udostępnia te właściwości:

  • arrival_stop zawiera obiekt TransitStop reprezentujący stację/przystanek przyjazdu z tymi właściwościami:
    • name – nazwa stacji transportu publicznego/przystanku. np. „Plac Zamkowy”.
    • location – lokalizacja stacji lub przystanku transportu publicznego, reprezentowana jako LatLng.
  • departure_stop zawiera obiekt TransitStop reprezentujący stację/przystanek początkowy.
  • arrival_time zawiera czas przybycia określony jako obiekt Time z 3 właściwościami:
    • value czas określony jako obiekt Date w JavaScripcie.
    • text – czas określony jako ciąg znaków. Godzina jest wyświetlana w strefie czasowej przystanku transportu publicznego.
    • time_zone zawiera strefę czasową tej stacji. Wartość to nazwa strefy czasowej zdefiniowana w bazie danych stref czasowych IANA, np. „America/New_York”.
  • departure_time zawiera czas odjazdu określony jako obiekt Time.
  • headsign określa kierunek jazdy na tej linii, zgodnie z oznaczeniem na pojeździe lub na przystanku odjazdu. Często będzie to stacja końcowa.
  • headway – jeśli jest dostępna, określa oczekiwaną liczbę sekund między odjazdami z tego samego przystanku w tym czasie. Jeśli na przykład wartość headway wynosi 600, a autobus ucieknie, czas oczekiwania wyniesie 10 minut.
  • line zawiera literał obiektu TransitLine, który zawiera informacje o linii transportu publicznego używanej na tym etapie. TransitLine zawiera nazwę i operatora linii oraz inne właściwości opisane w dokumentacji referencyjnej TransitLine.
  • num_stops zawiera liczbę przystanków w tym kroku. Obejmuje przystanek docelowy, ale nie przystanek początkowy. Jeśli na przykład wskazówki dojazdu obejmują wyjazd z przystanku A, przejazd przez przystanki B i C oraz przyjazd na przystanek D, funkcja num_stops zwróci wartość 3.

Linia transportu publicznego

Obiekt TransitLine udostępnia te właściwości:

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

    Uwaga: jeśli wskazówki dojazdu transportem publicznym renderujesz ręcznie, a nie za pomocą obiektu DirectionsRenderer, musisz wyświetlać nazwy i adresy URL przewoźników obsługujących wyniki podróży.

  • url zawiera adres URL tej linii transportu publicznego podany przez przewoźnika.
  • icon zawiera adres URL ikony powiązanej z tą linią. W większości miast będą używane ogólne ikony, które różnią się w zależności od typu pojazdu. Niektóre linie transportu publicznego, takie jak metro w Nowym Jorku, mają ikony charakterystyczne dla danej linii.
  • color zawiera kolor powszechnie używany w oznakowaniu tego środka transportu. Kolor będzie określony jako ciąg szesnastkowy, np. #FF0033.
  • text_color zawiera kolor tekstu powszechnie używanego w oznakowaniu tej linii. Kolor zostanie określony jako ciąg szesnastkowy.
  • vehicle zawiera obiekt Vehicle, który obejmuje te właściwości:
    • name zawiera nazwę pojazdu w tym wierszu. np. „Metro”.
    • type zawiera typ pojazdu używanego na tej linii. Pełną listę obsługiwanych wartości znajdziesz w dokumentacji dotyczącej typu pojazdu.
    • icon zawiera adres URL ikony powszechnie kojarzonej z tym typem pojazdu.
    • local_icon zawiera adres URL ikony powiązanej z tym typem pojazdu na podstawie lokalnych znaków transportowych.

Typ pojazdu

Obiekt VehicleType udostępnia te właściwości:

Wartość Definicja
VehicleType.RAIL Kolej.
VehicleType.METRO_RAIL Kolej miejska.
VehicleType.SUBWAY Podziemna kolej miejska.
VehicleType.TRAM Naziemna kolej miejska.
VehicleType.MONORAIL Kolej jednoszynowa.
VehicleType.HEAVY_RAIL Kolej naziemna.
VehicleType.COMMUTER_TRAIN Kolej podmiejska.
VehicleType.HIGH_SPEED_TRAIN Pociąg szybkobieżny.
VehicleType.BUS Autobus.
VehicleType.INTERCITY_BUS Autobus krajowy.
VehicleType.TROLLEYBUS Trolejbus.
VehicleType.SHARE_TAXI Taksówka zbiorowa to rodzaj autobusu, który może wysadzać i zabierać pasażerów w dowolnym miejscu na trasie.
VehicleType.FERRY Prom.
VehicleType.CABLE_CAR Pojazd poruszający się po kablu, zwykle na ziemi. Kolejki linowe mogą być typu VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Kolejka linowa.
VehicleType.FUNICULAR Pojazd, który jest wciągany na strome zbocze za pomocą liny. Kolejka linowo-terenowa składa się zwykle z 2 wagoników, które działają jak przeciwwaga dla siebie nawzajem.
VehicleType.OTHER Wszystkie inne pojazdy będą zwracać ten typ.

Sprawdzanie DirectionsResults

Podczas analizowania odpowiedzi dotyczącej wskazówek dojazdu można sprawdzać i używać komponentów DirectionsResults: DirectionsRoute, DirectionsLeg, DirectionsStep i TransitDetails.

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

Poniższy przykład przedstawia trasę pieszą do niektórych atrakcji turystycznych w Nowym Jorku. Sprawdzamy DirectionsStep trasy, aby dodać znaczniki dla każdego kroku, i dołączamy informacje do InfoWindow z tekstem instrukcji dla tego kroku.

Uwaga: ponieważ obliczamy trasę pieszą, wyświetlamy też użytkownikowi 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 w trasach

Jak wspomniano w opisie DirectionsRequest, podczas obliczania tras za pomocą usługi wskazówek dojazdu dla pieszych, rowerzystów lub kierowców możesz też określić punkty orientacyjne (typu DirectionsWaypoint). Punkty na trasie nie są dostępne w przypadku wskazówek dojazdu transportem publicznym. Punkty pośrednie umożliwiają obliczanie tras przez dodatkowe lokalizacje. W takim przypadku zwrócona trasa przebiega przez podane punkty pośrednie.

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

  • location (wymagany) określa adres punktu pośredniego.
  • stopover (opcjonalny) wskazuje, czy ten punkt pośredni jest rzeczywistym przystankiem na trasie (true), czy tylko preferencją dotyczącą trasy przez wskazaną lokalizację (false). Przystanki są domyślnie ustawione na true.

Domyślnie usługa Directions oblicza trasę przez podane punkty pośrednie w podanej kolejności. Opcjonalnie możesz przekazać optimizeWaypoints: true w parametrze DirectionsRequest, aby umożliwić usłudze Directions optymalizację podanej trasy przez zmianę kolejności punktów na bardziej efektywną. (Ta optymalizacja jest zastosowaniem problemu komiwojażera). Czas podróży jest głównym czynnikiem, który jest optymalizowany, ale przy podejmowaniu decyzji o tym, która trasa jest najbardziej efektywna, mogą być brane pod uwagę inne czynniki, takie jak odległość, liczba zakrętów i wiele innych. Aby usługa Directions mogła zoptymalizować trasę, wszystkie punkty pośrednie muszą być przystankami.

Jeśli poprosisz usługę Directions o zoptymalizowanie kolejności punktów pośrednich, ich kolejność zostanie zwrócona w polu waypoint_order w obiekcie DirectionsResult.

W tym przykładzie obliczamy trasy przez Stany Zjednoczone, używając różnych punktów początkowych, końcowych i pośrednich. (Aby wybrać kilka punktów, naciśnij Ctrl i kliknij elementy na liście). Zwróć uwagę, że sprawdzamy routes.start_address i routes.end_address, aby uzyskać tekst 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;

Limity i ograniczenia dotyczące punktów na trasie

Obowiązują te limity wykorzystania i ograniczenia:

  • Maksymalna liczba punktów pośrednich dozwolona podczas korzystania z usługi wskazówek dojazdu w Maps JavaScript API to 25, nie licząc punktu początkowego i docelowego. Limity są takie same jak w przypadku usługi internetowej Directions API (starsza wersja).
  • W przypadku usługi internetowej Directions API (starsza wersja) klienci mogą używać 25 punktów pośrednich oraz punktu początkowego i docelowego.
  • Klienci korzystający z abonamentu Premium Google Maps Platform mogą dodać 25 punktów pośrednich oraz punkt początkowy i docelowy.
  • Punkty pośrednie nie są obsługiwane w przypadku wskazówek dojazdu transportem publicznym.

Przeciąganie trasy

Użytkownicy mogą dynamicznie modyfikować wskazówki dojazdu rowerem, pieszo lub samochodem wyświetlane za pomocą elementu DirectionsRenderer, jeśli można je przeciągać. Pozwala to użytkownikowi wybierać i zmieniać trasy przez klikanie i przeciąganie wynikowych ścieżek na mapie. Możesz określić, czy wyświetlacz modułu renderującego umożliwia przeciąganie wskazówek dojazdu, ustawiając właściwość draggable na true. Wskazówek dojazdu transportem publicznym nie można przeciągać.

Jeśli wskazówki dojazdu można przeciągać, użytkownik może wybrać dowolny punkt na ścieżce (lub punkt pośredni) wyrenderowanego wyniku i przenieść wskazany komponent do nowej lokalizacji. DirectionsRenderer zostanie dynamicznie zaktualizowany, aby wyświetlać zmodyfikowaną ścieżkę. Po zwolnieniu przycisku do mapy zostanie dodany punkt pośredni (oznaczony małym białym znacznikiem). Zaznaczenie i przeniesienie segmentu ścieżki spowoduje zmianę tego odcinka trasy, a zaznaczenie i przeniesienie znacznika punktu pośredniego (w tym punktów początkowych i końcowych) spowoduje zmianę odcinków trasy przechodzących przez ten punkt pośredni.

Ponieważ wskazówki dojazdu z możliwością przeciągania są modyfikowane i renderowane po stronie klienta, możesz monitorować i obsługiwać zdarzenie directions_changed w DirectionsRenderer, aby otrzymywać powiadomienia, gdy użytkownik zmodyfikuje wyświetlane wskazówki dojazdu.

Poniższy kod pokazuje podróż z Perth na zachodnim wybrzeżu Australii do Sydney na wschodnim wybrzeżu. Kod monitoruje zdarzenie directions_changed, aby aktualizować łączną 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