Dịch vụ chỉ đường

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 di chuyển) bằng cách sử dụng đối tượng DirectionsService. Đối tượng này giao tiếp với Dịch vụ chỉ đường của Google Maps, 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 bắt đầu hoặc điểm đến trong một 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, Úc"), giá trị LatLng hoặc đối tượng Place.

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 các điểm tham chiếu. Đường đi được hiển thị dưới dạng một bản vẽ đường nhiều đoạn 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 đường dẫn lên 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 Directions API (cũ) 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 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 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à sử dụng cho dịch vụ Chỉ đường bằng JavaScript, hãy xem phần Sử dụng và thanh toán cho Directions API (Phiên bản cũ).

Chính sách

Bạn phải sử dụng dịch vụ Chỉ đường theo các chính sách được mô tả cho Directions API (phiên bản cũ).

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

Việc truy cập vào dịch vụ Đường đi là không đồng bộ, vì Google Maps API cần thực hiện một lệnh gọi đến 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 yêu cầu hoàn tất. 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 Maps JavaScript API, hãy tạo một đối tượng thuộc loại DirectionsService và gọi DirectionsService.route() để bắt đầu một yêu cầu đến dịch vụ Chỉ đường, truyền cho dịch vụ này một ký tự đối tượng 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 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 chỉ đường. 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, 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ụ sử dụng mã địa điểm từ Place Autocomplete, hãy xem Place Autocomplete và Directions.
  • destination (bắt buộc) chỉ định vị trí kết thúc để tính toán đường đi. Các lựa chọn này giống với các lựa chọn cho trường origin được mô tả ở trên.
  • travelMode (bắt buộc) chỉ định chế độ vận chuyển cần sử dụng khi tính toán chỉ đường. Các giá trị hợp lệ được chỉ định trong phần Chế độ 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 mà travelMode là TRANSIT. Các giá trị hợp lệ được mô tả trong phần Các lựa 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 những yêu cầu mà travelMode là DRIVING. Các giá trị hợp lệ được mô tả trong phần Lựa 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 dùng khi hiển thị kết quả. Các giá trị hợp lệ được chỉ định trong Hệ thống đơn vị bên dưới.

  • waypoints[] (không bắt buộc) chỉ định một mảng gồm các DirectionsWaypoint. Điểm tham chiếu thay đổi một tuyến đường bằng cách định tuyến qua(các) vị trí được chỉ định. Điểm đánh dấu được chỉ định là một đối tượng theo nghĩa đen với các trường như minh hoạ bên dưới:

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

    (Để biết thêm thông tin về điểm đánh dấu, hãy xem phần Sử dụng điểm đánh dấ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 được sắp xếp lại trong trường waypoint_order.(Để biết thêm thông tin, hãy xem phần Sử dụng điểm tham chiếu trong tuyến đường bên dưới.)
  • provideRouteAlternatives (không bắt buộc) khi được đặt thành true, sẽ chỉ định rằng dịch vụ Chỉ đường có thể cung cấp nhiều lựa chọn thay thế cho tuyến đường 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(các) tuyến đường được tính toán nên tránh đườ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 là giá trị gồm 2 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à 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
}

Phương tiện di chuyển

Khi tính toán chỉ đường, bạn cần chỉ định chế độ vận chuyển cần sử dụng. Hiện tại, chúng tôi hỗ trợ các chế độ di chuyển sau:

  • 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 lưới đường bộ.
  • BICYCLING yêu cầu chỉ đường đi xe đạp qua đường dành cho xe đạp và đường phố ư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 Nền tảng Google Maps để 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 mà loại chỉ đường đó không có sẵn, 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 đ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 nhìn thấy những 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 rằng 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 hiện có cho một yêu cầu chỉ đường sẽ khác nhau tuỳ theo chế độ di chuyển. Khi yêu cầu chỉ đường bằng phương tiện công cộng, các lựa chọn avoidHighways, avoidTolls, waypoints[] và optimizeWaypoints sẽ bị bỏ qua. Bạn có thể chỉ định các lựa chọn định tuyến cụ thể cho phương tiện công cộng thông qua giá trị cố định đối tượng TransitOptions.

Chỉ đường phương tiện công cộng có giới hạn về thời gian. Chỉ có thể nhận được chỉ đường cho các thời điểm trong tương lai.

Giá trị 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 một đố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à now (tức là thời gian hiện tại) nếu bạn không chỉ định giá trị nào 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 chữ TransitMode đối tượng. Bạn chỉ có thể thêm trường này nếu yêu cầu có khoá API. Mỗi TransitMode chỉ định một phương tiện công cộng ưu tiên. Bạn được phép sử dụng các giá trị sau:
    • BUS cho biết 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 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 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 đ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 vận chuyển công cộng. Khi sử dụng lựa chọn này, bạn có thể điều chỉnh các lựa chọn được trả về thay vì chấp nhận tuyến đường tối ưu 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ó khoá API. Bạn được phép sử dụng các giá trị sau:
    • FEWER_TRANSFERS cho biết tuyến đường được tính toán nên ưu tiên một số ít lượt chuyển phương tiện.
    • LESS_WALKING cho biết tuyến đường được tính toán nên ưu tiên đi bộ trong khoảng thời gian ngắn.

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 chỉ đường lái xe thông qua đối tượng DrivingOptions.

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

{
  departureTime: Date,
  trafficModel: TrafficModel
}

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

  • departureTime (bắt buộc để giá trị cố định đối tượng drivingOptions hợp lệ) chỉ định thời gian khởi hành mong muốn dưới dạng đối tượng Date. Bạn phải đặt giá trị 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à một ngày trong quá khứ. (API này chuyển đổi tất cả các ngày sang 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 Premium, nếu bạn thêm 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ự kiến khi có lưu lượng truy cập (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à một 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 toán 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. Trường này chứa thời gian dự đoán trong tình hình giao thông dựa trên mức trung bình trước đây. Giá trị mặc định là bestguess. Bạn được phép sử dụng các giá trị sau:
    • bestguess (mặc định) cho biết duration_in_traffic được trả về phải là thông tin ước tính chính xác nhất về thời gian di chuyển dựa trên những thông tin đã biết về cả điều kiện giao thông trong quá khứ và giao thông theo thời gian thực. Thông tin giao thông 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ề sẽ 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 vào những ngày có tình trạng giao thông đặc biệt xấu, giá trị này có thể vượt quá.
    • optimistic cho biết duration_in_traffic được trả về sẽ 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 thuận lợi, thời gian di chuyển có thể nhanh hơn giá trị này.

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

Lưu ý: Chế độ cài đặt hệ thống đơn vị này chỉ ảnh hưởng đến văn bản hiển thị cho người dùng. Kết quả chỉ đường cũng chứa các giá trị về 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.

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

Dịch vụ chỉ đường của Google Maps API 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 đều tải https://maps.googleapis.com/ nên thao tác này sẽ đặt một miền ngầm định thành Hoa Kỳ.) Nếu tải chương trình 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ụ: khi tìm kiếm "San Francisco", các ứng dụng tải https://maps.googleapis.com/ (Hoa Kỳ) có thể trả về kết quả khác với ứ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 là thẻ phụ khu vực gồm 2 ký tự (không phải số) theo chuẩn Unicode. Trong hầu hết các trường hợp, các thẻ này liên kết trực tiếp với giá trị gồm 2 ký tự ccTLD ("miền cấp cao nhất") như "uk" trong "co.uk", chẳng hạn. 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 (ví dụ: "GB" cho "Vương quốc Anh").

Khi sử dụng tham số region:

  • Chỉ định một quốc gia hoặc khu vực. Hệ thống sẽ bỏ qua nhiều giá trị và có thể dẫn đến yêu cầu không thành công.
  • Chỉ sử dụng thẻ phụ khu vực gồm 2 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 những quốc gia và khu vực hỗ trợ chỉ đường. Hãy tham khảo Thông tin chi tiết về phạm vi cung cấp của Nền tảng Google Maps để xem phạm vi cung cấp quốc tế của Directions API (Phiên bản cũ).

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 sẽ thực thi khi yêu cầu dịch vụ hoàn tất. Lệnh gọi lại này sẽ trả về DirectionsResult và mã DirectionsStatus trong phản hồi.

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

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

  • OK cho biết phản hồi chứa DirectionsResult hợp lệ.
  • NOT_FOUND cho biết không thể mã hoá địa lý ít nhất một trong các vị trí được chỉ định trong điểm bắt đầu, điểm đến hoặc các điểm tham chiếu của yêu cầu.
  • ZERO_RESULTS cho biết không tìm thấy tuyến đường nào giữa điểm khởi hành và điểm đến.
  • MAX_WAYPOINTS_EXCEEDED cho biết bạn đã cung cấp quá nhiều trường DirectionsWaypoint trong DirectionsRequest. Hãy xem phần bên dưới về giới hạn cho đ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ề chỉ dẫn phức tạp hơn. Hãy thử giảm số lượng điểm đánh dấu, lượt rẽ hoặc chỉ dẫn.
  • INVALID_REQUEST cho biết DirectionsRequest mà bạn 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 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 về phương tiện công cộng có các điểm tham chiếu.
  • OVER_QUERY_LIMIT cho biết trang web đã gửi quá nhiều yêu cầu trong khoảng thời gian cho phép.
  • REQUEST_DENIED cho biết trang web không được phép sử dụng dịch vụ chỉ đường.
  • UNKNOWN_ERROR cho biết không xử lý được 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 truyền đến một đố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 cho trình kết xuất 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 trình kết xuất và cập nhật bản đồ khi các chỉ dẫn được liên kết với trình kết xuất thay đổi.

Ví dụ sau đây tính toán chỉ đường giữa hai vị trí trên Quốc lộ 66, trong đó điểm bắt đầu 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ị đường nhiều đoạn giữa các vị trí được chỉ định và việc đặt điểm đánh dấu tại điểm xuất phát, đích đế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 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 chỉ đường bằng nhiều phương tiện di chuyển 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 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 nhiều đoạ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. Để thực hiện việc này, hãy gọi setPanel() trên DirectionsRenderer của bạn, truyền <div> vào đó để hiển thị thông tin này. Việc này cũng giúp 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ả.

Chỉ dẫn bằng văn bản sẽ được cung cấp bằ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 API JavaScript 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 chỉ đường 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 với ví dụ ở trên, nhưng có thêm một bảng <div> để hiển thị chỉ đườ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 đối tượng theo nghĩa đen 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ề hoạt động 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 khởi hành đến điểm đến được cung cấp trong DirectionsRequest. Thông thường, chỉ 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 đó, 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 bổ sung các điểm tham chiếu bổ sung trong các tuyến đường thay thế. Đối với các phiên bản từ 3.28 trở lên của API, bạn có thể tiếp tục triển khai chỉ đường có thể kéo bằng cách sử dụng dịch vụ Chỉ đường và 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 tuyến đường đó khớp với một tuyến đường thay thế.

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

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

DirectionsGeocodedWaypoint là một đối tượng theo nghĩa đen 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 mã địa lý đã thành công nhưng không trả về kết quả nào. Điều này có thể xảy ra nếu 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 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ù trình mã hoá này 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ỉ không đầy đủ hay không.

    Trường hợp khớp một phần thường xảy ra đối với những địa chỉ đường không tồn tại trong khu vực 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 trùng 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ị 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à một kết quả 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ể dùng với các API khác của Google. Ví dụ: bạn có thể dùng place_id với thư viện API Google Places để nhận 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 thông tin 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" cho biết "Chicago" là một thành phố, đồng thời trả về "political" cho biết đây là một thực thể chính trị.

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

Lưu ý: Đối tượng DirectionsTrip cũ đã được đổi tên thành DirectionsRoute. Xin lưu ý rằng tuyến đường hiện đề cập đến toàn bộ hành trình từ điểm bắt đầu đến điểm kết thúc, thay vì chỉ 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 xuất phát và điểm đến đã chỉ định. Tuyến đường này có thể bao gồm một hoặc nhiều đoạn đường (thuộc loại DirectionsLeg) tuỳ thuộc vào việc bạn có chỉ định điểm tham chiếu nào hay không. Ngoài ra, tuyến đường này cũng chứa thông tin cảnh báo và bản quyền mà người dùng phải nhìn thấy cùng với thông tin định tuyến.

DirectionsRoute là một đối tượng theo nghĩa đen có các trường sau:

  • legs[] chứa một mảng gồm 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ỗi điểm tham chiếu hoặc đích đến được chỉ định sẽ có một chặng riêng. (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 đã tính toán. Mảng này có thể chứa một thứ tự đã được thay đổi nếu DirectionsRequest được truyền optimizeWaypoints: true.
  • overview_path chứa một mảng LatLng đại diện cho đường dẫn gần đúng (được làm mịn) của các chỉ dẫn thu được.
  • overview_polyline chứa một đối tượng points duy nhất lưu giữ một biểu diễn đường nhiều đoạn được mã hoá của tuyến đường. Đường nhiều đường này là một đường dẫn gần đúng (được làm mịn) của chỉ đường thu được.
  • bounds chứa một LatLngBounds cho biết ranh giới của đường nhiều đoạn 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ác cảnh báo sẽ xuất hiện khi hiển thị các chỉ 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ị những 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ỉ dành cho những tuyến đường có thông tin về giá vé cho tất cả các chặng của phương tiện công cộng. Thông tin này bao gồm:
    • currency: Mã đơn vị tiền tệ theo ISO 4217 cho biết đơn vị tiền tệ mà số tiền được biểu thị.
    • value: Tổng số tiền vé, tính bằng đơn vị tiền tệ được chỉ định ở trên.

Chân đường đi

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

DirectionsLeg xác định một chặng của hành trình từ điểm khởi hành đến điểm đến trong tuyến đường đã tính toán. Đối với những tuyến đường không có điểm tham chiếu, tuyến đường sẽ bao gồm một "chặng", nhưng đối với những 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 cố định 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 đường.

  • distance cho biết tổng quãng đường mà chặng này đã đi, 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 biểu thị khoảng cách, theo mặc định, khoảng cách này được hiển thị bằng các đơn vị như được dùng tại vị trí ban đầu. (Ví dụ: dặm sẽ được dùng cho mọi điểm xuất phát trong phạm vi 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 xác định nếu khoảng cách không xác định.

  • duration cho biết tổng thời lượng của chặng này, dưới dạng một đối tượng Duration có dạng 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ị khoảng thời gian.

    Các trường này có thể không 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 các điểm dừng chân. Tức là không bao gồm các điểm đánh dấu nơi 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 như một phần của trường drivingOptions trong yêu cầu.
    • Tình trạng giao thông có sẵn cho tuyến đường được yêu cầu.

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

    • value cho biết thời lượng tính bằng giây.
    • text chứa một 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 chỉ đường bằng phương tiện công cộng. Kết quả được trả về dưới dạng một đối tượng Time có 3 thuộc tính:
    • value thời gian được chỉ định dưới dạng đối tượng JavaScript Date.
    • 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 trạm dừng chân.
    • time_zone chứa múi giờ của trạm sạc này. Giá trị này là tên của múi giờ như đượ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 dự kiến cho chặng này, được chỉ định dưới dạng đối tượng Time. departure_time chỉ có trong chỉ đường 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ụ chỉ đường trên web tính toán đường đi giữa các vị trí bằng cách sử dụng lựa chọn di chuyển gần nhất (thường là đường bộ) tại điểm bắt đầu 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, chẳng hạn như, đường không gần với đ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 chỉ đường 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 bắt đầu và điểm kết thúc, nên end_location có thể khác với đích đến được cung cấp của chặng này nếu, chẳng hạn như, không có đường bộ nào gần đích đến.
  • start_address chứa địa chỉ mà con người đọc được (thường là địa chỉ đường) 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 cách 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 cách lập trình.

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

DirectionsStep là đơn vị nhỏ nhất của tuyến đường, chứa một bước duy nhất mô tả một chỉ dẫn cụ thể, duy nhất trong hành trình. Ví dụ: "Rẽ trái tại đường W. 4th St." Bước này không chỉ mô tả chỉ dẫn mà còn chứa thông tin về khoảng cách và thời lượng liên quan đến cách bước này liên quan đến bước tiếp theo. Ví dụ: một bước được biểu thị là "Nhập vào đường I-80 West" có thể có thời lượng là "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ụ Đường đi để 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 dưới dạng một đối tượng transit. Nếu chỉ đường bao gồm nhiều phương thức vận chuyển, thì hướng dẫn 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ỉ dẫn 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 chi tiết về đường đi bộ 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 đường Arelious Walker" và "Rẽ trái vào đường Innes".

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

  • instructions chứa hướng dẫn cho bước này trong một chuỗi văn bản.
  • distance chứa khoảng cách mà bước này đã đi được cho đến bước tiếp theo, dưới dạng một đối tượng Distance. (Xem phần mô tả trong DirectionsLeg ở trên.) Trường này có thể không xác định nếu khoảng cách không xác định.
  • 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 phần mô tả trong DirectionsLeg ở trên.) Trường này có thể không xác định nếu không xác định được thời lượng.
  • start_location chứa LatLng được mã hoá địa lý 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 lưu giữ một biểu thị đường nhiều đoạn được mã hoá của bước. Đường nhiều đường này là đường dẫn gần đúng (được làm mịn) của bước.
  • steps[] một giá trị cố định đối tượng DirectionsStep chứa chỉ dẫn chi tiết cho các bước đi bộ hoặc lái xe trong chỉ đường phương tiện công cộng. Các bước phụ chỉ có trong chỉ đường 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ả khoá học 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. Những 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 một 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 trạm/điểm dừng đến với các thuộc tính sau:
    • name tên của trạm/điểm dừng phương tiện công cộng. Ví dụ: "Quảng trường Thống nhất".
    • location vị trí của trạm/bến phương tiện công cộng, được biểu thị dưới dạng một LatLng.
  • departure_stop chứa một đối tượng TransitStop đại diện cho trạm/điểm dừng khởi hành.
  • arrival_time chứa thời gian đến, được chỉ định dưới dạng một đối tượng Time có 3 thuộc tính:
    • value thời gian được chỉ định dưới dạng đối tượng JavaScript Date.
    • 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 trạm dừng chân.
    • time_zone chứa múi giờ của trạm sạc này. Giá trị này là tên của múi giờ như đượ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 một đối tượng Time.
  • headsign chỉ định hướng di chuyển trên đường này, khi đượ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 khi có sẵn, thông tin này cho biết 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 giá trị cố định đối tượng TransitLine chứa thông tin về tuyến đường công cộng được 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ố lượng đ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ỉ đường 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 giao thông 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 giao thông công cộng này. Đây thường là số dòng, chẳng hạn như "2" hoặc "M14".
  • agencies là một mảng chứa một đối tượng TransitAgency duy nhất. Đối tượng TransitAgency cung cấp thông tin về nhà điều hành của tuyến đường này, bao gồm cả các thuộc tính sau:
    • name chứa tên của công ty vận tải công cộng.
    • phone chứa số điện thoại của cơ quan vận tải công cộng.
    • url chứa URL của công ty vận tải công cộng.

    Lưu ý: Nếu đang hiển thị chỉ đường đi phương tiện công cộng theo cách thủ công thay vì sử dụng đối tượng DirectionsRenderer, bạn phải hiển thị tên và URL của các công ty vận tải công cộng 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ơ quan giao thông công cộng cung cấp.
  • icon chứa một URL cho biểu tượng được 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 giao thông 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 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 một chuỗi hex, 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 đường này. Màu sẽ được chỉ định dưới dạng một chuỗi hex.
  • vehicle chứa một đối tượng Vehicle có các thuộc tính sau:
    • name chứa tên của chiếc 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 đường 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 một URL cho 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 được liên kết với loại xe này, dựa trên biển báo 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 Hệ thống đường sắt đô thị.
VehicleType.SUBWAY Xe điện ngầm.
VehicleType.TRAM Xe điện trên mặt đất.
VehicleType.MONORAIL Xe lửa một ray.
VehicleType.HEAVY_RAIL Đường sắt 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 Xe buýt.
VehicleType.INTERCITY_BUS Xe buýt liên tỉnh.
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ó thể trả và đón khách ở bất cứ đâu trên tuyến đường của mình.
VehicleType.FERRY Phà.
VehicleType.CABLE_CAR Phương tiện hoạt động 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 loại xe được kéo lên dốc bằng cáp. Tàu kéo thường có 2 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 nào về chỉ đường.

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

Ví dụ sau đây vẽ chỉ đường đi bộ đến một số điểm 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 một InfoWindow có văn bản hướng dẫn cho bước đó.

Lưu ý: Vì chúng tôi đang tính toán chỉ đườ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 <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 các điểm tham chiếu (thuộc loại DirectionsWaypoint) khi tính toán các tuyến đường bằng dịch vụ Chỉ đường cho thông tin chỉ đường đi bộ, đi xe đạp hoặc lá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 đánh dấu cho phép bạn tính toán các 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 đánh dấu đã cho.

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

  • location (bắt buộc) chỉ định địa chỉ của điểm đánh dấ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à lựa chọn ưu tiên để định tuyến qua vị trí được chỉ định (false). Điểm dừng chân 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 qua các điểm tham chiếu được cung cấp theo thứ tự đã cho. Bạn có thể tuỳ ý truyền optimizeWaypoints: true trong DirectionsRequest để cho phép dịch vụ Chỉ đường tối ưu hoá tuyến đường đã cung cấp bằng cách sắp xếp lại các điểm tham chiếu theo thứ tự hiệu quả hơn. (Việc tối ưu hoá này là một ứng dụng của vấn đề người bán hàng lưu độ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 tính đến khi quyết định tuyến đường nào hiệu quả nhất. Tất cả các điểm đánh dấu phải là điểm dừng chân để 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 đánh dấu, thì thứ tự của các điểm này 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 bắt đầu, điểm kết thúc và điểm tham chiếu. (Để chọn nhiều điểm đánh dấu, hãy nhấn Ctrl-Nhấp 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 cho chúng ta 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;
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 đánh dấu

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

  • Số lượng điểm đánh dấu tối đa được phép khi sử dụng dịch vụ Chỉ đường trong Maps JavaScript API là 25, cộng với điểm xuất phát và điểm đến. Hạn mức này cũng áp dụng cho dịch vụ web Directions API (cũ).
  • Đối với dịch vụ web Directions API (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 đặc biệt của Nền tảng Google Maps được phép sử dụng 25 điểm tham chiếu, cộng với điểm bắt đầu và điểm đến.
  • Không hỗ trợ điểm trung gian cho chỉ đường 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 chỉ đường đi xe đạp, đi bộ hoặc lái xe được hiển thị bằng DirectionsRenderer một cách linh hoạt nếu chỉ đường đó 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 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 hướng có thể kéo hay không bằng cách đặt thuộc tính draggable của trình kết xuất thành true. Bạn không thể kéo chỉ đường bằng phương tiện công cộng.

Khi chỉ đường có thể kéo, 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ỉ báo đến một vị trí mới. DirectionsRenderer sẽ tự động cập nhật để cho thấy đường dẫn đã sửa đổi. Sau khi thả, 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 màu trắng nhỏ). Việc chọn và di chuyển một đoạn đường sẽ làm thay đổi đoạn đường đó của tuyến đường, trong khi việc chọn và di chuyển một điểm đánh dấu điểm tham chiếu (bao gồm cả điểm bắt đầu và điểm kết thúc) sẽ làm thay đổi các đoạn đường của tuyến đường đi qua điểm tham chiếu đó.

Vì các chỉ dẫn có thể kéo được sẽ đượ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 để nhận được thông báo khi người dùng sửa đổi chỉ dẫn được 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 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ụ

Dùng thử mẫu