Dịch vụ chỉ đường

Tổng quan

Bạn có thể tính toán đường đi (bằng nhiều phương thức di chuyển) bằng cách sử dụng đối tượng DirectionsService. Đối tượng này giao tiếp với Dịch vụ chỉ đường của API Google Maps để nhận yêu cầu chỉ đường và trả về một đường dẫn hiệu quả. Thời gian di chuyển là yếu tố chính được tối ưu hoá, nhưng bạn cũng có thể tính đến các yếu tố khác như khoảng cách, số chặng và nhiều yếu tố khác. Bạn có thể tự xử lý các kết quả chỉ đường này hoặc sử dụng đối tượng DirectionsRenderer để hiển thị các kết quả này.

Khi chỉ định điểm xuất phát hoặc điểm đến trong yêu cầu chỉ đường, bạn có thể chỉ định một chuỗi truy vấn (ví dụ: " Chicago, IL" hoặc "Darwin, NSW, Australia"), giá trị LatLng hoặc đối tượng Địa điểm.

Dịch vụ Chỉ đường có thể trả về thông tin đường đi gồm nhiều phần bằng cách sử dụng một loạt các điểm tham chiếu. Đường đi được hiển thị dưới dạng hình nhiều đường vẽ tuyến đường trên bản đồ, hoặc dưới dạng một loạt nội dung mô tả bằng văn bản trong phần tử <div> (ví dụ: "Đi phải vào đoạn đường nối Cầu Williamsburg").

Bắt đầu

Trước khi sử dụng dịch vụ Chỉ đường trong API JavaScript của Maps, trước tiên, hãy đảm bảo rằng bạn đã bật API Chỉ dẫn trong Google Cloud Console, trong chính dự án bạn đã thiết lập cho API JavaScript của Maps.

Cách xem danh sách các API đã bật:

  1. Chuyển đến Google Cloud Console.
  2. Nhấp vào nút Select a project (Chọn dự án), sau đó chọn chính dự án mà bạn đã thiết lập cho Maps JavaScript API rồi nhấp vào Open (Mở).
  3. Trong danh sách API trên Trang tổng quan, hãy tìm Directions API.
  4. Nếu thấy API này trong danh sách thì bạn đã hoàn tất. Nếu API không có trong danh sách, hãy bật API đó:
    1. Ở đầu trang, hãy chọn ENABLE API (BẬT API) để hiển thị thẻ Library (Thư viện). Ngoài ra, trên trình đơn bên trái, hãy chọn Thư viện.
    2. Tìm Direction API (API Chỉ đường), sau đó chọn API đó từ danh sách kết quả.
    3. Chọn BẬT. Khi quá trình này kết thúc, API Chỉ đường sẽ xuất hiện trong danh sách API trên Trang tổng quan.

Giá và chính sách

Giá

Kể từ ngày 16 tháng 7 năm 2018, gói giá mới "trả tiền theo mức dùng" đã bắt đầu có hiệu lực đối với Maps, Tuyến đường và Địa điểm. Để tìm hiểu thêm về mức giá và giới hạn sử dụng mới khi sử dụng dịch vụ JavaScript Directions, hãy xem phần Mức sử dụng và thanh toán cho Directions API.

Chính sách

Việc sử dụng dịch vụ Directions (Chỉ dẫn) phải tuân thủ các chính sách được mô tả cho API Chỉ dẫn.

Yêu cầu xem đường đi

Thao tác truy cập dịch vụ Chỉ đường không đồng bộ, vì API Google Maps cần thực hiện lệnh gọi đến một máy chủ bên ngoài. Do đó, bạn cần truyền phương thức callback để thực thi sau khi hoàn tất yêu cầu. Phương thức gọi lại này sẽ xử lý(các) kết quả. Xin lưu ý rằng dịch vụ Chỉ đường có thể trả về nhiều hành trình khả thi dưới dạng một mảng routes[] riêng biệt.

Để sử dụng chỉ đường trong API JavaScript của Maps, hãy tạo một đối tượng thuộc loại DirectionsService và gọi DirectionsService.route() để bắt đầu yêu cầu đến dịch vụ Chỉ đường, truyền đối tượng đó một đối tượng cố định DirectionsRequest chứa các cụm từ nhập và phương thức gọi lại để thực thi khi nhận được phản hồi.

Đối tượng cố định DirectionsRequest chứa các trường sau:

{
  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
}

Các trường này được giải thích dưới đây:

  • origin (bắt buộc) chỉ định vị trí bắt đầu để tính toán đường đi. Giá trị này có thể được chỉ định dưới dạng String (ví dụ: "pizza, IL"), giá trị LatLng hoặc đối tượng Địa điểm. Nếu sử dụng đối tượng Địa điểm, bạn có thể chỉ định mã địa điểm, chuỗi truy vấn hoặc vị trí LatLng. Bạn có thể truy xuất mã địa điểm từ Mã hoá địa lý, dịch vụ Tìm kiếm địa điểm và Tự động hoàn thành địa điểm trong Maps JavaScript API. Để tham khảo ví dụ về cách sử dụng mã địa điểm từ tính năng Tự động hoàn thành địa điểm, hãy xem Tính năng tự động hoàn thành và chỉ đường của địa điểm.
  • destination (bắt buộc) chỉ định vị trí kết thúc để tính toán đường đi. Các tuỳ chọn đều giống như trường origin được mô tả ở trên.
  • travelMode (bắt buộc) xác định phương thức vận tải cần sử dụng khi tính toán đường đi. Các giá trị hợp lệ được chỉ định trong phần Chế độ đi lại dưới đây.
  • transitOptions (không bắt buộc) chỉ định các giá trị chỉ áp dụng cho các yêu cầu có travelMode là TRANSIT. Các giá trị hợp lệ được mô tả trong Tuỳ chọn phương tiện công cộng bên dưới.
  • drivingOptions (không bắt buộc) chỉ định các giá trị chỉ áp dụng cho các yêu cầu có travelMode là DRIVING. Các giá trị hợp lệ được mô tả trong phần Tuỳ chọn lái xe dưới đây.

  • unitSystem (không bắt buộc) chỉ định hệ thống đơn vị cần sử dụng khi hiển thị kết quả. Các giá trị hợp lệ được chỉ định trong Hệ thống đơn vị dưới đây.

  • waypoints[] (không bắt buộc) chỉ định một mảng DirectionsWaypoint. Điểm tham chiếu thay đổi một tuyến đường bằng cách định tuyến tuyến đường đó qua(các) vị trí được chỉ định. Điểm tham chiếu được chỉ định dưới dạng một giá trị cố định của đối tượng với các trường như sau:

    • location chỉ định vị trí của điểm tham chiếu (dưới dạng LatLng) dưới dạng đối tượng Place (Địa điểm) hoặc String sẽ được mã hoá địa lý.
    • stopover là một giá trị boolean cho biết điểm tham chiếu là một điểm dừng trên tuyến. Điểm này có tác dụng chia tuyến thành hai tuyến.

    (Để biết thêm thông tin về điểm tham chiếu, hãy xem phần Sử dụng Điểm tham chiếu trong tuyến bên dưới.)

  • optimizeWaypoints (không bắt buộc) chỉ định rằng tuyến sử dụng waypoints đã cung cấp có thể được tối ưu hoá bằng cách sắp xếp lại các điểm tham chiếu theo thứ tự hiệu quả hơn. Nếu là true, dịch vụ Chỉ đường sẽ trả về waypoints đã được sắp xếp lại trong trường waypoint_order.(Để biết thêm thông tin, hãy xem phần Sử dụng Điểm tham chiếu trong Tuyến đường bên dưới.)
  • provideRouteAlternatives (không bắt buộc) khi được đặt thành true sẽ chỉ định rằng dịch vụ Chỉ đường có thể cung cấp nhiều tuyến thay thế trong phản hồi. Xin lưu ý rằng việc cung cấp các lựa chọn tuyến đường có thể làm tăng thời gian phản hồi từ máy chủ. Chế độ này chỉ dành cho các yêu cầu không có điểm tham chiếu trung gian.
  • avoidFerries (không bắt buộc) khi đặt thành true cho biết rằng(các) tuyến đường đã tính toán sẽ tránh được phà, nếu có thể.
  • avoidHighways (không bắt buộc) khi đặt thành true cho biết rằng(các) tuyến đường đã tính toán sẽ tránh các đường cao tốc chính, nếu có thể.
  • avoidTolls (không bắt buộc) khi đặt thành true cho biết rằng(các) tuyến đường đã tính toán sẽ tránh đường có thu phí, nếu có thể.
  • region (không bắt buộc) chỉ định mã vùng, được chỉ định dưới dạng giá trị 2 ký tự của ccTLD ("miền cấp cao nhất"). (Để biết thêm thông tin, hãy xem phần Xu hướng khu vực bên dưới.)

Dưới đây là DirectionsRequest mẫu:

{
  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
}

Phương tiện đi lại

Khi tính toán đường đi, bạn cần chỉ định phương tiện đi lại sẽ sử dụng. Hiện chúng tôi hỗ trợ các chế độ đi lại sau đây:

  • DRIVING (Mặc định) cho biết đường lái xe tiêu chuẩn bằng cách sử dụng mạng đường bộ.
  • BICYCLING yêu cầu chỉ đường xe đạp qua đường dành cho xe đạp và đường ưu tiên.
  • TRANSIT yêu cầu chỉ đường qua các tuyến phương tiện công cộng.
  • WALKING yêu cầu chỉ đường đi bộ qua đường dành cho người đi bộ và vỉa hè.

Hãy tham khảo Thông tin chi tiết về phạm vi lập chỉ mục của Nền tảng Google Maps để xác định phạm vi hỗ trợ chỉ đường tại một quốc gia. Nếu bạn yêu cầu chỉ đường cho một khu vực không có loại chỉ đường đó, thì phản hồi sẽ trả về DirectionsStatus="ZERO_RESULTS".

Lưu ý: Chỉ đường đi bộ có thể không bao gồm đường dành cho người đi bộ rõ ràng, vì vậy, chỉ đường đi bộ sẽ trả về cảnh báo trong DirectionsResult. Những cảnh báo này phải luôn hiển thị cho người dùng. Nếu không sử dụng DirectionsRenderer mặc định thì bạn có trách nhiệm đảm bảo các cảnh báo được hiển thị.

Lựa chọn cho phương tiện công cộng

Các lựa chọn có sẵn cho yêu cầu chỉ đường sẽ khác nhau giữa các phương tiện đi lại. Khi yêu cầu xem đường đi bằng phương tiện công cộng, các lựa chọn avoidHighways, avoidTolls, waypoints[] và optimizeWaypoints sẽ bị bỏ qua. Bạn có thể chỉ định các tuỳ chọn định tuyến dành riêng cho chuyển tuyến thông qua đối tượng cố định TransitOptions.

Đường đi bằng phương tiện công cộng có giới hạn về thời gian. Hệ thống sẽ chỉ trả lại thông tin đường đi cho các thời điểm trong tương lai.

Đối tượng cố định TransitOptions chứa các trường sau:

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

Các trường này được giải thích dưới đây:

  • arrivalTime (không bắt buộc) chỉ định thời gian đến mong muốn dưới dạng đối tượng Date. Nếu bạn chỉ định thời gian đến, thời gian khởi hành sẽ bị bỏ qua.
  • departureTime (không bắt buộc) chỉ định thời gian khởi hành mong muốn dưới dạng đối tượng Date. departureTime sẽ bị bỏ qua nếu bạn chỉ định arrivalTime. Giá trị mặc định là hiện tại (tức là thời gian hiện tại) nếu không có giá trị nào được chỉ định cho departureTime hoặc arrivalTime.
  • modes[] (không bắt buộc) là một mảng chứa một hoặc nhiều giá trị cố định đối tượng TransitMode. Bạn chỉ có thể sử dụng trường này nếu yêu cầu có khoá API. Mỗi TransitMode chỉ định một phương thức chuyển tuyến ưu tiên. Bạn có thể sử dụng các giá trị sau:
    • BUS cho biết rằng tuyến đường đã tính toán nên ưu tiên đi bằng xe buýt.
    • RAIL cho biết rằng tuyến đường đã tính toán nên ưu tiên đi bằng tàu hoả, xe điện, tàu điện và tàu điện ngầm.
    • SUBWAY cho biết rằng tuyến đường đã tính toán nên ưu tiên đi bằng tàu điện ngầm.
    • TRAIN cho biết rằng tuyến đường đã tính toán nên ưu tiên đi bằng tàu hoả.
    • TRAM cho biết rằng tuyến đường đã tính toán nên ưu tiên đi bằng xe điện và xe điện.
  • routingPreference (không bắt buộc) chỉ định các lựa chọn ưu tiên cho các tuyến đường chuyển tuyến. Khi sử dụng tuỳ chọn này, bạn có thể làm sai lệch các tuỳ chọn được trả về, thay vì chấp nhận tuyến mặc định tốt nhất mà API đã chọn. Bạn chỉ có thể chỉ định trường này nếu yêu cầu có khoá API. Bạn có thể sử dụng các giá trị sau:
    • FEWER_TRANSFERS cho biết tuyến đã tính toán nên có số lượt chuyển hạn chế.
    • LESS_WALKING cho biết rằng tuyến đường đã tính toán nên ưu tiên số lượng đi bộ hạn chế.

Dưới đây là ví dụ về DirectionsRequest mẫu bằng phương tiện công cộng:

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

Tuỳ chọn lái xe

Bạn có thể chỉ định các tuỳ chọn định tuyến cho chỉ đường lái xe thông qua đối tượng DrivingOptions.

Đối tượng DrivingOptions chứa các trường sau:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Các trường này được giải thích dưới đây:

  • departureTime (bắt buộc để giá trị cố định của đối tượng drivingOptions phải hợp lệ) chỉ định thời gian khởi hành mong muốn dưới dạng đối tượng Date. Bạn phải đặt giá trị này thành thời điểm hiện tại hoặc một thời điểm nào đó trong tương lai. Ngày đó không được ở trong quá khứ. (API chuyển đổi tất cả các ngày sang giờ UTC để đảm bảo xử lý nhất quán giữa các múi giờ.) Đối với khách hàng sử dụng Gói đặc biệt của Nền tảng Google Maps, nếu bạn đưa departureTime vào yêu cầu, thì API sẽ trả về tuyến đường tốt nhất dựa trên tình trạng giao thông dự kiến tại thời điểm đó và bao gồm thời gian tham gia giao thông dự đoán (duration_in_traffic) trong phản hồi. Nếu bạn không chỉ định thời gian khởi hành (nghĩa là nếu yêu cầu không bao gồm drivingOptions), thì tuyến đường trả về sẽ là tuyến đường thường phù hợp mà không tính đến tình trạng giao thông.
  • trafficModel (không bắt buộc) chỉ định các giả định cần sử dụng khi tính thời gian tham gia lưu lượng truy cập. Chế độ cài đặt này ảnh hưởng đến giá trị được trả về trong trường duration_in_traffic trong phản hồi, chứa thời gian dự đoán trong lưu lượng truy cập dựa trên giá trị trung bình trước đây. Giá trị mặc định là bestguess. Bạn có thể sử dụng các giá trị sau:
    • bestguess (mặc định) cho biết rằng duration_in_traffic được trả về phải là thông tin ước tính chính xác nhất về thời gian di chuyển, dựa trên những thông tin đã biết về cả tình trạng giao thông trước đây và lưu lượng truy cập trực tiếp. Giao thông trực tiếp càng gần với departureTime hơn.
    • pessimistic cho biết rằng duration_in_traffic được trả về phải dài hơn thời gian di chuyển thực tế trong hầu hết các ngày, mặc dù thỉnh thoảng những ngày có tình trạng giao thông đặc biệt xấu có thể vượt quá giá trị này.
    • optimistic cho biết rằng duration_in_traffic được trả về phải ngắn hơn thời gian di chuyển thực tế trong hầu hết các ngày, mặc dù một số ngày có điều kiện giao thông đặc biệt tốt có thể nhanh hơn giá trị này.

Dưới đây là DirectionsRequest mẫu cho chỉ đường lái xe:

{
  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'
  }
}

Hệ thống đơn vị

Theo mặc định, đường đi được tính toán và hiển thị bằng hệ thống đơn vị của quốc gia hoặc khu vực khởi hành. (Lưu ý: Các điểm khởi hành được biểu thị bằng vĩ độ/kinh độ thay vì địa chỉ luôn được đặt mặc định theo đơn vị hệ mét.) Ví dụ: tuyến đường từ " Chicago, IL" đến "Toronto, ONT" sẽ hiển thị kết quả theo dặm, trong khi tuyến đường ngược lại sẽ hiển thị kết quả tính theo kilômét. Bạn có thể ghi đè hệ thống đơn vị này bằng cách đặt một giá trị rõ ràng trong yêu cầu bằng cách sử dụng một trong các giá trị UnitSystem sau:

  • UnitSystem.METRIC chỉ định cách sử dụng hệ mét. Khoảng cách được hiển thị bằng cách sử dụng số km.
  • UnitSystem.IMPERIAL chỉ định cách sử dụng hệ thống Hoàng gia (tiếng Anh). Quãng đường được biểu thị bằng dặm.

Lưu ý: Chế độ cài đặt hệ thống đơn vị này chỉ ảnh hưởng đến văn bản mà người dùng nhìn thấy. Kết quả chỉ đường cũng chứa các giá trị khoảng cách, không hiển thị cho người dùng và luôn được biểu thị bằng mét.

Xu hướng Khu vực cho Chỉ đường

Dịch vụ chỉ đường của API Google Maps trả về kết quả về địa chỉ chịu ảnh hưởng của miền (khu vực hoặc quốc gia) mà từ đó bạn tải tệp khởi động JavaScript. (Vì hầu hết người dùng đều tải https://maps.googleapis.com/, nên chế độ này sẽ đặt một miền ngầm ẩn thành Hoa Kỳ.) Nếu tải quy trình tự khởi động từ một miền được hỗ trợ khác, bạn sẽ nhận được kết quả do miền đó ảnh hưởng. Ví dụ: nội dung tìm kiếm cho "San Francisco" có thể trả về các kết quả khác khi tải ứng dụng https://maps.googleapis.com/ (Hoa Kỳ) so với một kết quả tải http://maps.google.es/ (Tây Ban Nha).

Bạn cũng có thể đặt dịch vụ Chỉ đường để trả về kết quả theo một khu vực cụ thể bằng cách sử dụng tham số region. Thông số này sẽ lấy một mã vùng, được chỉ định dưới dạng một thẻ phụ vùng Unicode gồm hai ký tự (không phải dạng số). Trong hầu hết trường hợp, những thẻ này sẽ ánh xạ trực tiếp đến ccTLD (miền cấp cao nhất) với giá trị gồm 2 ký tự, chẳng hạn như "uk" trong "co.uk". Trong một số trường hợp, thẻ region cũng hỗ trợ mã ISO-3166-1. Mã này đôi khi khác với giá trị ccTLD (ví dụ: "GB" đối với "Vương quốc Anh").

Khi sử dụng tham số region:

  • Chỉ chọn một quốc gia hoặc khu vực. Nhiều giá trị bị bỏ qua và có thể dẫn đến yêu cầu không thành công.
  • Chỉ sử dụng thẻ phụ khu vực hai ký tự (định dạng Unicode CLDR). Tất cả các dữ liệu đầu vào khác đều sẽ dẫn đến lỗi.

Xu hướng khu vực chỉ được hỗ trợ cho các quốc gia và khu vực hỗ trợ chỉ đường. Hãy tham khảo Thông tin chi tiết về phạm vi lập chỉ mục của Nền tảng Google Maps để xem phạm vi quốc tế cho API Chỉ dẫn.

Hướng dẫn kết xuất

Để bắt đầu yêu cầu chỉ đường đến DirectionsService bằng phương thức route(), bạn phải truyền một lệnh gọi lại. Lệnh gọi lại này sẽ thực thi sau khi hoàn tất yêu cầu dịch vụ. Lệnh gọi lại này sẽ trả về mã DirectionsResult và DirectionsStatus trong phản hồi.

Trạng thái của truy vấn chỉ đường

DirectionsStatus có thể trả về các giá trị sau:

  • OK cho biết phản hồi chứa DirectionsResult hợp lệ.
  • NOT_FOUND cho biết ít nhất một trong các vị trí được chỉ định trong điểm gốc, đích đến hoặc điểm tham chiếu của yêu cầu không thể mã hoá địa lý.
  • ZERO_RESULTS cho biết không tìm thấy tuyến nào giữa điểm khởi hành và đích đến.
  • MAX_WAYPOINTS_EXCEEDED cho biết có quá nhiều trường DirectionsWaypoint đã được cung cấp trong DirectionsRequest. Hãy xem phần dưới đây về các giới hạn đối với điểm tham chiếu.
  • MAX_ROUTE_LENGTH_EXCEEDED cho biết tuyến được yêu cầu quá dài và không thể xử lý được. Lỗi này xảy ra khi trả về các hướng phức tạp hơn. Hãy thử giảm số điểm tham chiếu, ngã rẽ hoặc hướng dẫn.
  • INVALID_REQUEST cho biết DirectionsRequest được cung cấp không hợp lệ. Nguyên nhân phổ biến nhất của mã lỗi này là do các yêu cầu bị thiếu điểm gốc hoặc đích đến, hoặc một yêu cầu chuyển tuyến có điểm tham chiếu.
  • OVER_QUERY_LIMIT cho biết trang web đã gửi quá nhiều yêu cầu trong khoảng thời gian cho phép.
  • REQUEST_DENIED cho biết trang web đó không được phép sử dụng dịch vụ chỉ đường.
  • UNKNOWN_ERROR cho biết không thể xử lý yêu cầu chỉ đường do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn thử lại.

Bạn nên đảm bảo rằng truy vấn chỉ đường trả về kết quả hợp lệ bằng cách kiểm tra giá trị này trước khi xử lý kết quả.

Hiển thị DirectionsResult

DirectionsResult chứa kết quả của truy vấn chỉ đường mà bạn có thể tự xử lý hoặc truyền vào đối tượng DirectionsRenderer. Đối tượng này có thể tự động xử lý việc hiển thị kết quả trên bản đồ.

Để hiển thị DirectionsResult bằng DirectionsRenderer, bạn cần làm như sau:

  1. Tạo đối tượng DirectionsRenderer.
  2. Gọi setMap() trên trình kết xuất để liên kết nó với bản đồ đã chuyển.
  3. Gọi setDirections() trên trình kết xuất, truyền vào đó DirectionsResult như đã lưu ý ở trên. Vì trình kết xuất là một MVCObject nên trình kết xuất này sẽ tự động phát hiện mọi thay đổi đối với thuộc tính và cập nhật bản đồ khi các hướng liên quan thay đổi.

Ví dụ sau đây tính toán đường đi giữa hai vị trí trên Tuyến đường 66, trong đó điểm khởi hành và điểm đến được đặt bởi các giá trị "start" và "end" đã cho trong danh sách thả xuống. DirectionsRenderer xử lý việc hiển thị hình nhiều đường giữa các vị trí được chỉ định và vị trí của điểm đánh dấu tại điểm gốc, điểm đến và bất kỳ điểm tham chiếu nào, nếu có.

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);
    }
  });
}

Trong phần nội dung 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>

Xem ví dụ

Ví dụ sau đây cho thấy thông tin đường đi bằng nhiều phương thức di chuyển từ Haight-Ashbury đến Ocean Beach ở San Francisco, CA:

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);
    }
  });
}

Trong phần nội dung 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>

Xem ví dụ

DirectionsRenderer không chỉ xử lý việc hiển thị hình nhiều đường và mọi điểm đánh dấu liên quan, mà còn có thể xử lý việc hiển thị chỉ đường bằng văn bản dưới dạng một loạt các bước. Để thực hiện việc này, hãy gọi setPanel() trên DirectionsRenderer, truyền vào đó <div> để hiển thị thông tin này. Việc này cũng đảm bảo rằng bạn hiển thị thông tin phù hợp về bản quyền và mọi cảnh báo có thể liên quan đến kết quả tìm kiếm đó.

Hướng dẫn bằng văn bản sẽ được cung cấp qua chế độ cài đặt ngôn ngữ ưu tiên của trình duyệt hoặc ngôn ngữ được chỉ định khi tải API JavaScript bằng tham số language. (Để biết thêm thông tin, hãy xem nội dung Bản địa hoá.) Đối với thông tin chỉ đường cho phương tiện công cộng, thời gian sẽ được hiển thị theo múi giờ tại điểm dừng của phương tiện công cộng đó.

Ví dụ sau đây hoàn toàn giống với ví dụ ở trên, nhưng có một bảng điều khiển <div> để hiển thị thông tin đường đi:

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);
    }
  });
}

Trong phần nội dung HTML:

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

Xem ví dụ

Đối tượng DirectionsResult

Khi gửi yêu cầu chỉ đường đến DirectionsService, bạn sẽ nhận được phản hồi bao gồm một mã trạng thái và kết quả là đối tượng DirectionsResult. DirectionsResult là một đối tượng cố định có các trường sau:

  • geocoded_waypoints[] chứa một mảng các đối tượng DirectionsGeocodedWaypoint, mỗi đối tượng chứa thông tin chi tiết về việc mã hoá địa lý của điểm gốc, điểm đến và điểm tham chiếu.
  • routes[] chứa một mảng các đối tượng DirectionsRoute. Mỗi tuyến chỉ định một cách để đi từ điểm gốc đến đích được cung cấp trong DirectionsRequest. Nhìn chung, chỉ một tuyến được trả về cho một yêu cầu nhất định, trừ phi trường provideRouteAlternatives của yêu cầu được đặt thành true, trong đó, nhiều tuyến có thể được trả về.

Lưu ý: Thuộc tính via_waypoint không dùng nữa trong các tuyến thay thế. Phiên bản 3.27 là phiên bản cuối cùng của API bổ sung thông qua điểm tham chiếu trong các tuyến thay thế. Đối với các phiên bản API 3.28 trở lên, bạn có thể tiếp tục triển khai hướng có thể kéo bằng dịch vụ Chỉ dẫn bằng cách tắt tính năng kéo các tuyến đường thay thế. Bạn chỉ có thể kéo tuyến đường chính. Người dùng có thể kéo tuyến chính cho đến khi nó khớp với một tuyến thay thế.

Điểm tham chiếu được mã hoá theo địa lý cho đường đi

DirectionsGeocodedWaypoint chứa thông tin chi tiết về mã hoá địa lý của nguồn gốc, đích đến và điểm tham chiếu.

DirectionsGeocodedWaypoint là một đối tượng cố định có các trường sau:

  • geocoder_status cho biết mã trạng thái phát sinh từ thao tác mã hoá địa lý. Trường này có thể chứa các giá trị sau.
    • "OK" cho biết không có lỗi nào xảy ra; địa chỉ đã được phân tích cú pháp thành công và ít nhất một mã địa lý được trả về.
    • "ZERO_RESULTS" cho biết mã địa lý đã thành công nhưng không trả về kết quả nào. Điều này có thể xảy ra nếu bộ mã hoá địa lý được chuyển một address không tồn tại.

  • partial_match cho biết bộ mã hoá địa lý không trả về kết quả khớp chính xác cho yêu cầu ban đầu, mặc dù có thể khớp với một phần địa chỉ được yêu cầu. Bạn nên kiểm tra yêu cầu ban đầu để xem có lỗi chính tả và/hoặc địa chỉ chưa hoàn chỉnh trong yêu cầu hay không.

    Khớp một phần thường xảy ra nhất với các địa chỉ đường phố không tồn tại trong khu vực mà bạn chuyển đến trong yêu cầu. Kết quả khớp một phần cũng có thể được trả về khi một yêu cầu khớp với hai hoặc nhiều vị trí trong cùng một địa phương. Ví dụ: "Hillpar St, Bristol, UK" sẽ trả về kết quả khớp một phần cho cả Phố Henry và phố Henrietta. Xin lưu ý rằng nếu một yêu cầu bao gồm thành phần địa chỉ bị sai chính tả, thì dịch vụ mã hóa địa lý có thể đề xuất một địa chỉ thay thế. Các đề xuất được kích hoạt theo cách này cũng sẽ được đánh dấu là khớp một phần.

  • place_id là giá trị nhận dạng duy nhất của một địa điểm, có thể dùng với các API khác của Google. Ví dụ: bạn có thể sử dụng place_id với thư viện API Google Địa điểm để xem thông tin chi tiết về một doanh nghiệp địa phương, chẳng hạn như số điện thoại, giờ mở cửa, bài đánh giá của người dùng, v.v. Xem tổng quan về mã địa điểm.
  • types[] là một mảng cho biết loại của kết quả được trả về. Mảng này chứa một tập hợp gồm từ 0 thẻ trở lên xác định loại tính năng được trả về trong kết quả. Ví dụ: một mã địa lý của " " " " " " " " " " " " " " " " sẽ trả về " " " " " " cho biết " " " " " "

Tuyến đường chỉ đường

Lưu ý: Đối tượng DirectionsTrip cũ đã được đổi tên thành DirectionsRoute. Xin lưu ý rằng tuyến đường hiện đề cập đến toàn bộ hành trình từ điểm bắt đầu đến kết thúc, thay vì chỉ đơn thuần là một chặng của chuyến đi mẹ.

DirectionsRoute chứa một kết quả duy nhất từ điểm gốc và đích đến đã chỉ định. Tuyến đường này có thể bao gồm một hoặc nhiều chặng (thuộc loại DirectionsLeg), tuỳ thuộc vào việc có điểm tham chiếu nào được chỉ định hay không. Ngoài ra, tuyến đường này cũng chứa thông tin bản quyền và cảnh báo mà phải được hiển thị cho người dùng ngoài thông tin định tuyến.

DirectionsRoute là một đối tượng cố định có các trường sau:

  • legs[] chứa một mảng các đối tượng DirectionsLeg, mỗi đối tượng chứa thông tin về một chặng của tuyến đường, từ hai vị trí trong tuyến đường đã cho. Một chân riêng sẽ xuất hiện cho mỗi điểm tham chiếu hoặc đích được chỉ định. (Một tuyến không có điểm tham chiếu sẽ chứa đúng một DirectionsLeg.) Mỗi chân bao gồm một chuỗi DirectionStep.
  • waypoint_order chứa một mảng cho biết thứ tự của mọi điểm tham chiếu trong tuyến đã tính. Mảng này có thể chứa thứ tự đã thay đổi nếu DirectionsRequest được truyền optimizeWaypoints: true.
  • overview_path chứa một mảng LatLng đại diện cho một đường dẫn gần đúng (được làm mượt) của đường đi kết quả.
  • overview_polyline chứa một đối tượng points duy nhất chứa một hình nhiều đường được mã hoá của tuyến. Hình nhiều đường này là một đường dẫn gần đúng (được làm mượt) của các hướng kết quả.
  • bounds chứa LatLngBounds cho biết các ranh giới của hình nhiều đường dọc theo tuyến đường nhất định này.
  • copyrights chứa văn bản bản quyền sẽ hiển thị cho tuyến này.
  • warnings[] chứa một loạt cảnh báo sẽ hiển thị khi hiển thị các chỉ đường này. Nếu không dùng đối tượng DirectionsRenderer được cung cấp, bạn phải tự xử lý và cho thấy các cảnh báo này.
  • fare chứa tổng giá vé (tức là tổng chi phí vé) trên chặng bay này. Cơ sở lưu trú này chỉ được trả về cho các yêu cầu về phương tiện công cộng và chỉ cho các tuyến đường có thông tin giá vé cho tất cả các chặng đi phương tiện công cộng. Trong đó có:
    • currency: Mã đơn vị tiền tệ theo tiêu chuẩn ISO 4217 cho biết đơn vị tiền tệ mà số tiền đó được thể hiện bằng đơn vị tiền tệ đó.
    • value: Tổng số tiền giá vé, theo đơn vị tiền tệ được chỉ định ở trên.

Chân định hướng

Lưu ý: Đối tượng DirectionsRoute cũ đã được đổi tên thành DirectionsLeg.

DirectionsLeg xác định một chặng của hành trình từ điểm gốc đến đích đến trong tuyến đã tính. Đối với các tuyến đường không chứa điểm tham chiếu, tuyến đường sẽ có một "chân" duy nhất. Tuy nhiên, đối với các tuyến đường xác định một hoặc nhiều điểm tham chiếu, tuyến đường sẽ có một hoặc nhiều chân, tương ứng với các chặng cụ thể của hành trình.

DirectionsLeg là một đối tượng cố định có các trường sau:

  • steps[] chứa một mảng các đối tượng DirectionsStep cho biết thông tin về từng bước riêng biệt trong giai đoạn sau của hành trình.

  • distance cho biết tổng quãng đường mà chân này đi được, dưới dạng đối tượng Distance có dạng sau:

    • value cho biết khoảng cách tính bằng mét
    • text chứa một chuỗi đại diện cho khoảng cách, theo mặc định sẽ hiển thị bằng đơn vị dùng tại điểm gốc. (Ví dụ: dặm sẽ được sử dụng cho bất kỳ điểm khởi hành nào trong lãnh thổ Hoa Kỳ.) Bạn có thể ghi đè hệ thống đơn vị này bằng cách thiết lập cụ thể UnitSystem trong truy vấn ban đầu. Xin lưu ý rằng bất kể bạn sử dụng hệ thống đơn vị nào, trường distance.value luôn chứa một giá trị được biểu thị bằng mét.

    Các trường này có thể là không xác định nếu không xác định được khoảng cách.

  • duration cho biết tổng thời lượng của chân này, dưới dạng đối tượng Duration ở dạng sau:

    • value cho biết thời lượng tính bằng giây.
    • text chứa một chuỗi đại diện cho thời lượng.

    Nếu thời lượng không xác định, thì những trường này có thể là không xác định.

  • duration_in_traffic cho biết tổng thời gian của chặng này có tính đến điều kiện giao thông hiện tại. duration_in_traffic chỉ được trả về nếu tất cả các điều kiện sau đây là đúng:

    • Yêu cầu không bao gồm điểm dừng tham chiếu. Tức là dữ liệu này không bao gồm các điểm tham chiếu trong đó stopover là true.
    • Yêu cầu này dành riêng cho tính năng chỉ đường lái xe – mode được đặt thành driving.
    • departureTime có trong trường drivingOptions trong yêu cầu.
    • Tình trạng giao thông có sẵn cho tuyến đường được yêu cầu.

    duration_in_traffic chứa các trường sau:

    • value cho biết thời lượng tính bằng giây.
    • text chứa biểu thị thời lượng mà con người có thể đọc được.
  • arrival_time chứa thời gian đến dự kiến cho chặng bay này. Cơ sở lưu trú này chỉ được trả lại cho đường đi bằng phương tiện công cộng. Kết quả được trả về dưới dạng một đối tượng Time có ba thuộc tính:
    • value thời gian được chỉ định làm đối tượng JavaScript Date.
    • text thời gian được chỉ định dưới dạng chuỗi. Thời gian được hiển thị theo múi giờ của điểm dừng của phương tiện công cộng.
    • time_zone chứa múi giờ của trạm này. Giá trị này là tên của múi giờ theo xác định trong Cơ sở dữ liệu múi giờ IANA, ví dụ: "America/New_New York".
  • departure_time chứa thời gian khởi hành dự kiến cho chặng này, được chỉ định dưới dạng đối tượng Time. departure_time chỉ áp dụng cho đường đi bằng phương tiện công cộng.
  • start_location chứa LatLng của nguồn gốc của chân này. Vì Dịch vụ web chỉ đường tính toán đường đi giữa các vị trí bằng cách sử dụng phương tiện giao thông gần nhất (thường là một con đường) tại điểm đầu và điểm cuối, nên start_location có thể khác với điểm khởi hành được cung cấp của chặng này nếu một con đường không gần điểm gốc.
  • end_location chứa LatLng đích của chân này. Vì DirectionsService tính toán đường đi giữa các vị trí bằng cách sử dụng phương tiện giao thông gần nhất (thường là một con đường) tại điểm đầu và điểm cuối, nên end_location có thể khác với điểm đến được cung cấp cho chặng này nếu chẳng hạn như một con đường không gần điểm đến.
  • start_address chứa địa chỉ mà con người có thể đọc được (thường là địa chỉ đường phố) ở đầu chặng này.

    Nội dung này là để đọc nguyên trạng. Đừng phân tích cú pháp địa chỉ đã định dạng theo lập trình.
  • end_address chứa địa chỉ mà con người có thể đọc được (thường là địa chỉ đường phố) ở cuối chân này.

    Nội dung này là để đọc nguyên trạng. Đừng phân tích cú pháp địa chỉ đã định dạng theo lập trình.

Các bước chỉ dẫn

DirectionsStep là đơn vị nguyên tử nhất của tuyến đường của một hướng, chứa một bước duy nhất mô tả một hướng dẫn cụ thể, duy nhất trên hành trình. Ví dụ: "Hãy rẽ trái tại W. Đường 4" Bước này không chỉ mô tả hướng dẫn mà còn chứa thông tin về khoảng cách và thời lượng liên quan đến bước này và bước tiếp theo. Ví dụ: một bước được biểu thị là "Hợp nhất vào I-80 West" có thể chứa thời gian là "37 dặm" và "40 phút", cho biết rằng bước tiếp theo là 37 dặm/40 phút từ bước này.

Khi sử dụng dịch vụ Chỉ đường để tìm đường đi bằng phương tiện công cộng, mảng bước sẽ bao gồm Thông tin cụ thể về phương tiện công cộng bổ sung ở dạng đối tượng transit. Nếu thông tin đường đi có nhiều phương thức di chuyển, thì thông tin đường đi chi tiết sẽ được cung cấp cho các bước đi bộ hoặc lái xe trong một mảng steps[]. Ví dụ: một bước đi bộ sẽ bao gồm thông tin chỉ đường từ vị trí xuất phát và vị trí kết thúc: "Đi bộ đến Innes Ave và Fitch St". Bước đó sẽ bao gồm chỉ đường đi bộ chi tiết cho tuyến đường đó trong mảng steps[], chẳng hạn như: "Đi về hướng tây bắc", "Ngược sang trái vào Arelious Walker" và "Đi sang trái vào Innes Ave".

DirectionsStep là một đối tượng cố định có các trường sau:

  • instructions chứa hướng dẫn cho bước này trong một chuỗi văn bản.
  • distance chứa khoảng cách mà bước này sẽ thực hiện cho đến bước tiếp theo, dưới dạng đối tượng Distance. (Xem nội dung mô tả trong DirectionsLeg ở trên.) Trường này có thể không xác định nếu không xác định được khoảng cách.
  • duration chứa thông tin ước tính về thời gian cần thiết để thực hiện bước tiếp theo cho đến bước tiếp theo dưới dạng đối tượng Duration. (Xem nội dung mô tả trong DirectionsLeg ở trên.) Trường này có thể không xác định nếu không xác định được thời lượng.
  • start_location chứa LatLng được mã hoá địa lý tại điểm bắt đầu của bước này.
  • end_location chứa LatLng của điểm kết thúc của bước này.
  • polyline chứa một đối tượng points duy nhất chứa một hình nhiều dòng được mã hoá của bước đó. Hình nhiều đường này là một đường dẫn gần đúng (được làm mượt) của bước.
  • steps[] là một đối tượng cố định DirectionsStep chứa thông tin chỉ đường chi tiết về các bước đi bộ hoặc lái xe trên đường đi bằng phương tiện công cộng. Bạn chỉ có thể sử dụng các bước phụ cho chỉ đường bằng phương tiện công cộng.
  • travel_mode chứa TravelMode dùng trong bước này. Đường đi bằng phương tiện công cộng có thể bao gồm kết hợp chỉ đường đi bộ và chỉ đường bằng phương tiện công cộng.
  • path chứa một mảng LatLngs mô tả tiến trình của bước này.
  • transit chứa thông tin cụ thể về phương tiện công cộng, chẳng hạn như thời gian đến và khởi hành, cũng như tên của đường chuyển tuyến.

Thông tin cụ thể về phương tiện công cộng

Đường đi bằng phương tiện công cộng sẽ trả về thông tin bổ sung không liên quan đến các phương thức di chuyển khác. Các thuộc tính bổ sung này được hiển thị thông qua đối tượng TransitDetails, được trả về dưới dạng thuộc tính của DirectionsStep. Từ đối tượng TransitDetails, bạn có thể truy cập thêm thông tin cho các đối tượng TransitStop, TransitLine, TransitAgency và VehicleType như mô tả dưới đây.

Thông tin về phương tiện công cộng

Đối tượng TransitDetails hiển thị các thuộc tính sau:

  • arrival_stop chứa một đối tượng TransitStop đại diện cho ga/điểm dừng đến với các thuộc tính sau:
    • name tên của trạm/điểm dừng phương tiện công cộng. Ví dụ: "Quảng trường Union".
    • location vị trí của trạm/điểm dừng phương tiện công cộng, được biểu thị dưới dạng LatLng.
  • departure_stop chứa một đối tượng TransitStop đại diện cho trạm khởi hành/điểm dừng.
  • arrival_time chứa thời gian đến, được xác định dưới dạng đối tượng Time với ba thuộc tính:
    • value thời gian được chỉ định làm đối tượng JavaScript Date.
    • text thời gian được chỉ định dưới dạng chuỗi. Thời gian được hiển thị theo múi giờ của điểm dừng của phương tiện công cộng.
    • time_zone chứa múi giờ của trạm này. Giá trị này là tên của múi giờ theo xác định trong Cơ sở dữ liệu múi giờ IANA, ví dụ: "America/New_New York".
  • departure_time chứa thời gian khởi hành, được xác định dưới dạng đối tượng Time.
  • headsign xác định hướng đi trên dòng này, vì được đánh dấu trên xe hoặc tại điểm khởi hành. Đây thường sẽ là trạm cuối.
  • headway (nếu có), giá trị này xác định số giây dự kiến giữa các chuyến khởi hành từ cùng một điểm dừng tại thời điểm này. Ví dụ: với giá trị headway là 600, bạn sẽ phải chờ 10 phút nếu lỡ xe buýt.
  • line chứa một đối tượng cố định TransitLine chứa thông tin về đường chuyển tuyến được dùng trong bước này. TransitLine cung cấp tên và toán tử của dòng, cùng với các thuộc tính khác được mô tả trong tài liệu tham khảo về TransitLine.
  • num_stops chứa số điểm dừng trong bước này. Bao gồm điểm dừng đến, nhưng không phải điểm dừng khởi hành. Ví dụ: nếu đường đi của bạn là khởi hành từ Điểm dừng A, đi qua điểm dừng B và C và đến điểm dừng D, thì num_stops sẽ trả về 3.

Đường chuyển

Đối tượng TransitLine cho thấy các thuộc tính sau:

  • name chứa tên đầy đủ của đường chuyển tuyến này. Ví dụ: "7 Avenue Express" hoặc "14th St Crosstown".
  • short_name chứa tên ngắn của đường chuyển tuyến này. Thông thường, đây sẽ là số dòng, chẳng hạn như "2" hoặc "M14".
  • agencies là một mảng chứa một đối tượng TransitAgency duy nhất. Đối tượng TransitAgency cung cấp thông tin về toán tử của dòng này, bao gồm các thuộc tính sau:
    • name chứa tên của công ty vận tải.
    • phone chứa số điện thoại của công ty vận tải.
    • url chứa URL của công ty vận tải.

    Lưu ý: Nếu đang hiển thị đường đi phương tiện công cộng theo cách thủ công thay vì sử dụng đối tượng DirectionsRenderer, bạn phải hiển thị tên và URL của các công ty vận tải phân phối kết quả chuyến đi.

  • url chứa URL cho đường chuyển tuyến này do công ty vận tải cung cấp.
  • icon chứa URL cho biểu tượng liên kết với dòng này. Hầu hết các thành phố sẽ sử dụng những biểu tượng chung khác nhau tuỳ theo loại xe. Một số tuyến phương tiện công cộng, chẳng hạn như hệ thống tàu điện ngầm New York, có biểu tượng dành riêng cho tuyến đó.
  • color chứa màu thường dùng trong biển báo cho phương tiện công cộng này. Màu sắc sẽ được chỉ định dưới dạng chuỗi hex như: #FF0033.
  • text_color chứa màu của văn bản thường dùng cho bảng hiệu của dòng này. Màu sẽ được chỉ định dưới dạng một chuỗi hex.
  • vehicle chứa đối tượng Vehicle bao gồm các thuộc tính sau:
    • name chứa tên của xe trên dòng này. Ví dụ: "Xe điện ngầm."
    • type chứa loại phương tiện được sử dụng trên tuyến này. Vui lòng xem tài liệu về Loại xe để biết danh sách đầy đủ các giá trị được hỗ trợ.
    • icon chứa URL cho biểu tượng thường liên kết với loại xe này.
    • local_icon chứa URL cho biểu tượng liên kết với loại phương tiện này, dựa trên biển hiệu giao thông địa phương.

Loại xe

Đối tượng VehicleType hiển thị các thuộc tính sau:

Giá trị Định nghĩa
VehicleType.RAIL Đường sắt.
VehicleType.METRO_RAIL Phương tiện công cộng bằng xe điện.
VehicleType.SUBWAY Đường tàu điện ngầm.
VehicleType.TRAM Trên mặt đất.
VehicleType.MONORAIL Xe lửa chạy trên đường một ray.
VehicleType.HEAVY_RAIL Đường sắt nặng.
VehicleType.COMMUTER_TRAIN Tuyến đường sắt cho người đi làm.
VehicleType.HIGH_SPEED_TRAIN Tàu cao tốc.
VehicleType.BUS Xe buýt.
VehicleType.INTERCITY_BUS Xe buýt liên thành phố.
VehicleType.TROLLEYBUS Xe điện.
VehicleType.SHARE_TAXI Taxi chung là một loại xe buýt có tính năng trả khách và đón khách ở bất cứ đâu trên tuyến đường của nó.
VehicleType.FERRY Phà.
VehicleType.CABLE_CAR Một phương tiện vận hành trên cáp, thường là trên mặt đất. Cáp treo trên không có thể thuộc loại VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Một tuyến cáp treo trên không.
VehicleType.FUNICULAR Một chiếc xe bị cáp kéo lên một dốc đứng. Đường sắt leo núi thường bao gồm hai toa, trong đó mỗi toa đóng vai trò là đối trọng của xe kia.
VehicleType.OTHER Tất cả các xe khác sẽ trả về loại này.

Kiểm tra kết quả chỉ dẫn

Các thành phần DirectionsResults – DirectionsRoute, DirectionsLeg, DirectionsStep và TransitDetails – có thể được kiểm tra và sử dụng khi phân tích cú pháp bất kỳ phản hồi chỉ đường nào.

Lưu ý quan trọng: Nếu đang hiển thị đường đi phương tiện công cộng theo cách thủ công thay vì sử dụng đối tượng DirectionsRenderer, bạn phải hiển thị tên và URL của các công ty vận tải phân phối kết quả chuyến đi.

Ví dụ sau đây minh hoạ đường đi bộ đến một số điểm tham quan du lịch nhất định ở Thành phố New York. Chúng ta kiểm tra DirectionsStep của tuyến đường để thêm điểm đánh dấu cho từng bước và đính kèm thông tin vào InfoWindow có văn bản hướng dẫn cho bước đó.

Lưu ý: Vì chúng tôi đang tính toán đường đi bộ, nên chúng tôi cũng sẽ hiển thị mọi cảnh báo cho người dùng trong một bảng điều khiển <div> riêng.

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);
  });
}

Trong phần nội dung 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>

Xem ví dụ

Sử dụng Điểm tham chiếu trong tuyến đường

Như đã lưu ý trong DirectionsRequest, bạn cũng có thể chỉ định các điểm tham chiếu (thuộc loại DirectionsWaypoint) khi tính toán tuyến đường bằng dịch vụ Chỉ đường cho chỉ đường đi bộ, đi xe đạp hoặc lái xe. Điểm tham chiếu không có sẵn cho chỉ đường chuyển tuyến. Điểm tham chiếu cho phép bạn tính toán tuyến đường qua các vị trí khác, trong trường hợp tuyến đường được trả về đi qua các điểm tham chiếu nhất định.

waypoint bao gồm các trường sau:

  • location (bắt buộc) chỉ định địa chỉ của điểm tham chiếu.
  • stopover (không bắt buộc) cho biết liệu điểm tham chiếu này là một điểm dừng thực tế trên tuyến đường (true) hay chỉ là một lựa chọn ưu tiên để đi qua vị trí được chỉ định (false). Các điểm dừng này sẽ là true theo mặc định.

Theo mặc định, dịch vụ Đường đi sẽ tính toán tuyến đường qua các điểm tham chiếu đã cho theo thứ tự cụ thể. Nếu muốn, bạn có thể truyền optimizeWaypoints: true trong DirectionsRequest để cho phép dịch vụ Chỉ đường tối ưu hoá tuyến đường đã cung cấp bằng cách sắp xếp lại các điểm tham chiếu theo thứ tự hiệu quả hơn. (Phương thức tối ưu hoá này là một ứng dụng của vấn đề với nhân viên bán hàng lưu động.) Thời gian di chuyển là yếu tố chính được tối ưu hoá. Tuy nhiên, khi quyết định tuyến đường nào là hiệu quả nhất, bạn có thể xem xét các yếu tố khác như khoảng cách, số lượt rẽ và nhiều yếu tố khác. Tất cả các điểm tham chiếu phải là điểm dừng để dịch vụ Đường đi để tối ưu hoá tuyến đường của chúng.

Nếu bạn hướng dẫn dịch vụ Chỉ đường tối ưu hoá thứ tự của các điểm tham chiếu, thì thứ tự của các điểm tham chiếu đó sẽ được trả về trong trường waypoint_order trong đối tượng DirectionsResult.

Ví dụ sau đây tính toán các tuyến đường xuyên quốc gia trên khắp Hoa Kỳ bằng cách sử dụng nhiều điểm xuất phát, điểm cuối và điểm tham chiếu. (Để chọn nhiều điểm tham chiếu, hãy nhấn phím Ctrl-Nhấp khi chọn các mục trong danh sách.) Xin lưu ý rằng chúng ta kiểm tra routes.start_address và routes.end_address để cung cấp văn bản cho điểm bắt đầu và kết thúc của mỗi tuyến.

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

Giới hạn và hạn chế đối với Điểm tham chiếu

Các hạn mức và hạn mức sử dụng sau đây sẽ được áp dụng:

  • Số lượng điểm tham chiếu tối đa được phép khi sử dụng dịch vụ Chỉ đường trong API JavaScript của Maps là 25, cộng với điểm gốc và điểm đến. Các giới hạn là giống nhau cho dịch vụ web API chỉ đường.
  • Đối với dịch vụ web Directions API, khách hàng được phép có 25 điểm tham chiếu, cùng với điểm gốc và điểm đến.
  • Khách hàng sử dụng Gói cao cấp của Nền tảng Google Maps được phép có 25 điểm tham chiếu, cùng với điểm xuất phát và điểm đến.
  • Điểm tham chiếu không được hỗ trợ cho chỉ đường chuyển tuyến.

Đường đi có thể kéo

Người dùng có thể sửa đổi thông tin đường đi xe đạp, đi bộ hoặc lái xe được hiển thị bằng một DirectionsRenderer linh động nếu có thể kéo. Điều này cho phép người dùng chọn và thay đổi tuyến đường bằng cách nhấp và kéo các đường dẫn kết quả trên bản đồ. Bạn có thể cho biết liệu màn hình trình kết xuất có cho phép các hướng có thể kéo hay không bằng cách đặt thuộc tính draggable của trình kết xuất thành true. Bạn không thể kéo chỉ đường chuyển tuyến.

Khi có thể kéo chỉ đường, người dùng có thể chọn bất kỳ điểm nào trên đường dẫn (hoặc điểm tham chiếu) của kết quả được kết xuất và di chuyển thành phần được chỉ định đến một vị trí mới. DirectionsRenderer sẽ tự động cập nhật để cho thấy đường dẫn đã được sửa đổi. Sau khi phát hành, một điểm tham chiếu chuyển tiếp sẽ được thêm vào bản đồ (được biểu thị bằng một điểm đánh dấu nhỏ màu trắng). Việc chọn và di chuyển một đoạn đường dẫn sẽ làm thay đổi chân đó của tuyến đường, trong khi chọn và di chuyển một điểm đánh dấu điểm tham chiếu (bao gồm cả điểm bắt đầu và kết thúc) sẽ làm thay đổi các chân của tuyến đường đi qua điểm tham chiếu đó.

Vì các hướng có thể kéo được sửa đổi và hiển thị ở phía máy khách, bạn nên theo dõi và xử lý sự kiện directions_changed trên DirectionsRenderer để nhận được thông báo khi người dùng sửa đổi hướng dẫn hiển thị.

Mã sau đây cho thấy một chuyến đi từ Perth ở bờ tây Úc đến Sydney ở bờ đông. Mã này theo dõi sự kiện directions_changed để cập nhật tổng quãng đường của tất cả các chặng trong hành trình.

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
Xem ví dụ

Thử mẫu