Dịch vụ chỉ đường

Tổng quan

Bạn có thể tính toán đường đi (bằng nhiều phương thức 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 API Google Maps. Dịch vụ này nhận yêu cầu chỉ đường và trả về đường dẫn hiệu quả. Thời gian di chuyển là yếu tố chính được tối ưu hoá, nhưng bạn có thể cân nhắc đến những yếu tố khác như khoảng cách, số lượt và nhiều yếu tố khác. Bạn có thể tự xử lý các kết quả chỉ đường này hoặc sử dụng đối tượng DirectionsRenderer để kết xuất các kết quả này.

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

Dịch vụ Chỉ đường có thể trả về thông tin đường đi nhiều phần bằng cách sử dụng một loạt các điểm tham chiếu. Thông tin đường đi sẽ xuất hiện dưới dạng bản vẽ nhiều đường trên bản đồ hoặc dưới dạng một loạt nội dung mô tả dạ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 Maps JavaScript, trước tiên hãy đảm bảo rằng API Chỉ đường được bật 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. Truy cập vào Google Cloud Console.
  2. Nhấp vào nút Select a project (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 và nhấp vào Open (Mở).
  3. Trong danh sách API trên Dashboard (Trang tổng quan), hãy tìm Directions API (API chỉ đường).
  4. Nếu bạn thấy API này trong danh sách thì bạn đã hoàn tất. Nếu API không có trong danh sách, hãy bật API:
    1. Ở đầu trang, hãy chọn ENABLE API (BẬT API) để hiển thị thẻ Library (Thư viện). Ngoài ra, trên trình đơn bên trái, hãy chọn Thư viện.
    2. Tìm API Chỉ đường, rồi chọn API đó trong danh sách kết quả.
    3. Chọn ENABLE (BẬT). Khi quá trình này kết thúc, API Chỉ đường sẽ xuất hiện trong danh sách các API trên Trang tổng quan.

Mức giá và các chính sách

Giá

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

Chính sách

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

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

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

Để sử dụng thông tin đường đi trong API Maps JavaScript, hãy tạo một đối tượng thuộc loại DirectionsService và gọi DirectionsService.route() để bắt đầu yêu cầu dịch vụ Chỉ đường, chuyển đối tượng đó thành giá trị đối tượng DirectionsRequest chứa từ khoá đầu vào và phương thức gọi lại để thực thi sau 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 bên dưới:

  • origin (bắt buộc) chỉ định vị trí bắt đầu để tính đườ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 Place. Nếu sử dụng đối tượng Place (Địa điểm), bạn có thể chỉ định mã địa điểm, chuỗi truy vấn hoặc vị trí LatLng. Bạn có thể truy xuất mã địa điểm qua dịch vụ Mã hoá địa lý, Tìm kiếm địa điểm và Dịch vụ tự động hoàn thành địa điểm trong API JavaScript cho Maps. Để xem ví dụ về cách sử dụng mã địa điểm trong tính năng Tự động hoàn thành địa điểm, hãy tham khảo bài viết Tự động hoàn thành địa điểm và đường đi.
  • destination (bắt buộc) chỉ định vị trí kết thúc để tính chỉ đường. Các tùy chọn giống như trường origin được mô tả ở trên.
  • travelMode (bắt buộc) chỉ định phương thức di chuyển sẽ sử dụng khi tính toán chỉ đường. Các giá trị hợp lệ được chỉ định trong Travel Modes (Chế độ du lịch) bên dưới.
  • transitOptions (không bắt buộc) chỉ định các giá trị chỉ áp dụng cho yêu cầu trong đó travelModeTRANSIT. Giá trị hợp lệ được mô tả trong phần Tuỳ chọn phương tiện công cộng dưới đây.
  • drivingOptions (không bắt buộc) chỉ định các giá trị chỉ áp dụng cho yêu cầu trong đó travelModeDRIVING. Các giá trị hợp lệ được mô tả trong phần Tuỳ chọn lái xe dưới đây.
  • unitSystem (không bắt buộc) chỉ định hệ thống đơn vị cần sử dụng khi hiển thị kết quả. Các giá trị hợp lệ được chỉ định trong System Systems (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 tuyến đường đó qua(các) vị trí được chỉ định. Điểm tham chiếu được chỉ định dưới dạng đối tượng cố định với các trường hiển thị bên dưới:

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

    (Để biết thêm thông tin về điểm tham chiếu, hãy xem phần Sử dụng Điểm tham chiếu trong Tuyến đườ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 hóa 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 đặt thành true chỉ định dịch vụ Chỉ đường có thể cung cấp nhiều tuyến đường thay thế trong phản hồi. Lưu ý rằng việc cung cấp tuyến đường thay thế có thể làm tăng thời gian phản hồi từ 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 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 đã tính toán sẽ tránh được phà nếu có thể.
  • avoidHighways (không bắt buộc) khi đặt thành true cho biết rằng(các) tuyến đường đã tính toán 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 đã 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ã vùng, được chỉ định là giá trị hai ký tự cho 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à DirectionsRequest mẫu:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

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

Khi tính toán đường đi, bạn cần chỉ định phương tiện giao thông cần dùng. Các chế độ đi lại sau đây hiện được hỗ trợ:

  • DRIVING (Mặc định) cho biết chỉ đường 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 thông qua các tuyến đường phương tiện công cộng.
  • WALKING yêu cầu chỉ đường đi bộ qua lối đi bộ và vỉa hè.

Hãy tham khảo Thông tin chi tiết về phạm vi bao phủ của Nền tảng Google Maps để xác định phạm vi một quốc gia hỗ trợ đường đi. Nếu bạn yêu cầu chỉ đường cho một khu vực không hỗ trợ 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 dành cho người đi bộ, vì vậy, thông tin chỉ đường đi bộ sẽ trả về DirectionsResult mà bạn phải hiển thị nếu không sử dụng DirectionsRenderer mặc định.

Tùy chọn phương tiện công cộng

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

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

Đối tượng TransitOptions cố định 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 bên dưới:

  • arrivalTime (không bắt buộc) chỉ định thời gian đến mong muốn dưới dạng đối tượng Date. Nếu bạn chỉ định thời gian đến, thì thời gian khởi hành sẽ bị bỏ qua.
  • departureTime (không bắt buộc) chỉ định thời gian khởi hành theo ý 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 hiện tại (nghĩa là thời gian hiện tại) nếu không có giá trị nào được chỉ định cho departureTime hoặc arrivalTime.
  • modes[] (không bắt buộc) là một mảng chứa một hoặc nhiều giá trị cố định đối tượng TransitMode. Trường này chỉ có thể được bao gồm nếu yêu cầu bao gồm khóa API. Mỗi TransitMode sẽ chỉ định một phương tiện công cộng ưu tiên. Các giá trị sau được phép:
    • BUS cho biết tuyến đường đã tính toán nên đi bằng xe buýt.
    • RAIL cho biết rằng tuyến đường được tính toán phải ưu tiên đi bằng tàu hoả, xe điện, tàu điện và tàu điện ngầm.
    • SUBWAY cho biết tuyến đường được tính toán nên đi bằng tàu điện ngầm.
    • TRAIN cho biết tuyến đường đã tính toán nên đi 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 các tuyến phương tiện công cộng. Khi sử dụng tùy chọn này, bạn có thể thiên về các tùy chọn được trả về thay vì chấp nhận tuyến tốt nhất mặc định do API chọn. Trường này chỉ có thể được chỉ định nếu yêu cầu bao gồm khóa API. Các giá trị sau được phép:
    • FEWER_TRANSFERS cho biết tuyến đường được tính toán nên ưu tiên một số lần chuyển.
    • LESS_WALKING cho biết tuyến đường đã tính toán chỉ nên đi bộ có giới hạn.

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

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

Tùy chọn lái xe

Bạn có thể chỉ định các tuỳ chọn định tuyến để 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 bên dưới:

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

Dưới đây là ví dụ về DirectionsRequest để tìm đường lái xe:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Hệ thống đơn vị

Theo mặc định, thông tin đường đi được tính toán và hiển thị bằng hệ thống đơn vị của quốc gia hoặc khu vực xuất phát. (Lưu ý: Nguồn gốc biểu thị bằng toạ độ vĩ độ/kinh độ thay vì địa chỉ luôn được đặt mặc định là đơn vị hệ mét.) 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 km. Bạn có thể ghi đè hệ thống đơn vị này bằng cách đặt một hệ thống rõ ràng trong yêu cầu sử dụng một trong các giá trị UnitSystem sau:

  • UnitSystem.METRIC chỉ định việc sử dụng hệ thống chỉ số. Khoảng cách được hiển thị bằng cách sử dụng km.
  • UnitSystem.IMPERIAL chỉ định việc sử dụng hệ thống Hoàng gia (tiếng Anh). Khoảng cách sẽ 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 giá trị khoảng cách, không hiển thị cho người dùng, được biểu thị bằng mét.

Xu hướng theo khu vực cho đường đi

Dịch vụ Chỉ đường 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 giày bốt JavaScript. (Vì hầu hết người dùng tải https://maps.googleapis.com/ nên điều này sẽ đặt miền mặc định thành Hoa Kỳ.) Nếu tải bốt tự độ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 với kết quả của các ứng dụng tải https://maps.googleapis.com/ (Hoa Kỳ) so với một http://maps.google.es/ tải (Tây Ban Nha).

Bạn cũng có thể thiết lập 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 sẽ lấy một mã vùng, được chỉ định là một vùng phụ Unicode hai ký tự (không phải chữ 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 tới ccTLD ("miền cấp cao nhất") chẳng hạn như giá trị "uk" trong "co.uk". Trong một số trường hợp, thẻ region cũng hỗ trợ các mã ISO-3166-1, đôi khi khác với các giá trị ccTLD ("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ị bị bỏ qua và có thể dẫn đến yêu cầu không thực hiện được.
  • Chỉ sử dụng các thẻ con của vùng gồm hai ký tự (định dạng Unicode CLDR). Tất cả các giá trị nhập vào khác sẽ dẫn đến lỗi.

Xu hướng theo khu vực chỉ được hỗ trợ cho các quốc gia và khu vực hỗ trợ thông tin đường đi. Tham khảo bài viết Thông tin chi tiết về mức độ phù hợp của nền tảng Google Maps để xem thông tin toàn cầu về API chỉ đường.

Hiển thị chỉ đường

Việc khởi tạo yêu cầu chỉ đường đến DirectionsService bằng phương thức route() yêu cầu truyền lệnh gọi lại trong khi thực hiện yêu cầu dịch vụ. Lệnh gọi lại này sẽ trả về mã 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 một DirectionsResult hợp lệ.
  • NOT_FOUND chỉ ra ít nhất một trong số những vị trí đã chỉ định trong điểm xuất phát, điểm đến hoặc điểm trung gian của yêu cầu không được mã hoá địa lý.
  • ZERO_RESULTS cho biết không thể 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 dưới đây về giới hạn về điểm tham chiếu.
  • MAX_ROUTE_LENGTH_EXCEEDED cho biết tuyến được yêu cầu quá dài nên không thể xử lý. Lỗi này xảy ra khi hệ thống trả về các hướng phức tạp hơn. Hãy thử giảm số lượng điểm tham chiếu, ngã rẽ hoặc hướng dẫn.
  • INVALID_REQUEST cho biết rằng DirectionsRequest được cung cấp là không hợp lệ. Nguyên nhân phổ biến nhất của mã lỗi này là yêu cầu thiếu điểm xuất phát hoặc điểm đến hoặc yêu cầu phương tiện bao gồm điểm trung gian.
  • OVER_QUERY_LIMIT cho biết trang web đã gửi quá nhiều yêu cầu trong khoảng thời gian cho phép.
  • REQUEST_DENIED cho biết trang web này không được phép sử dụng dịch vụ chỉ đường.
  • UNKNOWN_ERROR cho biết không thể xử lý yêu cầu chỉ đường do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn thử lại.

Bạn phải đả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ị {2}Result

DirectionsResult chứa kết quả của truy vấn chỉ đường mà bạn có thể tự xử lý hoặc truyền đế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 đồ.

Để cho hiện DirectionsResult bằng cách sử dụng DirectionsRenderer, bạn cần thực hiện những việc sau:

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

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

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(result);
    }
  });
}

Trong phần nội dung HTML:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

Xem ví dụ

Ví dụ sau đây cho thấy thông tin chỉ đường bằng các phương thức đi lại từ Haight-Ashbury đến Ocean Beach ở San Francisco, CA:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

Trong phần nội dung HTML:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

Xem ví dụ

DirectionsRenderer không chỉ xử lý việc hiển thị hình nhiều đường và bất kỳ điểm đánh dấu liên quan nào, mà còn có thể xử lý hiển thị văn bản 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, truyền vào đó <div> để hiển thị thông tin này. Việc này cũng đảm bảo rằng bạn hiển thị thông tin bản quyền thích hợp và bất kỳ cảnh báo nào có thể liên quan đến kết quả.

Bạn có thể cung cấp thông tin đường đi bằng văn bản 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 nội dung Bản địa hoá.) Đối với đường đi bằng phương tiện công cộng, thời gian sẽ hiển thị theo múi giờ tại điểm dừng phương tiện đó.

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

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

Trong phần nội dung HTML:

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

Xem ví dụ

Đối tượngDirectionsResult

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à đối tượng DirectionsResult. DirectionsResult là giá trị cố định của đối tượng có các trường sau:

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

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

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

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

DirectionsGeocodedWaypoint là giá trị cố định của đối tượng có các trường sau:

  • geocoder_status cho biết mã trạng thái từ thao tác mã hoá địa lý. Trường này có thể chứa các giá trị sau.
    • "OK" cho biết chưa xảy ra lỗi nào; đị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ã 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 chuyển vào một address không tồn tại.
  • partial_match cho biết bộ mã hoá dữ liệu đã không trả về kết quả khớp chính xác cho yêu cầu ban đầu, mặc dù bộ mã hoá có thể so 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 để tìm lỗi chính tả và/hoặc địa chỉ không đầy đủ.

    Kết quả khớp một phần thường xảy ra nhất đối với các địa chỉ đường phố không tồn tại trong phạm vi địa phương bạn chuyển trong yêu cầu. Kết quả khớp một phần cũng có thể được trả về khi 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, Vương quốc Anh" sẽ trả về kết quả khớp một phần cho cả Phố Henry và Phố Henrietta. Hãy lưu ý rằng nếu một yêu cầu bao gồm một 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à 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ể sử dụng place_id với thư viện API Google Địa điểm để 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 bài viết tổng quan về mã địa điểm.
  • types[] là một mảng cho biết loại kết quả được trả về. Mảng này chứa một bộ từ 0 thẻ trở lên xác định loại tính năng được trả về trong kết quả. Ví dụ: một mã địa lý được mã hoá của "Chicago" trả về "địa phương" cho biết rằng "Chicago" là một thành phố, và cũng trả về "chính trị" để cho biết rằng đây là một pháp nhân chính trị.

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

Lưu ý: Đối tượng DirectionsTrip cũ đã được đổi tên thành DirectionsRoute. Xin lưu ý rằng tuyến đường hiện là toàn bộ hành trình bắt đầu và kết thúc, chứ không phải một chặng của chuyến đi của cha mẹ.

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

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

Chân chuyển hướng

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

DirectionsLeg xác định một chặng duy nhất của hành trình từ điểm gốc đến điểm đến trong tuyến đường đã 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 "một chân", 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à giá trị cố định của đối tượng có các trường sau:

  • steps[] chứa một loạt các đối tượng DirectionsStep biểu thị thông tin về từng bước riêng của hành trình.
  • distance cho biết tổng quãng đường mà chân này chiếm được, dưới dạng một đối tượng Distance của biểu mẫu sau:

    • value cho biết khoảng cách tính bằng mét
    • text chứa nội dung biểu diễn chuỗi khoảng cách mà theo mặc định sẽ hiển thị trong các đơn vị như được sử dụng tại điểm gốc. (Ví dụ: số dặm sẽ được sử dụng cho mọi điểm xuất phát trong phạm vi lãnh thổ 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.

    Những 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ân này, dưới dạng một đối tượng Duration của dạng sau:

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

    Những trường này có thể không xác định nếu không xác định được 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 điều kiện giao thông hiện tại. duration_in_traffic chỉ được trả về nếu tất cả các điều kiện sau đều đúng:

    • Yêu cầu này không bao gồm các điểm tham chiếu dừng. Nghĩa là, giá trị này không bao gồm các điểm trung gian mà stopovertrue.
    • Yêu cầu này dành riêng cho chỉ đường lái xe — mode được đặt thành driving.
    • departureTime được đưa vào trường drivingOptions trong yêu cầu.
    • Có 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 đại diện có thể đọc được của thời lượng.
  • arrival_time chứa thời gian đến dự kiến của chặng này. Thuộc tính này chỉ được trả về để xem đường đi bằng phương tiện công cộng. Kết quả sẽ được trả về dưới dạng đối tượng Time có ba thuộc tính:
    • value thời gian được chỉ định làm đối tượng Date JavaScript.
    • text thời gian được chỉ định dưới dạng chuỗi. Giờ hiển thị theo múi giờ của điểm dừng phương tiện.
    • time_zone chứa múi giờ của trạm này. Giá trị 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 của chặng này, được chỉ định là đối tượng Time. departure_time chỉ dùng được cho đường đi bằng phương tiện công cộng.
  • start_location chứa LatLng của nguồn gốc của chân này. Vì Dịch vụ web chỉ đường tính toán chỉ đường giữa các vị trí bằng cách sử dụng tùy chọn giao thông gần nhất (thường là đường) 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 bắt đầu đã cung cấp của chặng này, chẳng hạn như một con đường không gần nguồn gốc.
  • end_location chứa LatLng của đích đến của chân này. Do DirectionsService tính toán đường đi giữa các địa điểm bằng cách sử dụng tùy chọn vận chuyển gần nhất (thường là đường) tại điểm bắt đầu và điểm kết thúc, end_location có thể khác với điểm đến được cung cấp của chặng này, chẳng hạn như một đường không gần điểm đến.
  • start_address chứa địa chỉ mà con người có thể đọc được (thường là địa chỉ đường phố) ở đầu chân này.

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

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

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

DirectionsStep là đơn vị nguyên tử nhất của tuyến đường, có một bước mô tả một hướng dẫn cụ thể trên hành trình. Ví dụ: " Rẽ trái tại W. 4 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 bước này liên quan đến bước sau. Ví dụ: một bước được biểu thị là "Hợp nhất vào I-80 West" có thể chứa thời lượng là "37 dặm" và "40 phút", cho biết bước tiếp theo sẽ là 37 dặm/40 phút kể từ bước này.

Khi sử dụng dịch vụ Chỉ đường để tìm đường đi bằng phương tiện công cộng, dãy 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 thông tin đường đi bao gồm nhiều phương thức di chuyển, thì thông tin đường đi chi tiết sẽ được cung cấp cho các bước đi bộ hoặc lái xe trong một mảng steps[]. Ví dụ: một bước đi bộ sẽ bao gồm chỉ đường từ vị trí bắt đầu và kết thúc: "Walk to Innes Ave & Fitch St". Bước đó sẽ bao gồm thông tin đườ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à giá trị cố định của đối tượng có các trường sau:

  • instructions chứa hướng dẫn cho bước này trong một chuỗi văn bản.
  • distance chứa khoảng cách được thực hiện trong bước này cho đến bước tiếp theo, dưới dạng đối tượng Distance. (Xem nội dung mô tả bằng 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 dữ liệu ướ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 phần 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 đã mã hoá 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 chứa thông tin đại diện đa dòng đã mã hoá của bước. Hình nhiều đường này là một đường dẫn ước tính (được làm mượt) của bước.
  • steps[] một giá trị cố định đối tượng DirectionsStep có chứa thông tin đường đi chi tiết để đi bộ hoặc lái xe theo các hướng trong phương tiện công cộng. Các bước phụ chỉ có sẵn cho đường đi bằng phương tiện công cộng.
  • travel_mode chứa TravelMode được sử dụng trong bước này. Thông tin chỉ đường phương tiện công cộng có thể bao gồm cả thông tin chỉ đường đi bộ và chuyển tuyến.
  • path chứa một mảng LatLngs mô tả quy trình của bước này.
  • transit chứa thông tin cụ thể về phương tiện công cộng, chẳng hạn như thời gian đến và khởi hành, cũng như tên của tuyến phương tiện công cộng.

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

Thông tin chỉ đường phương tiện công cộng sẽ trả lại 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, TransitAgencyVehicleType như mô tả bên dưới.

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

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

  • arrival_stop chứa đối tượng TransitStop đại diện cho điểm đến/điểm dừng có các thuộc tính sau:
    • name tên trạm/ trạm dừng phương tiện công cộng. Ví dụ: "Hình vuông Union".
    • location vị trí của trạm/trạm dừng phương tiện công cộng, được biểu thị dưới dạng LatLng.
  • departure_stop chứa đối tượng TransitStop đại diện cho điểm khởi hành/điểm dừng.
  • arrival_time chứa thời gian đến, được chỉ định là một đối tượng Time có ba thuộc tính:
    • value thời gian được chỉ định làm đối tượng Date JavaScript.
    • text thời gian được chỉ định dưới dạng chuỗi. Giờ hiển thị theo múi giờ của điểm dừng phương tiện.
    • time_zone chứa múi giờ của trạm này. Giá trị 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 là đối tượng Time.
  • headsign chỉ định hướng di chuyển trên tuyến này, như được đánh dấu trên xe hoặc tại điểm khởi hành. Đây thường sẽ là trạm có ga cuối.
  • Hiện tại, headway sẽ chỉ định số giây dự kiến giữa các lầ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 có thể phải đợi mười phút nếu bỏ lỡ xe buýt.
  • line chứa giá trị cố định đối tượng TransitLine chứa thông tin về dòng phương tiện công cộng được sử dụng trong bước này. TransitLine cung cấp tên và toán tử của dòng, cùng với các thuộc tính khác được mô tả trong tài liệu tham khảo TransitLine.
  • num_stops chứa số điểm dừng ở bước này. Bao gồm điểm dừng đến, nhưng không bao gồm điểm khởi hành. Ví dụ: nếu thông tin đường đi của bạn là đi từ Đ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ề giá trị 3.

Đường chuyển

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

  • name chứa tên đầy đủ của dòng 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 dòng phương tiện 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. Đối tượng TransitAgency cung cấp thông tin về toán tử của dòng này, bao gồm các thuộc tính sau:
    • name chứa tên của công ty vận tải.
    • phone chứa số điện thoại của công ty vận tải.
    • url chứa URL cho công ty vận tải.

    Lưu ý: Nếu đang hiển thị thông tin đườ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 đang cung cấp 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 của biểu tượng liên kết với dòng này. Hầu hết các thành phố sẽ sử dụng biểu tượng chung thay đổi theo loại xe. Một số tuyến đường phương tiện, chẳng hạn như hệ thống tàu điện ngầm của New York, có các biểu tượng dành riêng cho tuyến đó.
  • color chứa màu sắc thường dùng trong bảng hiệu của phương tiện công cộng này. Màu sẽ được chỉ định dưới dạng chuỗi hex, chẳng hạn như: #FF0033.
  • text_color chứa màu của văn bản thường dùng cho biển báo của dòng này. Màu sẽ được chỉ định dưới dạng chuỗi hex.
  • vehicle chứa đối tượng Vehicle có các thuộc tính sau:
    • name chứa tên xe trên dòng này. Ví dụ: " Tàu điện ngầm."
    • type chứa loại xe được sử dụng trên tuyến này. Hãy xem tài liệu về Loại xe để biết danh sách đầy đủ các giá trị được hỗ trợ.
    • icon chứa URL cho biểu tượng thường liên kết với loại xe này.
    • local_icon chứa URL của biểu tượng liên kết với loại xe này, dựa trên biển báo 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 Chuyển tuyến xe điện.
VehicleType.SUBWAY Tàu điện ngầm.
VehicleType.TRAM Dải đèn đường trên mặt đất.
VehicleType.MONORAIL Tàu điện một ray.
VehicleType.HEAVY_RAIL Đường sắt nặng.
VehicleType.COMMUTER_TRAIN Tuyến đường đi làm.
VehicleType.HIGH_SPEED_TRAIN Tàu cao tốc.
VehicleType.BUS Xe buýt.
VehicleType.INTERCITY_BUS Xe buýt liên thành phố.
VehicleType.TROLLEYBUS Xe điện.
VehicleType.SHARE_TAXI Taxi chung là một loại xe buýt có khả năng trả khách và đưa đón khách ở bất cứ đâu trên tuyến đường.
VehicleType.FERRY Chuyến phà.
VehicleType.CABLE_CAR Xe hoạt động bằng cáp, thường là trên mặt đất. Cáp treo có thể thuộc loại VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Cáp treo.
VehicleType.FUNICULAR Một phương tiện được kéo lên bằng dốc bằng cáp. Xe lửa leo núi thường có 2 chiếc ô tô, trong đó mỗi chiếc ô tô đóng vai trò là một chiếc xe đối trọng.
VehicleType.OTHER Tất cả các phương tiện khác sẽ trả về loại này.

Kiểm tra Đường đi

Các thành phần DirectionsResultsDirectionsRoute, DirectionsLeg ,DirectionsStepTransitDetails — có thể được kiểm tra và sử dụng khi phân tích cú pháp của bất kỳ phản hồi nào về đường đi.

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

Ví dụ sau minh họa đườ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 mỗi 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 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 đ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 waypoint (loại DirectionsWaypoint) khi tính toán các tuyến đường bằng dịch vụ Chỉ đường để đi bộ, đi xe đạp hoặc lái xe. Điểm tham chiếu không khả dụng cho chỉ đường phương tiện. Điểm tham chiế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 đó, tuyến đường được trả về đi qua các điểm tham chiếu nhất định.

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

  • location (bắt buộc) chỉ định địa chỉ của điểm tham chiếu.
  • stopover (không bắt buộc) cho biết liệu điểm tham chiếu này có phải là điểm dừng thực tế trên tuyến đường (true) hay không, hoặc thay vào đó chỉ có một lựa chọn ưu tiên để định tuyến qua vị trí đã 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 đã cung cấp theo thứ tự nhất định. Nếu muốn, bạn có thể chuyể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. (Hoạt động tối ưu hoá này là một ứng dụng của vấn đề nhân viên bán hàng du lịch.) Thời gian đi lại 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 và nhiều yếu tố khác có thể được xem xét khi quyết định tuyến đường hiệu quả nhất. Tất cả điểm trung gian phải là điểm dừng để dịch vụ Chỉ đường tối ưu hoá tuyến đường của họ.

Nếu bạn hướng dẫn dịch vụ Chỉ đường tối ưu hoá thứ tự 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 trung gian. (Để 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 ý: Chúng tôi kiểm tra routes.start_addressroutes.end_address để cung cấp cho chúng tôi văn bản cho điểm bắt đầu và điểm kết thúc của mỗi tuyến.

TypeScript

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

  directionsRenderer.setMap(map);

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

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

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

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

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

      summaryPanel.innerHTML = "";

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

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

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

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à hạn chế đối với Điểm tham chiếu

Những hạn chế và hạn chế sử dụng sau đây được áp dụng:

  • Số lượng điểm trung bình tối đa được phép khi sử dụng dịch vụ Chỉ đường trong API Maps JavaScript là 25 điểm, cộng với điểm khởi hành và điểm đến. Giới hạn tương tự cũng áp dụng đối với dịch vụ web Chỉ đường API.
  • Đối với dịch vụ web Chỉ đường API, khách hàng được phép sử dụng 25 điểm tham chiếu, cùng với điểm khởi hành và điểm đến.
  • Khách hàng sử dụng Gói cao cấp của Nền tảng Google Maps được phép sử dụng 25 điểm trung gian, cùng với điểm khởi hành và điểm đến.
  • Hệ thống không hỗ trợ điểm tham chiếu cho chỉ đường phương tiện.

Đườ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 hiển thị bằng cách sử dụng DirectionsRenderer một cách linh động nếu chúng có thể kéo được, cho phép người dùng chọn và thay đổi các tuyến đường bằng cách nhấp và kéo các đường dẫn thu được trên bản đồ. Bạn cho biết liệu màn hình của trình kết xuất có cho phép hướng dẫn kéo bằng cách đặt thuộc tính draggable của nó thành true hay không. Bạn không thể kéo đường đi bằng phương tiện công cộng.

Khi đường đi có thể kéo được, người dùng có thể chọn bất kỳ điểm nào trên đường dẫn (hoặc điểm tham chiếu) của kết quả kết xuất và di chuyển thành phần được chỉ định đến một vị trí mới. DirectionsRenderer sẽ tự động cập nhật để hiển thị đường dẫn đã sửa đổi. Khi phát hành, một điểm trung gian 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 dẫn sẽ thay đổi chân 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ẽ thay đổi các chặng của tuyến đường đi qua điểm tham chiếu đó.

Vì thông tin đườ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ể theo dõi và xử lý sự kiện directions_changed trên DirectionsRenderer để nhận thông báo khi người dùng sửa đổi hướng đi được hiển thị.

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

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ụ

Thử mẫu