Dịch vụ chỉ đường (Cũ)

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)
Lưu ý: Thư viện phía máy chủ

Tổng quan

Bạn có thể tính toán đường đi (bằng nhiều phương thức vận 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. Dịch vụ này nhận các yêu cầu chỉ đường và trả về một tuyến đường 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ề thông tin chỉ đường gồm nhiều phần bằng cách sử dụng một loạt điểm tham chiếu. Đường đi được hiển thị dưới dạng một 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ụ: "Rẽ 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 Directions API (Cũ) trong Google Cloud Console, trong cùng một dự án mà 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 Chọn một dự án, sau đó chọn cùng một dự án mà bạn đã thiết lập cho Maps JavaScript API 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 (Cũ).
  4. Nếu bạn thấy API đó trong danh sách, thì bạn không cần làm gì thêm. Nếu API không có trong danh sách, hãy bật API tại https://console.cloud.google.com/apis/library/directions-backend.googleapis.com

Giá và chính sách

Giá

Để tìm hiểu về chính sách giá và mức sử dụng cho dịch vụ Chỉ đường JavaScript, hãy xem phần Mức sử dụng và thanh toán cho API Chỉ đường (Cũ).

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 Directions API (Cũ).

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 gọi lại để thực thi 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ụ đường đi có thể trả về nhiều hành trình có thể có dưới dạng một mảng routes[] riêng biệt.

Để sử dụng đường đi 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ụ Đường đi, truyền cho dịch vụ này một đối tượng chữ 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.

Đối tượng chữ 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ụ: "Chicago, IL"), dưới dạng giá trị LatLng hoặc dưới dạng đối tượng Địa điểm. Nếu sử dụng đối tượng Place, 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à Place Autocomplete trong Maps JavaScript API. Để xem ví dụ về cách sử dụng mã địa điểm từ tính năng Place Autocomplete, hãy xem phần Place Autocomplete 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 với các tuỳ chọn cho trường origin được mô tả ở trên.
  • travelMode (bắt buộc) chỉ định phương thức vận chuyển 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 Phương thức di chuyển bên dưới.
  • transitOptions (không bắt buộc) chỉ định các giá trị chỉ áp dụng cho những yêu cầu có travelMode là TRANSIT. Các giá trị hợp lệ được mô tả trong phần Lựa 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 những 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 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 phần Hệ thống đơn vị bên dưới.

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

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

    (Để 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 đường bên dưới.)

  • optimizeWaypoints (không bắt buộc) chỉ định rằng tuyến đường sử dụng waypoints được 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 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 tham chiếu trong tuyến đường bên dưới.)
  • provideRouteAlternatives (không bắt buộc) khi được đặt thành true, thuộc tính này 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ỉ áp dụng 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 được đặt thành true cho biết rằng(các) tuyến đường được tính toán nên tránh phà, nếu có thể.
  • avoidHighways (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 nên tránh các đường cao tốc chính, nếu có thể.
  • avoidTolls (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 nên 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 Xu hướng theo khu vực bên dưới.)

Dưới đây là một 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
}

Chế độ di chuyển

Khi tính toán đường đi, bạn cần chỉ định phương tiện đi lại sẽ sử dụng. Các phương thức di chuyển sau đây hiện được hỗ trợ:

  • DRIVING (Mặc định) cho biết đường lái xe tiêu chuẩn sử dụng mạng lưới đườ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 đường dành cho người đi bộ và vỉa hè.

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

Lưu ý: Đường đi bộ có thể không bao gồm đường đi bộ rõ ràng, vì vậy, đườ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, bạn có trách nhiệm đảm bảo các cảnh báo được hiển thị.

Lựa chọ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 thức di chuyển. Khi yêu cầu đường đi 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 lựa chọn định tuyến cụ thể cho phương tiện công cộng thông qua đối tượng chữ TransitOptions.

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

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

Dưới đây là ví dụ về DirectionsRequest theo 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 lựa chọn định tuyến cho đườ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 tượng chữ drivingOptions hợp lệ) chỉ định thời gian khởi hành mong muốn dưới dạng đối tượng Date. Giá trị phải được đặt thành thời gian hiện tại hoặc một thời điểm nào đó trong tương lai. Ngày này không được là ngày trong quá khứ. (API này chuyển đổi tất cả ngày sang giờ UTC để đảm bảo 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 Google Maps Platform cao cấp, nếu bạn thêm 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 dự kiế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 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 toán thời gian trong tình trạng giao thông. 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 được cho phép:
    • bestguess (mặc định) cho biết rằng duration_in_traffic được trả về phải là giá trị ướ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à tình trạng giao thông theo thời gian thực. Lưu lượng truy cập trực tiếp càng quan trọng hơn khi departureTime càng gần với thời điểm hiện tại.
    • pessimistic cho biết 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ù đôi khi có 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 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ù đôi khi có những ngày có tình trạng giao thông đặc biệt thuận lợi có thể nhanh hơn giá trị này.

Dưới đây là DirectionsRequest mẫu cho đườ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 toạ độ vĩ độ/kinh độ thay vì địa chỉ luôn mặc định là đơn vị hệ mét.) Ví dụ: một 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ả theo km. Bạn có thể ghi đè hệ thống đơn vị này bằng cách đặt rõ ràng một hệ thống đơn vị trong yêu cầu bằng một trong các giá trị UnitSystem sau:

  • UnitSystem.METRIC chỉ định việc sử dụng hệ mét. Khoảng cách được hiển thị bằng đơn vị km.
  • UnitSystem.IMPERIAL chỉ định việc sử dụng hệ đo lường Anh. Khoảng cách được hiển thị bằng đơn vị 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) luôn được biểu thị bằng mét.

Thiên vị khu vực cho đường đi

Dịch vụ chỉ đường của API Google Maps 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 tệp khởi động JavaScript. (Vì hầu hết người dùng đều tải https://maps.googleapis.com/, nên miền ngầm định sẽ được đặt thành Hoa Kỳ.) Nếu tải tệp khởi động 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 giữa ứng dụng tải https://maps.googleapis.com/ (Hoa Kỳ) và ứng dụng 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ã khu vực, được chỉ định dưới dạng thẻ phụ 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, những thẻ này liên kết trực tiếp với các giá trị gồm hai ký tự của ccTLD ("tên 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 khác với giá trị ccTLD (ví dụ: "GB" cho "Vương quốc Anh").

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ụ vùng gồm hai ký tự (định dạng Unicode CLDR). Tất cả cá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ợ đường đi. Tham khảo Thông tin chi tiết về phạm vi cung cấp của Google Maps Platform để xem phạm vi cung cấp trên toàn thế giới của Directions API (Phiên bản cũ).

Đang hiển thị đường đi

Để 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 thực thi 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 DirectionsResult và một mã 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 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 tham chiếu 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 có quá nhiều trường DirectionsWaypoint được cung cấp trong DirectionsRequest. Xem phần bên dưới về giới hạn đối với điểm tham chiếu.
  • 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 hệ thống trả về thông tin đường đi phức tạp hơn. Hãy thử giảm số lượng điểm tham chiếu, ngã rẽ hoặc chỉ dẫn.
  • INVALID_REQUEST cho biết rằng DirectionsRequest được 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à do yêu cầu thiếu điểm xuất phát hoặc điểm đến, hoặc yêu cầu về phương tiện công cộng có chứa đ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 phía 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 đường đi đã 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 đường đi mà bạn có thể tự xử lý hoặc chuyển đế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 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 sẽ tự động phát hiện mọi thay đổi đối với các thuộc tính của nó và cập nhật bản đồ khi đường đi 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 xuất phát và điểm đến được đặt theo 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 xuất phát, điểm đến và mọi điểm tham chiếu (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 giữa Haight-Ashbury và 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ị 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ị văn bản của đường đi dưới dạng một loạt các bước. Để làm việc này, hãy gọi setPanel() trên DirectionsRenderer, truyền <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 phù hợp và mọi cảnh báo có thể liên quan đến kết quả.

Đường đi bằ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 tham số language. (Để biết thêm thông tin, hãy xem phần Bản địa hoá). Trong trường hợp đường đi bằng 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 phương tiện công cộng đó.

Ví dụ sau đây giống hệt với ví dụ ở trên, nhưng có thêm 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ã trạng thái và kết quả, là một đối tượng DirectionsResult. DirectionsResult là một đối tượng chữ 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ề mã hoá địa lý của điểm xuất phát, điểm đến và điểm tham chiếu.
  • routes[] chứa một mảng gồm 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, chỉ có một tuyến đường được trả về cho bất kỳ yêu cầu nào, trừ phi trường provideRouteAlternatives của yêu cầu được đặt thành true. Trong trường hợp này, nhiều tuyến đường có thể được trả về.

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 thêm điểm tham chiếu bổ sung trong các tuyến đường thay thế. Đối với các phiên bản 3.28 trở lên của API, bạn có thể tiếp tục triển khai đường đi có thể kéo bằ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ỉ có thể kéo tuyến đường chính. Người dùng có thể kéo tuyến đường chính cho đến khi tuyến đường đó khớp với một tuyến đường thay thế.

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

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

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

  • geocoder_status cho biết mã trạng thái do 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 rằng mã hoá đị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 truyề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 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 đầy đủ hay không.

    Kết quả 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 chuyển trong 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ả Henry Street và Henrietta Street. Xin lưu ý rằng nếu một yêu cầu có chứa thành phần địa chỉ bị viết sai chính tả, thì dịch vụ mã hoá đị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à kết quả trùng khớp một phần.

  • place_id là giá trị nhận dạng riêng biệt của một địa điểm, có thể dùng được với các API khác của Google. Ví dụ: bạn có thể sử dụng place_id cùng với thư viện Google Places API để 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 không hoặc nhiều thẻ xác định loại đối tượng địa lý được trả về trong kết quả. Ví dụ: mã địa lý của "Chicago" trả về "locality" (địa phương) cho biết "Chicago" là một thành phố, đồng thời trả về "political" (chính trị) cho biết đây là một thực thể chính trị.

Tuyến đường đi

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, chứ không chỉ đơn giản là một chặng của chuyến đi chính.

DirectionsRoute chứa một kết quả duy nhất từ điểm khởi hành và điểm đến được 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 cũng chứa thông tin về bản quyền và cảnh báo mà bạn phải hiển thị cho người dùng, bên cạnh thông tin định tuyến.

DirectionsRoute là một đối tượng chữ 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ặng riêng biệt sẽ xuất hiện cho mỗi điểm tham chiếu hoặc điểm đến được chỉ định. (Một tuyến đường không có điểm tham chiếu 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 tham chiếu trong tuyến đường được 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 LatLng đại diện cho đường đi gần đúng (đã được làm mượt) của đường đi thu được.
  • overview_polyline chứa một đối tượng points duy nhất, trong đó có một biểu diễn hình nhiều đường được mã hoá của tuyến đường. Hình nhiều đường này là một đường gần đúng (đã được làm mượt) của đường đi thu được.
  • bounds chứa LatLngBounds cho biết ranh giới của hình nhiều đường dọc theo tuyến đường 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 các đường đi 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 về phương tiện công cộng và chỉ cho những tuyến đường có thông tin về giá vé cho tất cả các chặng phương tiện công cộng. Thông tin này bao gồm:

Chặng đường đi

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 được tính toán. Đối với các tuyến đường không có điểm tham chiếu, tuyến đường sẽ bao gồm một "chặng" duy nhất, nhưng đố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ẽ bao gồm một hoặc nhiều chặng, tương ứng với các chặng cụ thể của hành trình.

DirectionsLeg là một đối tượng chữ 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 của chặng này, dưới dạng đối tượng Distance có dạng như sau:

    • value cho biết khoảng cách tính bằng mét
    • text chứa một chuỗi biểu thị 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 điểm xuất phát. (Ví dụ: dặm sẽ được dùng cho mọi điểm xuất phát ở Hoa Kỳ.) Bạn có thể ghi đè hệ thống đơn vị này bằng cách đặt cụ thể một 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ể 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 đều đúng:

    • Yêu cầu không bao gồm điểm tham chiếu dừng chân. Tức là, tuyến đường này không bao gồm các điểm tham chiếu có stopover là true.
    • Yêu cầu này dành riêng cho đường lái xe – mode được đặt thành driving.
    • departureTime được đưa vào dưới dạng một phần của trường drivingOptions trong yêu cầu.
    • Có thông tin về tình trạng giao thông 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 giá trị 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 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 JavaScript.
    • 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 trạm 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ờ được xác định trong Cơ sở dữ liệu múi giờ IANA, ví dụ: "America/New_York".
  • departure_time chứa thời gian khởi hành ước tính 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 đ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 lựa chọn phương tiện giao thông gần nhất (thường là đường bộ) tại điểm xuất phát và điểm kết thúc, 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 bộ không ở gần điểm xuất phát.
  • end_location chứa LatLng của điểm đế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 di chuyển gần nhất (thường là đường bộ) tại điểm xuất phát và điểm kết thúc, nên end_location có thể khác với điểm đến được cung cấp của chặng này nếu, ví dụ: đường bộ 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ố) của điểm bắt đầu chặng này.

    Nội dung này được dùng để đọc nguyên trạng. Đừng phân tích cú pháp địa chỉ được định dạng theo phương thức 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ố) của điểm cuối chặng này.

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

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

DirectionsStep là đơn vị nhỏ nhất của một tuyến đường trong chỉ đường, chứa một bước duy nhất mô tả một chỉ dẫn cụ thể trong 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 quan 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à "Nhập vào I-80 West" có thể chứa thời lượng "37 dặm" và "40 phút", cho biết bước tiếp theo cách bước này 37 dặm/40 phút.

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ông tin cụ thể về phương tiện công cộng bổ sung dưới dạng đối tượng transit. Nếu đường đi bao gồm nhiều phương thức di chuyển, 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 chỉ đường từ vị trí bắt đầu và kết thúc: "Đi bộ đến Innes Ave & Fitch St". Bước đó sẽ bao gồm đườ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", "Rẽ trái vào Arelious Walker" và "Rẽ trái vào Innes Ave".

DirectionsStep là một đối tượng chữ 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 quãng đường 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 được xác định nếu không biết 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 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 được 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 của bước này.
  • polyline chứa một đối tượng points duy nhất, trong đó có một biểu diễn hình nhiều đường được mã hoá của bước. Hình nhiều đường này là đường dẫn gần đúng (đã được làm mượt) của bước.
  • steps[] một đối tượng chữ DirectionsStep chứa thông tin chi tiết về đường đi cho các bước đi bộ hoặc lái xe trong đường đi bằng phương tiện công cộng. Các bước phụ chỉ có trong đường đ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ả quá 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à đi, 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

Đường đi 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 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 vào thông tin bổ sung cho các đối tượng TransitStop, TransitLine, TransitAgency và VehicleType như mô tả dưới đây.

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 có các thuộc tính sau:
    • name tên của trạm phương tiện công cộng/điểm dừng. Ví dụ: "Quảng trường Thống nhất".
    • location vị trí của trạm phương tiện công cộng/điểm dừ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 dừng khởi hành.
  • 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 JavaScript.
    • 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 trạm 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ờ được xác định trong Cơ sở dữ liệu múi giờ IANA, ví dụ: "America/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 phương tiện hoặc tại điểm dừng khởi hành. Đây thường là ga cuối.
  • headway nếu có, giá trị này 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 lỡ chuyến xe buýt.
  • line chứa một đối tượng chữ 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à nhà điều hành của tuyến, 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ố điểm dừng trong bước này. Bao gồm điểm dừng đến, nhưng không bao gồm điểm dừng đi. Ví dụ: nếu chỉ 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ố tuyến, 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ề nhà điều hành tuyến 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 bạn đang kết xuất đường đ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, thì bạn phải hiển thị tên và URL của các công ty vận tải cung cấp dịch vụ cho kết quả chuyến đi.

  • url chứa URL của tuyến phương tiện công cộng 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 biểu tượng chung, thay đổi 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 thập lục phân, chẳng hạn như: #FF0033.
  • text_color chứa màu văn bản thường dùng cho biển báo của tuyến 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 dòng này. Ví dụ: "Subway".
    • type chứa loại phương tiện đượ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 liên kết với loại phương tiện này.
    • local_icon chứa URL của biểu tượng liên kết với loại phương tiện này, dựa trên biển báo giao thông tại đị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 Xe điện.
VehicleType.SUBWAY Xe điện ngầm.
VehicleType.TRAM Xe điện trên mặt đất.
VehicleType.MONORAIL Tàu điện một ray.
VehicleType.HEAVY_RAIL Tàu điện hạng nặng.
VehicleType.COMMUTER_TRAIN Tàu chở khách đi làm.
VehicleType.HIGH_SPEED_TRAIN Tàu cao tốc.
VehicleType.BUS Doanh nghiệp.
VehicleType.INTERCITY_BUS Xe buýt liên tỉnh.
VehicleType.TROLLEYBUS Xe buýt điện.
VehicleType.SHARE_TAXI Xe taxi đi chung là một loại xe buýt có thể đón và trả khách ở bất cứ đâu trên tuyến đường của xe.
VehicleType.FERRY Phà.
VehicleType.CABLE_CAR Phương tiện vận hành bằng 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 Cáp treo trên không.
VehicleType.FUNICULAR Một chiếc xe được kéo lên dốc cao bằng cáp. Một tuyến cáp treo thường bao gồm hai toa, trong đó mỗi toa đóng vai trò là đối trọng cho toa kia.
VehicleType.OTHER Tất cả các phương tiện khác sẽ trả về loại này.

Kiểm tra DirectionsResults

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 nào về đường đi.

Quan trọng: Nếu bạn đang kết xuất đường đ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, thì bạn phải hiển thị tên và URL của các công ty vận tải cung cấp kết quả về 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 tôi 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 bằng 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 tôi 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 biệt.

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 đ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 đường đi bộ, đi xe đạp hoặc lái xe. Không thể sử dụng điểm tham chiếu cho đường đi bằng phương tiện công cộng. Điểm tham chiếu cho phép bạn tính toán tuyến đường qua các vị trí bổ sung, trong trường hợp đó, tuyến đường được trả về sẽ đi qua các điểm tham chiếu đã cho.

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 có phải là đ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 để định tuyến qua vị trí được chỉ định (false). Điểm dừng là true theo mặc định.

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 tham chiếu được cung cấp theo thứ tự đã cho. 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 được 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. (Cách tối ưu hoá này là một ứng dụng của bài toán người bán hàng.) 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 là hiệu quả nhất. Tất cả điểm tham chiếu phải là điểm dừng để dịch vụ Chỉ đường 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 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 kết thúc và điểm tham chiếu. (Để chọn nhiều điểm tham chiếu, hãy nhấn Ctrl-Click khi chọn các mục trong danh sách.) 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 kết thúc của mỗi tuyến đường.

TypeScript

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

  directionsRenderer.setMap(map);

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

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

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

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

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

      summaryPanel.innerHTML = "";

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

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

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

JavaScript

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

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

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

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

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

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

      summaryPanel.innerHTML = "";

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

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

window.initMap = initMap;

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

Các giới hạn và quy định hạn chế sau đây về việc sử dụng 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 xuất phát và điểm đến. Các giới hạn này giống với giới hạn của dịch vụ web Directions API (Phiên bản cũ).
  • Đối với dịch vụ web Directions API (Phiên bản cũ), khách hàng được phép sử dụng 25 điểm tham chiếu, cộng với điểm xuất phát và điểm đến.
  • Khách hàng sử dụng Gói cao cấp của Google Maps Platform đượ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 đường đi bằng phương tiện công cộng.

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

Người dùng có thể sửa đổi đường đi xe đạp, đi bộ hoặc đường lái xe được hiển thị bằng cách sử dụng DirectionsRenderer một cách linh hoạt nếu các đường này có thể kéo được, 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 kết quả trên bản đồ. Bạn cho biết liệu màn hình của trình kết xuất có cho phép chỉ đườ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 đi (hoặc điểm tham chiếu) của kết quả được 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 để cho thấy đường dẫn đã sửa đổi. Khi bạn thả ra, 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 sẽ thay đổi chặng đó của tuyến đường, trong khi việc chọn và di chuyển điểm đánh dấu điểm tham chiếu (bao gồm cả điểm xuất phát và điểm kết thúc) sẽ thay đổi các chặng của tuyến đường đi qua điểm tham chiếu đó.

Vì đường đi có thể kéo được sửa đổi và hiển thị phía máy khách, nên bạn có thể muố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 đường đi hiển thị.

Đoạn 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 giám sát 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;

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