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 API của Google Maps. Dịch vụ này nhận các 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 các yếu tố khác như khoảng cách, số lượt rẽ và nhiều yếu tố khác cũng có thể được xem xét. 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"), một giá trị LatLng hoặc một đối tượng Địa điểm.

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

Bắt đầu

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

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

  1. Chuyển đến Google Cloud Console.
  2. Nhấp vào nút Chọn dự án, sau đó chọn chính dự án mà bạn đã thiết lập cho API Maps JavaScript rồi nhấp vào Mở.
  3. Trong danh sách API trên Trang tổng quan, hãy tìm Directions API (API chỉ đường).
  4. Nếu thấy API trong danh sách, tức là 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 BẬT API để hiển thị thẻ 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 kiếm Directions API (API chỉ đường), sau đó chọn API đó trong danh sách kết quả.
    3. Chọn BẬT. Khi quá trình này hoàn tất, Directions API 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, một gói giá mới theo phương thức trả phí khi sử dụng sẽ có hiệu lực đối với Maps, Routes và Places. Để tìm hiểu thêm về mức giá mới và hạn mức sử dụng khi bạn sử dụng dịch vụ Chỉ đường JavaScript, hãy xem phần Sử dụng và thanh toán cho API Chỉ đường.

Chính sách

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

Yêu cầu chỉ đường

Việc truy cập vào dịch vụ Chỉ đường là 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. Vì lý do đó, bạn cần truyền một phương thức lệnh gọi lại để 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 có thể có dưới dạng một mảng gồm các routes[] riêng biệt.

Để sử dụng chỉ đường trong API Maps JavaScript, 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, chuyển cho dịch vụ này một đối tượng cố định DirectionsRequest chứa các cụm từ đầu vào và một phương thức gọi lại để thực thi khi nhận được phản hồi.

Biểu thức cố định đối tượng 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. Bạn có thể chỉ định giá trị này dưới dạng String (ví dụ: "Chicago, IL"), dưới dạng giá trị LatLng hoặc dưới dạng đối tượng Place. Nếu sử dụng đối tượng Place (Đị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ừ các dịch vụ Mã hoá địa lý, Tìm kiếm địa điểm và Tự động hoàn thành địa điểm trong API Maps JavaScript. Để biết 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 phần Tự động hoàn thành địa điểm và chỉ đường.
  • destination (bắt buộc) chỉ định vị trí kết thúc để tính toán đường đi. Các tuỳ chọn này giống như đối với trường origin được mô tả ở trên.
  • travelMode (bắt buộc) chỉ định loại phương tiện sẽ 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 bên dưới.
  • transitOptions (không bắt buộc) chỉ định các giá trị chỉ áp dụng cho các yêu cầu mà travelMode là TRANSIT. Các giá trị hợp lệ được mô tả trong phần Tuỳ chọn vận chuyển 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 mà travelMode là DRIVING. Các giá trị hợp lệ được mô tả trong phần Tuỳ chọn lái xe bên dưới.

  • 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ệ đơn vị bên dưới.

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

    • location chỉ định vị trí của điểm trung gian dưới dạng LatLng, đối tượng Địa điểm hoặc String sẽ được mã hoá địa lý.
    • stopover là một boolean cho biết điểm trung gian là một điểm dừng trên tuyến đường, có tác dụng phân tách tuyến đường thành hai tuyến đường.

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

  • optimizeWaypoints (không bắt buộc) chỉ định rằng bạn có thể tối ưu hoá tuyến đường bằng cách sử dụng waypoints được cung cấp bằng cách sắp xếp lại các điểm trung gian theo thứ tự hiệu quả hơn. Nếu là true, dịch vụ Chỉ đường sẽ trả về waypoints đã 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 trung gian trong Tuyến đường bên dưới.)
  • provideRouteAlternatives (không bắt buộc) khi được đặt thành true chỉ định rằng dịch vụ Chỉ đường có thể cung cấp nhiều tuyến đường thay thế trong phản hồi. Xin lưu ý rằng việc cung cấp các tuyến đường thay thế có thể làm tăng thời gian phản hồi của máy chủ. Tính năng này chỉ dành cho các yêu cầu không có điểm trung gian.
  • avoidFerries (không bắt buộc) khi được đặt thành true cho biết rằng(các) tuyến đường được tính toán sẽ tránh phà nếu có thể.
  • avoidHighways (không bắt buộc) khi được đặt thành true cho biết(các) tuyến đường được tính toán sẽ tránh xa các đường cao tốc lớn, nếu có thể.
  • avoidTolls (không bắt buộc) khi được đặt thành true cho biết(các) tuyến đường được 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ã khu vực, được chỉ định dưới dạng giá trị gồm hai ký tự ccTLD ("miền cấp cao nhất"). (Để biết thêm thông tin, hãy xem phần Thiên vị theo 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 giao thông sẽ sử dụng. Các phương tiện di chuyển sau đây hiện được hỗ trợ:

  • DRIVING (Mặc định) cho biết đường đi 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 đi 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 các lối đi bộ và vỉa hè.

Hãy tham khảo Thông tin chi tiết về phạm vi cung cấp của Nền tảng Google Maps để xác định mức độ hỗ trợ thông tin chỉ đường của 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 đường đó, thì phản hồi sẽ trả về DirectionsStatus="ZERO_RESULTS".

Lưu ý: Thông tin 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, thông tin chỉ đường đi bộ sẽ trả về cảnh báo trong DirectionsResult. Người dùng phải luôn thấy các cảnh báo này. Nếu không sử dụng DirectionsRenderer mặc định, bạn có trách nhiệm đảm bảo cảnh báo xuất hiện.

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 tuỳ theo phương tiện di chuyển. Khi yêu cầu chỉ đường bằng phương tiện công cộng, các tuỳ 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 cụ thể cho quá trình chuyển đổi thông qua giá trị cố định đối tượng TransitOptions.

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

Biểu thức cố định đối tượng 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ì 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ể đưa trường này vào nếu yêu cầu có chứa khoá API. Mỗi TransitMode chỉ định một phương thức đi lại ưu tiên. Các giá trị sau đây được phép:
    • BUS cho biết rằng tuyến đường được tính toán sẽ ưu tiên đi bằng xe buýt.
    • RAIL cho biết rằng tuyến đường được tính toán nên ưu tiên đi bằng tàu, xe điện, tàu điện nhẹ và tàu điện ngầm.
    • SUBWAY cho biết rằng tuyến đường được 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 được tính toán sẽ ưu tiên đi bằng tàu.
    • TRAM cho biết rằng tuyến đường được tính toán nên ưu tiên đi bằng xe điện và tàu điện.
  • routingPreference (không bắt buộc) chỉ định các lựa chọn ưu tiên cho tuyến đường công cộng. Khi sử dụng tuỳ chọn này, bạn có thể thiên vị các tuỳ chọn được trả về thay vì chấp nhận tuyến đường tốt nhất mặc định do API chọn. Bạn chỉ có thể chỉ định trường này nếu yêu cầu có chứa khoá API. Các giá trị sau đây được phép:
    • FEWER_TRANSFERS cho biết tuyến đường được tính toán nên ưu tiên số lượng chuyến chuyển bị giới hạn.
    • LESS_WALKING cho biết tuyến đường được tính toán nên ưu tiên đi bộ ở mức hạn chế.

Dưới đây là ví dụ về DirectionsRequest 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
}

Các lựa chọn khi 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 đối với đối tượng cố định drivingOptions) 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ị thành thời gian hiện tại hoặc một thời điểm trong tương lai. Ngày này không được là ngày trong quá khứ. (API chuyển đổi tất cả ngày thành UTC để đảm bảo việc xử lý nhất quán trên các múi giờ.) Đối với khách hàng sử dụng Gói cao cấp của Nền tảng Google Maps, nếu bạn đưa departureTime vào yêu cầu, 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 dự đoán trong tình trạng giao thông (duration_in_traffic) trong phản hồi. Nếu bạn không chỉ định thời gian khởi hành (tức là nếu yêu cầu không bao gồm drivingOptions), thì tuyến đường được trả về thường là tuyến đường tốt 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 trong 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 mức trung bình trước đây. Giá trị mặc định là bestguess. Các giá trị sau đây được phép:
    • bestguess (mặc định) cho biết rằng duration_in_traffic được trả về phải là thời gian di chuyển ước tính tốt nhất dựa trên những gì đã biết về cả tình trạng giao thông trước đây và giao thông hiện tại. Lưu lượng truy cập trực tiếp càng quan trọng khi departureTime càng gần thời điểm hiện tại.
    • 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ế vào hầu hết các ngày, mặc dù đôi khi những ngày có điều kiện 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ế vào hầu hết các ngày, mặc dù đôi khi vào những ngày có điều kiện giao thông đặc biệt tốt, thời gian di chuyển 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ệ đơn vị

Theo mặc định, đường đi được tính toán và hiển thị bằng hệ đơn vị của quốc gia hoặc khu vực xuất phát. (Lưu ý: Điểm xuất phát được biểu thị bằng tọa độ vĩ độ/kinh độ thay vì địa chỉ luôn mặc định là đơn vị đo lường theo hệ mét.) Ví dụ: tuyến đường từ "Chicago, IL" đến "Toronto, ONT" sẽ hiển thị kết quả theo dặm, còn tuyến đường ngược lại sẽ hiển thị kết quả theo km. Bạn có thể ghi đè hệ thống đơn vị này bằng cách đặt một hệ thống đơn vị 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 thể hiện bằng kilômét.
  • UnitSystem.IMPERIAL chỉ định việc sử dụng hệ thống đo lường theo hệ thống Anh. Khoảng cách được thể hiện 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 hiển thị cho người dùng. Kết quả chỉ đường cũng chứa 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.

Khu vực thiên vị cho chỉ đường

Dịch vụ chỉ đường API Maps của Google trả về kết quả địa chỉ chịu ảnh hưởng của miền (khu vực hoặc quốc gia) mà bạn đã tải trình khởi động JavaScript. (Vì hầu hết người dùng tải https://maps.googleapis.com/, nên việc này sẽ đặt một miền ngầm ẩn thành Hoa Kỳ.) Nếu tải bootstrap từ một miền được hỗ trợ khác, bạn sẽ nhận được kết quả chịu ảnh hưởng của miền đó. Ví dụ: nội dung tìm kiếm "San Francisco" có thể trả về kết quả khác nhau khi ứng dụng tải https://maps.googleapis.com/ (Hoa Kỳ) so với khi 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ả thiên về một khu vực cụ thể bằng cách sử dụng tham số region. Tham số này lấy một mã khu vực, được chỉ định dưới dạng thẻ con khu vực Unicode gồm hai ký tự (không phải số). Trong hầu hết các trường hợp, các thẻ này liên kết trực tiếp đến các giá trị gồm hai ký tự của ccTLD ("miền cấp cao nhấ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. Đôi khi, mã này khác với giá trị ccTLD ("GB" cho "Vương quốc Anh", ví dụ:).

Khi sử dụng tham số region:

  • Chỉ chỉ định một quốc gia hoặc khu vực. Nhiều giá trị sẽ 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ụ theo khu vực gồm hai ký tự (định dạng Unicode CLDR). Tất cả dữ liệu đầu vào khác sẽ dẫn đến lỗi.

Tính năng thiên vị theo khu vực chỉ được hỗ trợ cho các quốc gia và khu vực hỗ trợ hướng. Hãy tham khảo Thông tin chi tiết về phạm vi cung cấp của Nền tảng Google Maps để xem phạm vi cung cấp quốc tế của API Chỉ đường.

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 cần truyền một lệnh gọi lại 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ột mã DirectionsResult và DirectionsStatus trong phản hồi.

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

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

  • OK cho biết phản hồi chứa một 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 xuất phát, điểm đến hoặc điểm trung gian của yêu cầu không thể được mã hoá địa lý.
  • ZERO_RESULTS cho biết không tìm thấy tuyến đường nào giữa điểm xuất phát và điểm đến.
  • MAX_WAYPOINTS_EXCEEDED cho biết rằng bạn đã cung cấp quá nhiều trường DirectionsWaypoint trong DirectionsRequest. Hãy xem phần dưới đây về các giới hạn đối với điểm trung gian.
  • MAX_ROUTE_LENGTH_EXCEEDED cho biết tuyến đường được yêu cầu quá dài và không thể xử lý. Lỗi này xảy ra khi các hướng phức tạp hơn được trả về. Hãy thử giảm số lượng điểm trung gian, lượt rẽ hoặc hướng dẫn.
  • INVALID_REQUEST cho biết rằng DirectionsRequest đã cung cấp không hợp lệ. Nguyên nhân phổ biến nhất gây ra mã lỗi này là các yêu cầu thiếu điểm xuất phát hoặc điểm đến, hoặc yêu cầu đi phương tiện công cộng có chứa các điểm trung gian.
  • 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. Bạn có thể tự xử lý hoặc chuyển kết quả đó đến đố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 trình kết xuất đó với bản đồ đã truyề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à 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 các thuộc tính của trình kết xuất và cập nhật bản đồ khi các hướng liên kết của trình kết xuất đó thay đổi.

Ví dụ sau đây tính toán đường đi giữa hai địa điểm trên Tuyến 66, trong đó điểm xuất phát và điểm đến được đặt bằng các giá trị "start" và "end" đã cho trong danh sách thả xuống. DirectionsRenderer xử lý việc hiển thị đa tuyến giữa các vị trí được chỉ định và vị trí đặt điểm đánh dấu tại điểm xuất phát, đích đến và mọi điểm trung gian (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 đường đi bằng nhiều phương tiện di chuyển khác nhau từ Haight-Ashbury đến Ocean Beach ở San Francisco, California:

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ị đường đa tuyến và mọi điểm đánh dấu liên quan, mà còn có thể xử lý việc hiển thị văn bản của chỉ đường dưới dạng một loạt các bước. Để làm điều 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 bản quyền thích hợp và mọi cảnh báo có thể liên quan đến kết quả.

Hướng dẫn dạng văn bản sẽ được cung cấp bằng cách sử dụng 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 JavaScript API bằng thông số language. (Để biết thêm thông tin, hãy xem phần Bản địa hoá.) Trong trường hợp chỉ đường bằng phương tiện công cộng, thời gian sẽ hiển thị theo múi giờ tại điểm dừng phương tiện công cộng đó.

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

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 một phản hồi bao gồm mã trạng thái và kết quả, là một đối tượng DirectionsResult. DirectionsResult là một giá trị cố định đối tượng 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 xuất phát, điểm đến và điểm trung gian.
  • routes[] chứa một mảng các đối tượng DirectionsRoute. Mỗi tuyến đường cho biết một cách để đi từ điểm xuất phát đến điểm đến được cung cấp trong DirectionsRequest. Nhìn chung, hệ thống chỉ trả về một tuyến cho bất kỳ yêu cầu cụ thể nào, trừ phi trường provideRouteAlternatives của yêu cầu được đặt thành true, trong đó có thể trả về nhiều tuyến.

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

Điểm trung gian được mã hoá địa lý trong chỉ đường

DirectionsGeocodedWaypoint chứa thông tin chi tiết về việc mã hoá địa lý của điểm xuất phát, điểm đến và điểm trung gian.

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 do thao tác liên kết đị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ý đã được tạo 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 trình mã hoá địa lý được truyền một address không tồn tại.

  • partial_match cho biết trình dịch đị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 một phần của đị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 hay không.

    Kết quả trùng khớp một phần thường xảy ra đối với những địa chỉ đường phố không tồn tại trong địa phương mà bạn truyền vào yêu cầu. Kết quả trùng 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ả đường Henry và Henrietta. Xin lưu ý rằng nếu một yêu cầu có thành phần địa chỉ bị sai chính tả, thì dịch vụ mã hoá địa lý có thể đề xuất một địa chỉ thay thế. Nội dung đề xuất được kích hoạt theo cách này cũng sẽ được đánh dấu là một kết quả trùng khớp một phần.

  • place_idlà giá trị nhận dạng duy nhất của một địa điểm, có thể được sử 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 để lấy 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à nhiều thông tin khác. Xem nội dung 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 0 hoặc nhiều thẻ xác định loại đối tượng được trả về trong kết quả. Ví dụ: mã địa lý của "Chicago" trả về "locality" (khu vực địa lý) cho biết "Chicago" là một thành phố và cũng trả về "political" (chính trị) cho biết đây là một thực thể chính trị.

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ừ đầu đến cuối, thay vì chỉ một chặng của chuyến đi mẹ.

DirectionsRoute chứa một kết quả duy nhất từ nguồn 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 (loại DirectionsLeg) tuỳ thuộc vào việc có điểm trung gian nào được chỉ định hay không. Ngoài ra, tuyến đường cũng chứa thông tin cảnh báo và bản quyền mà người dùng phải thấy 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. Sẽ có một chặng riêng cho từng điểm trung gian hoặc đích đến được chỉ định. (Một tuyến đường không có điểm trung gian sẽ chứa đúng một DirectionsLeg.) Mỗi chặng bao gồm một loạt DirectionStep.
  • waypoint_order chứa một mảng cho biết thứ tự của mọi điểm trung gian trong tuyến đường đã tính toán. 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 các LatLng đại diện cho một đường dẫn gần đúng (được làm mượt) của các hướng dẫn thu được.
  • overview_polyline chứa một đối tượng points duy nhất chứa đường đa tuyến được mã hoá đại diện cho tuyến đường. Đường đa tuyến này là đường dẫn gần đúng (được làm mượt) của các hướng dẫn thu được.
  • bounds chứa LatLngBounds cho biết ranh giới của đường đa tuyến tính dọc theo tuyến đường đã cho này.
  • copyrights chứa văn bản bản quyền sẽ được hiển thị cho tuyến đường này.
  • warnings[] chứa một mảng cảnh báo sẽ hiển thị khi hiển thị các hướng dẫn này. Nếu không sử dụng đối tượng DirectionsRenderer được cung cấp, bạn phải tự xử lý và hiển thị 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 tuyến đường này. Thuộc tính này chỉ được trả về cho các yêu cầu đi phương tiện công cộng và chỉ dành cho các tuyến có thông tin về giá vé cho tất cả các chặng đi bằng phương tiện công cộng. Thông tin này bao gồm:

Chân chỉ đường

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

DirectionsLeg xác định một chặng duy nhất của hành trình từ điểm xuất phát đến điểm đến trong tuyến đường đã tính. Đối với các tuyến không chứa điểm trung gian, tuyến sẽ bao gồm một "đoạn" duy nhất, nhưng đối với các tuyến xác định một hoặc nhiều điểm trung gian, tuyến sẽ bao gồm một hoặc nhiều đoạn, tương ứng với các đoạn cụ thể của hành trình.

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

  • steps[] chứa một mảng các đối tượng DirectionsStep biểu thị thông tin về từng bước riêng biệt của chặng hành trình.

  • distance cho biết tổng quãng đường mà chặng này đã đi qua, dưới dạng một đố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, khoảng cách này được hiển thị theo đơn vị được sử dụng tại gốc. (Ví dụ: dặm sẽ được dùng cho mọi điểm xuất phát trong Hoa Kỳ.) Bạn có thể ghi đè hệ thống đơn vị này bằng cách đặt cụ thể UnitSystem trong truy vấn ban đầu. Xin lưu ý rằng bất kể bạn sử dụng hệ đơ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ể không được xác định nếu không biết khoảng cách.

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

    • value cho biết thời lượng tính bằng giây.
    • text chứa một chuỗi biểu thị thời lượng.

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

  • duration_in_traffic cho biết tổng thời lượng của chặng này, có tính đến tình trạng 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 đều đúng:

    • Yêu cầu không bao gồm các điểm dừng trung gian. Tức là không bao gồm các điểm trung gian mà stopover là true.
    • Yêu cầu này dành riêng cho chỉ đường lái xe – mode được đặt thành driving.
    • departureTime được đưa vào trường drivingOptions trong yêu cầu.
    • Có thông tin về tình trạng giao thông cho tuyến đường đã 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 nội dung biểu thị thời lượng mà con người đọc được.
  • arrival_time chứa thời gian đến dự kiến cho chặng này. Thuộc tính này chỉ được trả về cho đường đi bằng phương tiện công cộng. Kết quả được trả về dưới dạng đối tượng Time có ba thuộc tính:
    • value thời gian được chỉ định dưới dạng đối tượng Date của JavaScript.
    • text thời gian được chỉ định dưới dạng một chuỗi. Thời gian được hiển thị theo múi giờ của điểm dừng phương tiện công cộng.
    • time_zone chứa múi giờ của đài này. Giá trị này là tên của múi giờ được xác định trong Cơ sở dữ liệu múi giờ IANA, ví dụ: "Hoa Kỳ/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ỉ có sẵn cho chỉ dẫn phương tiện công cộng.
  • start_location chứa LatLng của điểm xuất phát của chặng 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à đường) tại điểm xuất phát và điểm cuối, nên start_location có thể khác với điểm xuất phát được cung cấp của chặng này nếu, ví dụ: đường không ở gần điểm xuất phát.
  • end_location chứa LatLng của đích đến của chặng 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à đường) tại điểm bắt đầu và điểm cuối, nên end_location có thể khác với đích đến được cung cấp của chặng này nếu, ví dụ: đường không ở gần đích đến.
  • start_address chứa địa chỉ mà con người đọc được (thường là địa chỉ đường phố) của điểm bắt đầu chặng này.

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

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

Các bước chỉ đường

DirectionsStep là đơn vị nguyên tử nhất của tuyến đường đi, chứa một bước mô tả một hướng dẫn cụ thể trên hành trình. Ví dụ: "Rẽ trái tại W. 4th St." 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 mối liên hệ giữa bước này với 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 lượng là "37 dặm" và "40 phút", cho biết 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 các bước sẽ bao gồm thêm Thông tin cụ thể về phương tiện công cộng ở dạng đối tượng transit. Nếu đường đi bao gồm nhiều phương tiện giao thông, thì đườ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 đường đi từ vị trí bắt đầu và kết thúc: "Đi bộ đến Innes Ave & Fitch St". Bước đó sẽ bao gồm hướng dẫn đi bộ chi tiết cho tuyến đường đó trong mảng steps[], chẳng hạn như: "Hướng tây bắc", "Rẽ trái vào Arelious Walker" và "Rẽ trái vào Innes Ave".

DirectionsStep là một giá trị cố định đối tượng 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 đã đi được 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 biết khoảng cách.
  • duration chứa thời gian ước tính cần thiết để thực hiện bước này 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 biết thời lượng.
  • start_location chứa LatLng được mã hoá địa lý của điểm bắt đầu của bước này.
  • end_location chứa LatLng của điểm kết thúc bước này.
  • polyline chứa một đối tượng points duy nhất chứa đường đa tuyến được mã hoá đại diện cho bước. Đường đa tuyến này là đường dẫn gần đúng (đã làm mượt) của bước.
  • steps[] một giá trị cố định đối tượng DirectionsStep chứa thông tin chỉ dẫn chi tiết về các bước đi bộ hoặc lái xe theo hướng đi phương tiện công cộng. Các bước phụ chỉ có sẵn cho chỉ dẫn đi bằng phương tiện công cộng.
  • travel_mode chứa TravelMode được dùng trong bước này. Đường đi bằng phương tiện công cộng có thể bao gồm cả đường đi bộ và đường đi 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 tuyến phương tiện công cộng.

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

Thông tin chỉ đường bằng phương tiện công cộng trả về thông tin bổ sung không liên quan đến các phương tiện giao thông 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 vào thông tin bổ sung cho các đối tượng TransitStop, TransitLine, TransitAgency và VehicleType như mô tả bên dưới.

Thông tin chi tiết 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ụ: "Union Square".
    • 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 đối tượng TransitStop đại diện cho ga/điểm xuất phát.
  • arrival_time chứa thời gian đến, được chỉ định dưới dạng đối tượng Time có ba thuộc tính:
    • value thời gian được chỉ định dưới dạng đối tượng Date của JavaScript.
    • text thời gian được chỉ định dưới dạng một chuỗi. Thời gian được hiển thị theo múi giờ của điểm dừng phương tiện công cộng.
    • time_zone chứa múi giờ của đài này. Giá trị này là tên của múi giờ được xác định trong Cơ sở dữ liệu múi giờ IANA, ví dụ: "Hoa Kỳ/New_York".
  • departure_time chứa thời gian khởi hành, được chỉ định dưới dạng đối tượng Time.
  • headsign chỉ định hướng di chuyển trên tuyến này, như được đánh dấu trên xe hoặc tại điểm dừng khởi hành. Đây thường là ga cuối.
  • headway (nếu có) chỉ đị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 đợi 10 phút nếu bị lỡ chuyến xe buýt.
  • line chứa một giá trị cố định đối tượng TransitLine chứa thông tin về tuyến phương tiện công cộng được sử 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 TransitLine.
  • num_stops chứa số lượng điểm dừng trong bước này. Bao gồm điểm đến nhưng không bao gồm điểm khởi hành. Ví dụ: nếu hướng dẫn của bạn bao gồm việc rời khỏi Điểm dừng A, đi qua các điểm dừng B và C rồi đến điểm dừng D, thì num_stops sẽ trả về 3.

Đường phương tiện

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

  • name chứa tên đầy đủ của tuyến phương tiện công cộng này. Ví dụ: "7 Avenue Express" hoặc "14th St Crosstown".
  • short_name chứa tên ngắn của tuyến phương tiện công cộng 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. Đố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ị hướng dẫn đ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 công cộng cung cấp kết quả chuyến đi.

  • url chứa URL cho tuyến phương tiện công cộng này do cơ quan vận tải công cộng cung cấp.
  • icon chứa URL của 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 biểu tượng chung 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 chỉ định dưới dạng chuỗi hex, chẳng hạn như: #FF0033.
  • text_color chứa màu văn bản thường dùng để gắn biển báo cho dòng này. Màu sẽ được chỉ định dưới dạng chuỗi thập lục phân.
  • vehicle chứa một đối tượng Vehicle bao gồm các thuộc tính sau:
    • name chứa tên của xe trên tuyến này. Ví dụ: "Tàu điện ngầm."
    • type chứa loại xe được sử dụng trên tuyến này. Hãy 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 của biểu tượng thường được liên kết với loại xe này.
    • local_icon chứa URL của biểu tượng liên kết với loại xe này, dựa trên biển báo phương tiện 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 Đường sắt đô thị.
VehicleType.SUBWAY Xe điện ngầm.
VehicleType.TRAM Xe điện trên mặt đất.
VehicleType.MONORAIL Tàu một ray.
VehicleType.HEAVY_RAIL Đường sắt nặng.
VehicleType.COMMUTER_TRAIN Tàu chở khách đ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 bánh hơi.
VehicleType.SHARE_TAXI Xe taxi đi chung là một loại xe buýt có khả năng trả và đón khách ở bất cứ đâu trên tuyến đường của xe.
VehicleType.FERRY Phà.
VehicleType.CABLE_CAR Xe hoạt động trên cáp, thường là trên mặt đất. Cáp treo có thể thuộc loại VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Một chiếc cáp treo trên không.
VehicleType.FUNICULAR Một chiếc xe được kéo lên dốc bằng cáp. Tàu điện trên cáp thường bao gồm hai toa, mỗi toa đóng vai trò là đối trọng cho toa còn lại.
VehicleType.OTHER Tất cả các loại xe khác sẽ trả về loại này.

Kiểm tra DirectionsResults

Bạn có thể kiểm tra và sử dụng các thành phần DirectionsResults – DirectionsRoute, DirectionsLeg, DirectionsStep và TransitDetails – 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ị hướng dẫn đi bằng 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 công cộng cung cấp kết quả chuyến đi.

Ví dụ sau đây vẽ đường đi bộ đến một số điểm tham quan du lịch ở 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ì đang tính toán đường đi bộ, nên chúng ta cũng 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 trung gian trong Tuyến

Như đã lưu ý trong DirectionsRequest, bạn cũng có thể chỉ định điểm trung gian (loại DirectionsWaypoint) khi tính toán tuyến đường bằng cách sử dụng dịch vụ Chỉ đường cho đường đi bộ, đường đi xe đạp hoặc đường đi xe. Bạn không thể thêm điểm trung gian cho đường đi bằng phương tiện công cộng. Điểm trung gian cho phép bạn tính toán tuyến đường thông qua các vị trí bổ sung, trong trường hợp này, tuyến đường được trả về sẽ đi qua các điểm trung gian đã cho.

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

  • location (bắt buộc) chỉ định địa chỉ của điểm trung gian.
  • stopover (không bắt buộc) cho biết liệu điểm trung gian này có phải là điểm dừng thực tế trên tuyến đường (true) hay không, hoặc chỉ là một lựa chọn ưu tiên để định tuyến qua vị trí đã chỉ định (false). Theo mặc định, điểm dừng là true.

Theo mặc định, dịch vụ Chỉ đường sẽ tính toán một tuyến đường thông qua các điểm trung gian được cung cấp theo thứ tự đã cho. Bạn có thể truyền optimizeWaypoints: true trong DirectionsRequest (không bắt buộc) để cho phép dịch vụ Chỉ đường tối ưu hoá tuyến đường được cung cấp bằng cách sắp xếp lại các điểm trung gian theo thứ tự hiệu quả hơn. (Phương pháp tối ưu hoá này là một ứng dụng của vấn đề người bán hàng đi lại.) Thời gian di chuyển là yếu tố chính được tối ưu hoá, nhưng các yếu tố khác như khoảng cách, số lượt rẽ và nhiều yếu tố khác có thể được xem xét khi quyết định tuyến đường nào hiệu quả nhất. Tất cả điểm trung gian phải là điểm dừng để dịch vụ Chỉ đường có thể tối ưu hoá tuyến đườ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 trung gian, thì thứ tự của các điểm trung gian đó 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 Hoa Kỳ bằng nhiều điểm xuất phát, điểm cuối và điểm trung gian. (Để chọn nhiều điểm trung gian, hãy nhấn tổ hợp 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à điểm cuối 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à quy định hạn chế đối với điểm trung gian

Các giới hạn và quy định hạn chế về việc sử dụng sau đây sẽ được áp dụng:

  • Số lượng điểm trung gian tối đa được phép khi sử dụng dịch vụ Đường đi trong API JavaScript của Maps là 25, cộng với điểm xuất phát và điểm đến. Các giới hạn này cũng áp dụng cho dịch vụ web API Địa chỉ.
  • Đối với Dịch vụ web API chỉ đường, khách hàng được phép sử dụng 25 điểm trung gian, cộng với điểm xuất phát và điểm đến.
  • Khách hàng sử dụng Gói đặc biệt của Nền tảng Google Maps được phép sử dụng 25 điểm trung gian, cùng với điểm xuất phát và điểm đến.
  • Điểm trung gian không được hỗ trợ cho chỉ đường bằng phương tiện công cộng.

Chỉ đường có thể kéo

Người dùng có thể sửa đổi hướng đi bằng xe đạp, đi bộ hoặc lái xe được hiển thị bằng cách sử dụng DirectionsRenderer một cách linh động nếu các hướng đi đó có thể kéo, 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 thu được trên bản đồ. Bạn cho biết màn hình của 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 thành true. Không thể kéo đường đi bằng phương tiện công cộng.

Khi có thể kéo đường đi, người dùng có thể chọn bất kỳ điểm nào trên đường dẫn (hoặc điểm trung gian) của kết quả hiển thị 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 để hiển thị đường dẫn đã sửa đổi. Sau khi phát hành, một điểm trung gian chuyển đổi sẽ được thêm vào bản đồ (được biểu thị bằng một điểm đánh dấu màu trắng nhỏ). Thao tác chọn và di chuyển một đoạn đường dẫn sẽ thay đổi chặng đó của tuyến đường, trong khi thao tác chọn và di chuyển điểm đánh dấu waypoint (bao gồm cả điểm bắt đầu và điểm kết thúc) sẽ thay đổi các chặng của tuyến đường đi qua waypoint đó.

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

Mã sau đây cho thấy một chuyến đi từ Perth ở bờ biển phía tây của Úc đến Sydney ở bờ biển phía đô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