Usługa Trasy

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

Przegląd

Możesz obliczać wskazówki dojazdu (różnymi środkami transportu) za pomocą obiektu DirectionsService. Ten obiekt komunikuje się z usługą wskazówek dojazdu w interfejsie API Map Google, która otrzymuje prośby o wskazówki i zwraca optymalną trasę. Głównym czynnikiem optymalizacji jest czas podróży, ale mogą być brane pod uwagę także inne czynniki, takie jak odległość, liczba zakrętów i wiele innych. Możesz samodzielnie obsługiwać wyniki dotyczące wskazówek dojazdu lub użyć obiektu DirectionsRenderer, aby je renderować.

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

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

Pierwsze kroki

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

Ceny i zasady

Ceny

Więcej informacji o cenach i zasadach korzystania z usługi wyznaczania trasy w JavaScript znajdziesz w sekcji Korzystanie i płatności w przypadku interfejsu Directions API (starsza wersja).

Zasady

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

Zapytania o trasę

Dostęp do usługi Kierunki jest asynchroniczny, ponieważ interfejs Google Maps API musi wywołać zewnętrzny serwer. Dlatego musisz przekazać metodę wywołania zwrotnego, która zostanie wykonana po zakończeniu żądania. Ta metoda wywołania zwrotnego powinna przetwarzać wyniki. Pamiętaj, że usługa Wskazówki dojazdu może zwrócić więcej niż 1 możliwy plan podróży w postaci tablicy oddzielnych routes[].

Aby używać wskazówek w interfejsie Maps JavaScript API, utwórz obiekt typu DirectionsService i wywołaj DirectionsService.route(), aby zainicjować żądanie do usługi Wskazówki, przekazując mu literał obiektu DirectionsRequest zawierający terminy 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 znajdziesz wyjaśnienia tych pól:

  • Parametr origin (wymagany) określa lokalizację początkową, z której mają być obliczane wskazówki dojazdu. Tę wartość można podać 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 LatLnglokalizację. 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ć obliczone wskazówki dojazdu. Opcje są takie same jak w przypadku opisanego powyżej pola origin.
  • travelMode (wymagany) określa, jakiego środka transportu użyć podczas obliczania trasy. Prawidłowe wartości podano w sekcji Rodzaje transportu poniżej.
  • transitOptions (opcjonalny) określa wartości, które mają zastosowanie tylko w przypadku żądań, w których travelMode ma wartość TRANSIT. Prawidłowe wartości opisano w sekcji Opcje transportu poniżej.
  • drivingOptions (opcjonalny) określa wartości, które mają zastosowanie tylko w przypadku żądań, w których travelMode ma wartość DRIVING. Prawidłowe wartości opisano 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 są podane w sekcji Systemy miar poniżej.

  • waypoints[] (opcjonalnie) określa tablicę obiektów 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 na trasach poniżej).

  • optimizeWaypoints (opcjonalny) oznacza, że trasa z użyciem podanego parametru waypoints może zostać zoptymalizowana przez zmianę kolejności punktów pośrednich na bardziej efektywną. Jeśli true, usługa Kierunki zwróci zmienioną kolejność waypoints w polu waypoint_order. Więcej informacji znajdziesz w sekcji Używanie punktów pośrednich na trasach poniżej.
  • provideRouteAlternatives (opcjonalny) po ustawieniu na true określa, że usługa Kierunki może podać w odpowiedzi więcej niż jedną trasę alternatywną. Pamiętaj, że podanie alternatywnych tras może wydłużyć czas odpowiedzi serwera. Ta opcja jest dostępna tylko w przypadku próśb bez pośrednich punktów trasy.
  • avoidFerries (opcjonalny) gdy jest ustawiony na true, oznacza, że obliczone trasy powinny w miarę możliwości omijać promy.
  • avoidHighways (opcjonalny) gdy jest ustawiony na true, oznacza, ż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 omijać drogi płatne.
  • region (opcjonalny) określa kod regionu w postaci dwuznakowej wartości ccTLD („domena najwyższego poziomu”). (Więcej informacji znajdziesz w sekcji Region Biasing poniżej).

Poniżej znajdziesz 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
}

Tryby podróży

Obliczając wskazówki dojazdu, musisz określić, jakiego środka transportu chcesz użyć. Obecnie obsługiwane są te środki transportu:

  • DRIVING (Domyślne) wskazuje standardowe wskazówki dojazdu z wykorzystaniem sieci dróg.
  • BICYCLING prosi o wskazówki dojazdu rowerem po ścieżkach rowerowych i ulicach, które preferuje.
  • TRANSIT prosi o wskazówki dojazdu transportem publicznym.
  • WALKING prosi o wskazówki dojazdu pieszo ścieżkami dla pieszych i chodnikami.

Aby sprawdzić, w jakim stopniu dany kraj obsługuje wskazówki dojazdu, zapoznaj się ze szczegółami dotyczącymi zasięgu Google Maps Platform. Jeśli poprosisz o wskazówki dojazdu w regionie, w którym ten typ wskazówek nie jest dostępny, w odpowiedzi otrzymasz DirectionsStatus="ZERO_RESULTS".

Uwaga: wskazówki dojścia pieszo mogą nie obejmować wyraźnych ścieżek dla pieszych, dlatego w DirectionsResult będą wyświetlać ostrzeżenia. Te ostrzeżenia muszą być zawsze wyświetlane użytkownikowi. Jeśli nie używasz domyślnego parametru DirectionsRenderer, odpowiadasz za wyświetlanie ostrzeżeń.

Opcje transportu publicznego

Dostępne opcje w przypadku 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 routingu dotyczące 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
}

Poniżej znajdziesz wyjaśnienia tych pól:

  • arrivalTime (opcjonalny) określa żądany czas przyjazdu jako obiekt Date. Jeśli podasz czas przyjazdu, czas odjazdu zostanie zignorowany.
  • departureTime (opcjonalny) określa żądany czas odjazdu jako obiekt Date. Element departureTime zostanie zignorowany, jeśli określono element arrivalTime. Jeśli nie podasz wartości dla departureTime ani arrivalTime, domyślnie zostanie przyjęta bieżąca data i godzina.
  • modes[] (opcjonalny) to tablica zawierająca co najmniej 1 TransitMode literał obiektu. To pole może być uwzględnione tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Każdy element TransitMode określa preferowany środek transportu. Dozwolone wartości:
    • BUS oznacza, że obliczona trasa powinna uwzględniać przejazd autobusem.
    • RAIL oznacza, że obliczona trasa powinna uwzględniać przede wszystkim podróż pociągiem, tramwajem, koleją miejską i metrem.
    • SUBWAY oznacza, że obliczona trasa powinna uwzględniać podróż metrem.
    • TRAIN oznacza, że obliczona trasa powinna preferować podróż pociągiem.
    • TRAM oznacza, że obliczona trasa powinna uwzględniać podróż tramwajem lub koleją miejską.
  • routingPreference (opcjonalny) określa preferencje dotyczące tras transportu publicznego. Dzięki tej opcji możesz zmienić preferencje dotyczące zwracanych opcji, 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 wartości:
    • FEWER_TRANSFERS oznacza, że obliczona trasa powinna uwzględniać ograniczoną liczbę przesiadek.
    • LESS_WALKING oznacza, że obliczona trasa powinna uwzględniać ograniczone ilości chodzenia.

Poniżej znajduje się przykład DirectionsRequest według transportu publicznego:

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

Obiekt DrivingOptions zawiera te pola:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Poniżej znajdziesz wyjaśnienia tych pól:

  • departureTime (wymagany, aby literał obiektu drivingOptions był prawidłowy) określa żądany czas odjazdu jako obiekt Date. Wartość musi być ustawiona na bieżącą godzinę lub na godzinę w przyszłości. Nie może przypadać w przeszłości. (Interfejs API konwertuje wszystkie daty na UTC, aby zapewnić spójną obsługę w różnych strefach czasowych). Jeśli w przypadku klientów korzystających z abonamentu premium na Google Maps Platform w żądaniu uwzględnisz parametr departureTime, interfejs API zwróci najlepszą trasę z uwzględnieniem przewidywanych warunków ruchu w danym czasie oraz przewidywany czas przejazdu w ruchu (duration_in_traffic) w odpowiedzi. Jeśli nie określisz godziny odjazdu (czyli jeśli żądanie nie zawiera parametru drivingOptions), zwrócona trasa będzie ogólnie dobrą trasą, która nie uwzględnia warunków drogowych.
  • trafficModel (opcjonalny) określa założenia, które należy uwzględnić podczas obliczania czasu w ruchu. To ustawienie wpływa na wartość zwracaną w polu duration_in_traffic w odpowiedzi, która zawiera przewidywany czas przejazdu w warunkach ruchu na podstawie średnich wartości historycznych. Domyślna wartość to bestguess. Dozwolone wartości:
    • bestguess (domyślnie) oznacza, że zwrócona wartośćduration_in_traffic powinna być najlepszym oszacowaniem czasu podróżyduration_in_traffic na podstawie historycznych i bieżących informacji o natężeniu ruchu. Im bliżej jest departureTime do teraźniejszości, tym większe znaczenie ma ruch na żywo.
    • pessimistic oznacza, że zwrócony czas duration_in_traffic powinien być dłuższy niż rzeczywisty czas podróży duration_in_traffic w większości dni, chociaż w niektóre dni, gdy warunki drogowe są szczególnie złe, może być dłuższy.
    • optimistic oznacza, że zwrócony 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, podróż może trwać krócej.

Poniżej znajdziesz przykładowy DirectionsRequest dotyczący wskazówek 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 jednostek

Domyślnie trasa jest obliczana i wyświetlana w układzie jednostek kraju lub regionu, z którego pochodzi punkt początkowy. (Uwaga: w przypadku miejsc docelowych wyrażonych za pomocą współrzędnych geograficznych zamiast adresów zawsze domyślnie używane są jednostki metryczne). Na przykład trasa z „Chicago, IL” do „Toronto, ONT” będzie wyświetlać wyniki w milach, a trasa w przeciwnym kierunku – w kilometrach. Możesz zastąpić ten system jednostek, ustawiając go w żądaniu za pomocą jednej z tych wartości UnitSystem:

  • UnitSystem.METRIC określa użycie systemu metrycznego. Odległości są podawane w kilometrach.
  • UnitSystem.IMPERIAL określa użycie systemu imperialnego (angielskiego). Odległości są podawane 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 podawane w metrach.

Preferowanie regionu w przypadku wskazówek dojazdu

Usługa Kierunki w interfejsie Google Maps API zwraca wyniki adresów, na które ma wpływ domena (region lub kraj), z której załadowano plik bootstrap JavaScript. (Ponieważ większość użytkowników wczytuje https://maps.googleapis.com/, ustawia to domyślną domenę na Stany Zjednoczone). Jeśli wczytasz bootstrap z innej obsługiwanej domeny, wyniki będą zależeć od tej domeny. Na przykład wyszukiwanie hasła „San Francisco” może zwracać różne wyniki w aplikacjach wczytujących https://maps.googleapis.com/ (Stany Zjednoczone) niż w aplikacjach wczytujących http://maps.google.es/ (Hiszpania).

Możesz też skonfigurować usługę Kierunki tak, aby zwracała wyniki z określonego regionu, używając parametru region. Ten parametr przyjmuje kod regionu określony jako 2-znakowy (nieliczbowy) podtag regionu Unicode. W większości przypadków te tagi są bezpośrednio mapowane na 2-znakowe 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” zamiast „Great Britain”).

Podczas korzystania z parametru region:

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

Preferowanie regionu jest obsługiwane tylko w krajach i regionach, w których dostępne są wskazówki dojazdu. Szczegółowe informacje o zasięgu międzynarodowym interfejsu Directions API (starszego) znajdziesz w szczegółach zasięgu Google Maps Platform.

Wyświetlanie wskazówek dojazdu

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

Stan zapytania o wskazówki dojazdu

DirectionsStatus może zwracać te wartości:

  • OK oznacza, że odpowiedź zawiera prawidłowy DirectionsResult.
  • NOT_FOUND oznacza, że co najmniej jednej z lokalizacji określonych w punkcie początkowym, docelowym lub pośrednich żądania nie można było przekształcić na współrzędne geograficzne.
  • ZERO_RESULTS oznacza, że nie udało się znaleźć trasy między miejscem początkowym a docelowym.
  • MAX_WAYPOINTS_EXCEEDED oznacza, że w DirectionsRequest podano zbyt wiele pól DirectionsWaypoint. Więcej informacji znajdziesz w sekcji poniżej dotyczącej limitów punktów pośrednich.
  • MAX_ROUTE_LENGTH_EXCEEDED oznacza, ż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 wskazówki. Spróbuj zmniejszyć liczbę punktów, zakrętów lub instrukcji.
  • INVALID_REQUEST oznacza, że podany DirectionsRequest jest nieprawidłowy. Najczęstsze przyczyny tego kodu błędu to żądania, w których brakuje miejsca docelowego lub źródła, albo żądania dotyczące transportu publicznego, które zawierają punkty pośrednie.
  • OVER_QUERY_LIMIT oznacza, że strona wysłała zbyt wiele żądań w dozwolonym okresie.
  • REQUEST_DENIED oznacza, że strona internetowa nie może korzystać z usługi wyznaczania trasy.
  • UNKNOWN_ERROR oznacza, że nie udało się przetworzyć żądania dotyczącego wskazówek dojazdu z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.

Przed przetworzeniem wyniku sprawdź, czy zapytanie o wskazówki dojazdu zwróciło prawidłowe wyniki.

Wyświetlanie obiektu DirectionsResult

DirectionsResult zawiera wynik zapytania o wskazówki dojazdu, który możesz przetworzyć samodzielnie lub przekazać do obiektu DirectionsRenderer, który może automatycznie wyświetlić wynik 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 programie renderującym, aby powiązać go z przekazaną mapą.
  3. Wywołaj funkcję setDirections() w programie renderującym, przekazując jej wartość DirectionsResult zgodnie z opisem powyżej. Renderujący jest MVCObject, więc automatycznie wykrywa wszelkie zmiany w swoich właściwościach i aktualizuje mapę, gdy zmienią się powiązane z nim wskazówki dojazdu.

W tym przykładzie obliczane są wskazówki dojazdu między 2 lokalizacjami na trasie Route 66. Początek i miejsce docelowe są ustawiane przez podane wartości "start" i "end" na listach. Klasa DirectionsRenderer odpowiada za wyświetlanie linii łamanej między wskazanymi lokalizacjami oraz umieszczanie markerów w miejscu początkowym, docelowym i wszystkich punktach pośrednich (w odpowiednich przypadkach).

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 dzielnicy 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

DirectionsRenderer nie tylko obsługuje wyświetlanie polilinii i powiązanych z nią znaczników, ale też może obsługiwać tekstowe wyświetlanie wskazówek dojazdu w postaci serii kroków. Aby to zrobić, wywołaj funkcję setPanel() na urządzeniu DirectionsRenderer, przekazując jej element <div>, w którym mają być wyświetlane te informacje. Dzięki temu wyświetlisz też odpowiednie informacje o prawach autorskich i ostrzeżenia, które mogą być powiązane z wynikiem.

Wskazówki tekstowe będą podawane w języku preferowanym w ustawieniach przeglądarki lub w języku określonym podczas wczytywania kodu JavaScript interfejsu API za pomocą parametru language. (Więcej informacji znajdziesz w sekcji Lokalizacja). W przypadku wskazówek dojazdu transportem publicznym czas będzie wyświetlany w strefie czasowej danego przystanku.

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

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 wyślesz do DirectionsService żądanie dotyczące wskazówek dojazdu, otrzymasz odpowiedź składającą się z kodu stanu i wyniku, 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 punktu początkowego, 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 DirectionsRequest. Zwykle w odpowiedzi na żądanie zwracana jest tylko jedna trasa, chyba że w polu provideRouteAlternatives żądania ustawiono wartość true. W takim przypadku może zostać zwróconych kilka tras.

Uwaga: właściwość via_waypoint jest wycofywana w przypadku tras 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 i nowszych możesz nadal wdrażać trasy z możliwością przeciągania za pomocą usługi Kierunki, wyłączając przeciąganie tras alternatywnych. Przeciągać można tylko główną trasę. Użytkownicy mogą przeciągnąć główną trasę, aż będzie pasować do trasy alternatywnej.

Geokodowane punkty pośrednie w usłudze Kierunki

DirectionsGeocodedWaypoint zawiera szczegółowe informacje o geokodowaniu punktu początkowego, miejsca docelowego i punktów pośrednich.

DirectionsGeocodedWaypoint to literał obiektu z tymi polami:

  • geocoder_status oznacza 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ł prawidłowo przeanalizowany i zwrócono co najmniej 1 geokod.
    • "ZERO_RESULTS" oznacza, że geokodowanie 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 address.

  • partial_match oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, ale udało mu się dopasować część żądanego adresu. Sprawdź, czy w pierwotnej prośbie nie ma błędów pisowni lub niepełnego adresu.

    Częściowe dopasowania najczęściej występują w przypadku adresów ulic, które nie istnieją w miejscowości przekazywanej 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 do Henry Street, jak i do Henrietta Street. Pamiętaj, że jeśli żądanie zawiera błędnie napisaną część adresu, usługa geokodowania może zaproponować alternatywny adres. Sugerowane odpowiedzi wywołane w ten sposób będą też oznaczone jako częściowo pasujące.

  • place_idjest unikalnym identyfikatorem 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 itp. Zapoznaj się z omówieniem identyfikatorów miejsc.
  • types[] to tablica wskazująca typ zwróconego wyniku. Ta tablica zawiera zestaw tagów (co najmniej 1) identyfikujących typ funkcji zwróconej 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 wskazówek dojazdu

Uwaga: starszy obiekt DirectionsTrip został zmieniony 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 odjazdu i miejsca docelowego. Ta trasa może składać się z co najmniej 1 odcinka (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 muszą być wyświetlane użytkownikowi oprócz informacji o wyznaczaniu trasy.

DirectionsRoute to literał obiektu z tymi polami:

  • legs[] zawiera tablicę obiektów DirectionsLeg, z których każdy zawiera informacje o etapie trasy między 2 lokalizacjami na danej trasie. Dla każdego określonego punktu pośredniego 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 wartość DirectionsRequestoptimizeWaypoints: true.
  • overview_path zawiera tablicę obiektów LatLng, które reprezentują przybliżoną (wygładzoną) ścieżkę wynikowych wskazówek.
  • overview_polyline zawiera pojedynczy obiekt points, który zawiera zakodowaną linię łamaną reprezentującą trasę. Ta linia łamana to przybliżona (wygładzona) ścieżka wynikowych wskazówek.
  • bounds zawiera LatLngBounds, który wskazuje granice linii łamanej na danej trasie.
  • copyrights zawiera tekst dotyczący praw autorskich, który ma być wyświetlany w przypadku tej trasy.
  • warnings[] zawiera tablicę ostrzeżeń, które mają być wyświetlane podczas pokazywania tych wskazówek. Jeśli nie używasz podanego obiektu DirectionsRenderer, musisz samodzielnie obsługiwać i wyświetlać te ostrzeżenia.
  • fare zawiera całkowitą cenę (czyli łączne koszty biletu) na tej trasie. Ta właściwość jest zwracana tylko w przypadku zapytań dotyczących transportu publicznego i tylko w przypadku tras, dla których dostępne są informacje o opłatach za wszystkie etapy podróży transportem publicznym. Informacje obejmują:
    • currency: kod waluty w formacie ISO 4217 wskazujący walutę, w której wyrażona jest kwota.
    • value: łączna kwota opłaty w walucie określonej powyżej.

Directions Legs

Uwaga: starszy obiekt DirectionsRoute został zmieniony na DirectionsLeg.

Obiekt DirectionsLeg określa pojedynczy etap podróży z 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 „odcinka”, ale w przypadku tras, które definiują co najmniej 1 punkt pośredni, trasa będzie składać się z co najmniej 1 odcinka odpowiadającego poszczególnym odcinkom podróży.

DirectionsLeg to literał obiektu z tymi polami:

  • steps[] zawiera tablicę obiektów DirectionsStep z informacjami o każdym etapie podróży.

  • distance – łączna odległość pokonana 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 pochodzenia. (np. mile będą używane w przypadku dowolnego miejsca początkowego w Stanach Zjednoczonych). Możesz zastąpić ten system jednostek, ustawiając w oryginalnym zapytaniu UnitSystem. 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 w postaci obiektu Duration w tym formacie:

    • value oznacza 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 oznacza łączny czas trwania tego etapu, z uwzględnieniem aktualnych warunków drogowych. Wartość duration_in_traffic jest zwracana tylko wtedy, gdy spełnione są wszystkie te warunki:

    • Żądanie nie zawiera punktów pośrednich. Oznacza to, że nie obejmuje punktów pośrednich, w których stopover jest równe true.
    • Żądanie dotyczy konkretnie wskazówek dojazdu – parametr mode ma wartość driving.
    • departureTime jest częścią pola drivingOptions w żądaniu.
    • Informacje o warunkach na drodze są dostępne dla wybranej trasy.

    duration_in_traffic zawiera te pola:

    • value oznacza czas trwania w sekundach.
    • text zawiera czytelną dla człowieka reprezentację czasu trwania.
  • arrival_time zawiera szacowany czas przybycia 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 JavaScript.Date
    • text czas określony jako ciąg znaków. Godzina jest wyświetlana w strefie czasowej przystanku.
    • 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 odlotu na tym odcinku, określony jako obiekt Time. departure_time jest dostępna tylko w przypadku wskazówek dojazdu transportem publicznym.
  • start_location zawiera LatLng pochodzenia tego odcinka. Usługa internetowa Kierunki oblicza wskazówki dojazdu między lokalizacjami, korzystając z najbliższej opcji transportu (zwykle drogi) w punktach początkowym i końcowym, więc start_location może się różnić od podanego punktu początkowego tego etapu, jeśli np. w pobliżu punktu początkowego nie ma drogi.
  • end_location zawiera LatLng miejsca docelowego tego odcinka. Ponieważ usługa DirectionsService oblicza wskazówki dojazdu między lokalizacjamiend_location, korzystając z najbliższej opcji transportu (zwykle drogi) w punktach początkowym i końcowym, może się ona różnić od podanego miejsca docelowego tego etapu, jeśli np. w pobliżu miejsca docelowego nie ma drogi.
  • start_address zawiera adres czytelny dla człowieka (zwykle adres ulicy) początku tego odcinka.

    Te treści należy odczytywać w takiej postaci, w jakiej są. Nie analizuj programowo sformatowanego adresu.
  • end_address zawiera adres czytelny dla człowieka (zwykle adres ulicy) na końcu tego odcinka.

    Te treści należy odczytywać w takiej postaci, w jakiej są. Nie analizuj programowo sformatowanego adresu.

Kroki trasy

DirectionsStep to najmniejsza jednostka trasy wskazówek dojazdu. Zawiera pojedynczy krok opisujący konkretną instrukcję dotyczącą podróży. Na przykład: „Skręć w lewo na W. 4th St." Krok nie tylko zawiera 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 „Wjedź 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.

Gdy używasz usługi Wskazówki dojazdu do wyszukiwania wskazówek dojazdu transportem publicznym, tablica steps zawiera dodatkowe informacje dotyczące transportu publicznego w postaci obiektu transit. Jeśli wskazówki obejmują różne środki transportu, szczegółowe instrukcje dotyczące kroków związanych z pieszym lub samochodowym pokonywaniem trasy zostaną podane w steps[]tablicy. Na przykład krok dotyczący przejścia pieszego będzie zawierać wskazówki dotyczące lokalizacji początkowej i końcowej: „Idź do Innes Ave & Fitch St”. Ten krok będzie zawierać szczegółowe wskazówki dojazdu pieszo dla tej trasy w tablicy steps[], np. „Idź na północny zachód”, „Skręć w lewo w ulicę Arelious Walker” i „Skręć w lewo w ulicę 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 DirectionsLeg powyżej). To pole może być niezdefiniowane, jeśli odległość jest nieznana.
  • duration zawiera szacunkowy czas potrzebny na wykonanie kroku do następnego kroku w postaci obiektu Duration. (patrz opis w DirectionsLeg powyżej). To pole może być niezdefiniowane, jeśli czas trwania jest nieznany.
  • start_location zawiera geokodowanyLatLng punkt początkowy tego kroku.
  • end_location zawiera LatLng punktu końcowego tego kroku.
  • polyline zawiera pojedynczy obiekt points, który zawiera zakodowaną polilinię reprezentującą krok. Ta linia łamana to przybliżona (wygładzona) ścieżka kroku.
  • steps[] – literał obiektu DirectionsStep, który zawiera szczegółowe wskazówki dotyczące kroków podczas pieszej lub samochodowej części trasy w przypadku wskazówek dotyczących transportu publicznego. Podetapy są dostępne tylko w przypadku wskazówek dotyczących transportu publicznego.
  • travel_mode zawiera TravelMode użyte w tym kroku. Trasa transportu publicznego może obejmować kombinację trasy pieszej i trasy transportu publicznego.
  • 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 dotyczące transportu publicznego

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 za pomocą obiektu TransitDetails, który jest zwracany jako właściwość obiektu DirectionsStep. Z obiektu TransitDetails możesz uzyskać dostęp do dodatkowych informacji o obiektach TransitStop, TransitLine, TransitAgency i VehicleType w sposób opisany poniżej.

Szczegóły transportu publicznego

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

  • arrival_stop zawiera obiekt TransitStop reprezentujący stację/przystanek docelowy z tymi właściwościami:
    • name nazwa stacji lub przystanku; np. „Union Square”.
    • location lokalizację stacji lub przystanku transportu publicznego, która jest reprezentowana przez LatLng.
  • departure_stop zawiera obiekt TransitStop reprezentujący stację lub przystanek odjazdu.
  • arrival_time zawiera czas przyjazdu określony jako obiekt z 3 właściwościami:
      Time
    • value czas określony jako obiekt JavaScript.Date
    • text czas określony jako ciąg znaków. Godzina jest wyświetlana w strefie czasowej przystanku.
    • 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 godzinę odlotu określoną jako obiekt Time.
  • headsign określa kierunek, w którym należy się poruszać na tej linii, zgodnie z oznaczeniem na pojeździe lub na przystanku początkowym. Często jest to stacja końcowa.
  • headway – jeśli jest dostępna, określa oczekiwaną liczbę sekund między odjazdami z tego samego przystanku o tej porze. Jeśli na przykład wartość headway wynosi 600, w przypadku spóźnienia się na autobus musisz się liczyć z 10-minutowym oczekiwaniem.
  • line zawiera literał obiektu TransitLine, który zawiera informacje o linii transportu publicznego użytej w tym kroku. Element 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 wiersza, np. „2” lub „M14”.
  • agencies to tablica zawierająca jeden obiekt TransitAgency. Obiekt TransitAgency zawiera informacje o operatorze tej linii, w tym te właściwości:
    • name zawiera nazwę agencji transportu publicznego.
    • phone zawiera numer telefonu przewoźnika.
    • url zawiera adres URL przewoźnika.

    Uwaga: 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.

  • url zawiera adres URL tej linii transportu publicznego podany przez przewoźnika.
  • icon zawiera adres URL ikony powiązanej z tym wierszem. 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, np. nowojorskie metro, mają ikony charakterystyczne dla danej linii.
  • color zawiera kolor powszechnie używany w oznaczeniach tego środka transportu publicznego. Kolor będzie określony jako ciąg szesnastkowy, np. #FF0033.
  • text_color zawiera kolor tekstu powszechnie używanego na 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 Typ pojazdu.
    • icon zawiera adres URL ikony zwykle powiązanej 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 kolejową,
VehicleType.METRO_RAIL Kolej miejska.
VehicleType.SUBWAY Podziemna kolej miejska.
VehicleType.TRAM Kolej miejska naziemna.
VehicleType.MONORAIL kolej jednoszynowa,
VehicleType.HEAVY_RAIL Kolej dużych prędkości.
VehicleType.COMMUTER_TRAIN kolej podmiejska,
VehicleType.HIGH_SPEED_TRAIN Pociąg szybkobieżny.
VehicleType.BUS Autobus.
VehicleType.INTERCITY_BUS Autobus dalekobieżny.
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 promem,
VehicleType.CABLE_CAR Pojazd poruszający się po kablu, zwykle po ziemi. Kolejki linowe mogą być typu VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT kolejka gondolowa,
VehicleType.FUNICULAR Pojazd wciągany na strome wzniesienie za pomocą liny. Kolejka linowo-terenowa składa się zwykle z 2 wagonów, z których każdy stanowi przeciwwagę dla drugiego.
VehicleType.OTHER W przypadku wszystkich pozostałych pojazdów zwracany jest ten typ.

Sprawdzanie wyników wskazówek dojazdu

Komponenty DirectionsResults – DirectionsRoute, DirectionsLeg, DirectionsStep i TransitDetails – można sprawdzać i wykorzystywać podczas analizowania dowolnej odpowiedzi dotyczącej wskazówek dojazdu.

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 trasę DirectionsStep, aby dodać znaczniki dla każdego kroku, i dołączamy informacje do InfoWindow z tekstem instruktażowym dla tego kroku.

Uwaga: ponieważ obliczamy wskazówki dojazdu pieszo, wyświetlamy też wszelkie ostrzeżenia dla użytkownika 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

Korzystanie z punktów pośrednich na trasach

Jak wspomnieliśmy w sekcji DirectionsRequest, podczas obliczania tras za pomocą usługi Directions możesz też określić punkty pośrednie (typu DirectionsWaypoint) w przypadku wskazówek dojazdu pieszo, rowerem lub samochodem. Punkty pośrednie nie są dostępne w przypadku wskazówek dojazdu transportem publicznym. Punkty pośrednie umożliwiają obliczanie tras przez dodatkowe lokalizacje. W takim przypadku zwracana trasa przebiega przez podane punkty pośrednie.

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

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

Domyślnie usługa Kierunki oblicza trasę przez podane punkty pośrednie w określonej kolejności. Opcjonalnie możesz przekazać parametr optimizeWaypoints: true w ramach parametru DirectionsRequest, aby usługa Kierunki mogła zoptymalizować podaną trasę, zmieniając kolejność punktów pośrednich na bardziej efektywną. (Ta optymalizacja jest zastosowaniem problemu komiwojażera). Czas podróży jest głównym czynnikiem optymalizacji, ale przy wyborze najskuteczniejszej trasy mogą być brane pod uwagę także inne czynniki, takie jak odległość, liczba zakrętów i wiele innych. Wszystkie punkty pośrednie muszą być przystankami, aby usługa Kierunki mogła zoptymalizować trasę.

Jeśli poprosisz usługę Kierunki 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 w Stanach Zjednoczonych z różnymi punktami początkowymi, końcowymi i pośrednimi. (Aby wybrać wiele punktów, podczas wybierania elementów na liście naciśnij Ctrl i kliknij). Zwróć uwagę, że sprawdzamy elementy routes.start_address i routes.end_address, aby uzyskać tekst dotyczący 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;
index.ts

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;
index.js

Limity i ograniczenia dotyczące punktów pośrednich

Obowiązują te limity i ograniczenia:

  • Maksymalna liczba punktów pośrednich dozwolonych podczas korzystania z usługi Wskazówki dojazdu w interfejsie Maps JavaScript API to 25, plus punkt początkowy i miejsce docelowe. Limity są takie same w przypadku interfejsu Directions API (starszego).
  • W przypadku usługi internetowej Directions API (starszej wersji) klienci mogą korzystać z 25 punktów pośrednich oraz punktu początkowego i docelowego.
  • Klienci korzystający z abonamentu Premium w Google Maps Platform mogą korzystać z 25 punktów pośrednich, a także z punktu początkowego i docelowego.
  • Punkty pośrednie nie są obsługiwane w przypadku wskazówek dojazdu transportem publicznym.

Przeciągane wskazówki dojazdu

Użytkownicy mogą modyfikować wyświetlane wskazówki dojazdu rowerem, pieszo lub samochodem, DirectionsRendererdynamicznie, jeśli są one DirectionsRendererprzesuwane. Umożliwia to wybieranie i zmienianie tras przez klikanie i przeciąganie powstałych ścieżek na mapie. Aby określić, czy wyświetlacz renderera umożliwia przeciąganie wskazówek dojazdu, ustaw wartość właściwości draggable na true. Wskazówki dojazdu transportem publicznym nie mogą być przeciągane.

Gdy wskazówki można przeciągać, użytkownik może wybrać dowolny punkt na ścieżce (lub punkt pośredni) wyrenderowanego wyniku i przenieść wskazany komponent w nowe miejsce. DirectionsRenderer będzie się dynamicznie aktualizować, aby wyświetlać zmodyfikowaną ścieżkę. Po zwolnieniu przycisku na mapie pojawi się punkt pośredni (oznaczony małym białym znacznikiem). Wybranie i przesunięcie odcinka trasy spowoduje zmianę tego odcinka, a wybranie i przesunięcie znacznika punktu trasy (w tym punktu początkowego i końcowego) spowoduje zmianę odcinków trasy przechodzących przez ten punkt.

Ponieważ kierunki, które można przeciągać, są modyfikowane i renderowane po stronie klienta, możesz monitorować i obsługiwać zdarzenie directions_changed w obiekcie DirectionsRenderer, aby otrzymywać powiadomienia, gdy użytkownik zmodyfikuje wyświetlane kierunki.

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;
index.ts

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;
index.js
Zobacz przykład

Wypróbuj