Khi tính toán một tuyến đường, Routes API sẽ lấy các điểm trung gian và thông số cấu hình mà bạn cung cấp làm dữ liệu đầu vào. Sau đó, API sẽ trả về một phản hồi chứa tuyến mặc định và một hoặc nhiều tuyến thay thế.
Phản hồi của bạn có thể bao gồm nhiều loại tuyến và dữ liệu khác, dựa trên các trường mà bạn yêu cầu:
| Cách đưa thông tin này vào nội dung phản hồi | Xem tài liệu này |
|---|---|
| Tuyến đường tiết kiệm nhiên liệu hoặc năng lượng nhất dựa trên loại động cơ của xe. | Định cấu hình tuyến đường Thân thiện với môi trường |
| Tối đa 3 tuyến đường thay thế | Yêu cầu tuyến đường thay thế |
| Đường đa tuyến cho toàn bộ tuyến đường, cho mỗi chặng của tuyến đường và cho mỗi bước của một chặng. | Yêu cầu đường đa tuyến của tuyến đường |
| Phí cầu đường ước tính, có tính đến mọi khoản chiết khấu phí cầu đường hoặc thẻ đi qua cầu đường mà người lái xe hoặc xe có thể sử dụng. | Tính phí cầu đường |
| Câu trả lời được bản địa hoá theo mã ngôn ngữ và đơn vị đo lường (hệ đo lường Anh hoặc hệ đo lường quốc tế). | Yêu cầu giá trị đã bản địa hoá |
Để định dạng hướng dẫn điều hướng dưới dạng chuỗi văn bản HTML, hãy thêm HTML_FORMATTED_NAVIGATION_INSTRUCTIONS vào extraComputations. |
Tính toán bổ sung |
Để biết danh sách đầy đủ các tuỳ chọn đầu vào, hãy xem Các tuỳ chọn tuyến đường hiện có và Phần nội dung yêu cầu.
Bằng cách sử dụng phản hồi, bạn có thể cung cấp cho khách hàng thông tin cần thiết để chọn tuyến phù hợp với yêu cầu của họ.
Giới thiệu về mặt nạ trường
Khi gọi một phương thức để tính toán tuyến đường, bạn phải chỉ định một mặt nạ trường xác định những trường mà bạn muốn trả về trong phản hồi. Không có danh sách mặc định về các trường được trả về. Nếu bạn bỏ qua danh sách này, các phương thức sẽ trả về lỗi.
Các ví dụ trong tài liệu này cho thấy toàn bộ đối tượng phản hồi mà không xem xét mặt nạ trường. Trong môi trường phát hành công khai, phản hồi của bạn sẽ chỉ bao gồm các trường mà bạn chỉ định rõ ràng trong mặt nạ trường.
Để biết thêm thông tin, hãy xem phần Chọn thông tin cần trả về.
Giới thiệu về việc hiển thị bản quyền
Bạn phải thêm tuyên bố bản quyền sau đây khi hiển thị kết quả cho người dùng:
Powered by Google, ©YEAR Google
Ví dụ:
Powered by Google, ©2023 Google
Giới thiệu về tuyến đường, chặng và bước
Trước khi xem phản hồi do Routes API trả về, bạn nên hiểu rõ các thành phần tạo nên một tuyến:
Nội dung phản hồi của bạn có thể chứa thông tin về từng thành phần tuyến đường sau:
Tuyến đường: Toàn bộ hành trình từ điểm trung gian, thông qua mọi điểm trung gian, đến điểm trung gian đích. Một tuyến đường bao gồm một hoặc nhiều đoạn.
Đoạn: Đường dẫn từ một điểm trung gian trong tuyến đến điểm trung gian tiếp theo trong tuyến. Mỗi chặng bao gồm một hoặc nhiều bước riêng biệt.
Một tuyến chứa một chặng riêng cho đường dẫn từ mỗi điểm trung gian đến điểm trung gian tiếp theo. Ví dụ: nếu tuyến chứa một điểm trung gian xuất phát và một điểm trung gian đích, thì tuyến đó chứa một chặng. Đối với mỗi điểm trung gian mà bạn thêm vào tuyến đường sau điểm xuất phát và điểm đến, được gọi là điểm trung gian, API sẽ thêm một chặng riêng.
API không thêm một chặng cho điểm trung gian đi qua. Ví dụ: một tuyến đường chứa điểm trung gian xuất phát, điểm trung gian đi qua và điểm trung gian đích chỉ chứa một chặng từ điểm xuất phát đến điểm đến, trong khi đi qua điểm trung gian. Để biết thêm thông tin về điểm trung chuyển, hãy xem phần Xác định điểm trung chuyển.
Bước: Một hướng dẫn duy nhất dọc theo chặng của tuyến. Bước là đơn vị nguyên tử nhất của một tuyến. Ví dụ: một bước có thể cho biết "Rẽ trái vào đường Main".
Nội dung trong phản hồi
Đối tượng JSON đại diện cho phản hồi API chứa các thuộc tính cấp cao nhất sau:
routes, một mảng các phần tử thuộc loại Tuyến. Mảngrouteschứa một phần tử cho mỗi tuyến đường do API trả về. Mảng này có thể chứa tối đa 5 phần tử: tuyến đường mặc định, tuyến đường thân thiện với môi trường và tối đa 3 tuyến đường thay thế.geocodingResults, một mảng các phần tử thuộc loại GeocodingResults. Đối với mọi vị trí trong yêu cầu (điểm xuất phát, điểm đến hoặc điểm trung gian) mà bạn chỉ định dưới dạng chuỗi địa chỉ hoặc Mã cộng, API sẽ thực hiện tra cứu mã địa điểm. Mỗi phần tử của mảng này chứa mã địa điểm tương ứng với một vị trí. Các vị trí trong yêu cầu được chỉ định là mã địa điểm hoặc tọa độ vĩ độ/kinh độ sẽ không được đưa vào. Nếu bạn đã chỉ định tất cả vị trí bằng mã địa điểm hoặc toạ độ vĩ độ và kinh độ, thì hệ thống sẽ không cung cấp mảng này.fallbackInfo, thuộc loại FallbackInfo. Nếu không thể tính toán một tuyến từ tất cả các thuộc tính đầu vào, API có thể sử dụng một phương thức tính toán khác. Khi chế độ dự phòng được sử dụng, trường này sẽ chứa thông tin chi tiết về phản hồi dự phòng. Nếu không, trường này sẽ không được đặt.
Phản hồi có dạng:
{
// The routes array.
"routes": [
{
object (Route)
}
],
// The place ID lookup results.
"geocodingResults": [
{
object (GeocodedWaypoint)
}
],
// The fallback property.
"fallbackInfo": {
object (FallbackInfo)
}
}
Giải mã mảng tuyến
Phản hồi chứa mảng routes, trong đó mỗi phần tử mảng thuộc loại Tuyến.
Mỗi phần tử mảng đại diện cho toàn bộ tuyến đường từ điểm xuất phát đến điểm đến. API luôn trả về ít nhất một tuyến, được gọi là tuyến mặc định.
Bạn có thể yêu cầu thêm tuyến. Nếu bạn yêu cầu tuyến đường thân thiện với môi trường, thì mảng có thể chứa hai phần tử: tuyến đường mặc định và tuyến đường thân thiện với môi trường. Hoặc đặt computeAlternativeRoutes thành true trong yêu cầu để thêm tối đa 3 tuyến đường thay thế vào phản hồi.
Mỗi tuyến trong mảng được xác định bằng thuộc tính mảng routeLabels:
| Giá trị | Mô tả |
|---|---|
DEFAULT_ROUTE |
Xác định tuyến mặc định. |
FUEL_EFFICIENT |
Xác định tuyến đường thân thiện với môi trường. |
DEFAULT_ROUTE_ALTERNATE |
I cho biết một tuyến đường thay thế. |
Mảng legs chứa định nghĩa về từng chặng của tuyến đường. Các thuộc tính còn lại, chẳng hạn như distanceMeters, duration và polyline, chứa thông tin về toàn bộ tuyến đường:
{
"routeLabels": [
enum (RouteLabel)
],
"legs": [
{
object (RouteLeg)
}
],
"distanceMeters": integer,
"duration": string,
"routeLabels": [string],
"staticDuration": string,
"polyline": {
object (Polyline)
},
"description": string,
"warnings": [
string
],
"viewport": {
object (Viewport)
},
"travelAdvisory": {
object (RouteTravelAdvisory)
}
"routeToken": string
}
Do điều kiện lái xe hiện tại và các yếu tố khác, tuyến đường mặc định và tuyến đường thân thiện với môi trường có thể giống nhau. Trong trường hợp này, mảng routeLabels chứa cả hai nhãn: DEFAULT_ROUTE và FUEL_EFFICIENT.
{
"routes": [
{
"routeLabels": [
"DEFAULT_ROUTE",
"FUEL_EFFICIENT"
],
…
}
]
}
Tìm hiểu về mảng chân
Mỗi route trong phản hồi chứa một mảng legs, trong đó mỗi phần tử mảng legs thuộc loại RouteLeg.
Mỗi chặng trong mảng xác định đường dẫn từ một điểm trung gian đến điểm trung gian tiếp theo trên tuyến đường. Một tuyến đường luôn chứa ít nhất một chặng.
Thuộc tính legs chứa định nghĩa về từng bước dọc theo chân trong mảng steps. Các thuộc tính còn lại, chẳng hạn như distanceMeters, duration và polyline chứa thông tin về chân.
{
"distanceMeters": integer,
"duration": string,
"staticDuration": string,
"polyline": {
object (Polyline)
},
"startLocation": {
object (Location)
},
"endLocation": {
object (Location)
},
"steps": [
{
object (RouteLegStep)
}
],
"travelAdvisory": {
object (RouteLegTravelAdvisory)
}
}
Tìm hiểu về mảng steps
Mỗi chặng trong phản hồi chứa một mảng steps, trong đó mỗi phần tử mảng steps thuộc loại RouteLegStep.
Một bước tương ứng với một hướng dẫn dọc theo chân. Một chặng luôn chứa ít nhất một bước.
Mỗi phần tử trong mảng steps bao gồm thuộc tính navigationInstruction thuộc loại NavigationInstruction chứa hướng dẫn từng bước. Ví dụ:
"navigationInstruction": {
"maneuver": "TURN_LEFT",
"instructions": "Turn left toward Frontage Rd"
}
instructions có thể chứa thêm thông tin về bước này. Ví dụ:
"navigationInstruction": {
"maneuver": "TURN_SLIGHT_LEFT",
"instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days"
}
Các thuộc tính còn lại trong bước này mô tả thông tin về bước đó, chẳng hạn như distanceMeters, duration và polyline:
{
"distanceMeters": integer,
"staticDuration": string,
"polyline": {
object (Polyline)
},
"startLocation": {
object (Location)
},
"endLocation": {
object (Location)
},
"navigationInstruction": {
object (NavigationInstruction)
}
}
Chỉ định ngôn ngữ của hướng dẫn từng bước
API trả về thông tin tuyến đường bằng ngôn ngữ địa phương, được chuyển tự sang một tập lệnh mà người dùng có thể đọc được (nếu cần), đồng thời tuân theo ngôn ngữ ưu tiên. Tất cả thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ.
Sử dụng tham số
languageCodecủa một yêu cầu để đặt rõ ràng ngôn ngữ tuyến từ danh sách ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể chưa đầy đủ.Nếu không có tên nào bằng ngôn ngữ đã chỉ định, API sẽ sử dụng tên khớp gần nhất.
Ngôn ngữ được chỉ định có thể ảnh hưởng đến tập hợp kết quả mà API chọn trả về và thứ tự trả về các kết quả đó. Trình mã hoá địa lý diễn giải các từ viết tắt theo cách khác nhau tuỳ theo ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường hoặc từ đồng nghĩa có thể hợp lệ trong một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác. Ví dụ: utca và tér là từ đồng nghĩa với đường trong tiếng Hungary.
Tìm hiểu về mảng geocodingResults
Đối với mọi vị trí trong yêu cầu (điểm xuất phát, điểm đến hoặc điểm trung gian) được chỉ định dưới dạng chuỗi địa chỉ hoặc Mã cộng, API sẽ cố gắng tìm vị trí phù hợp nhất có mã địa điểm tương ứng. Mỗi phần tử của mảng geocodingResults chứa trường placeID chứa vị trí dưới dạng mã địa điểm và trường type chỉ định loại vị trí, chẳng hạn như street_address, premise hoặc airport.
Mảng geocodingResults chứa ba trường:
origin: Nếu được chỉ định dưới dạng chuỗi địa chỉ hoặc mã Plus, thì mã địa điểm của điểm xuất phát. Nếu không, trường này sẽ bị bỏ qua trong phản hồi.destination: Nếu được chỉ định dưới dạng chuỗi địa chỉ hoặc mã Plus, thì mã nhận dạng địa điểm của đích đến. Nếu không, trường này sẽ bị bỏ qua trong phản hồi.intermediates: Một mảng chứa mã địa điểm của mọi điểm trung gian được chỉ định dưới dạng chuỗi địa chỉ hoặc mã Plus. Nếu bạn chỉ định điểm trung gian bằng mã địa điểm hoặc toạ độ vĩ độ và kinh độ, thì điểm trung gian đó sẽ bị bỏ qua trong phản hồi. Sử dụng thuộc tínhintermediateWaypointRequestIndextrong phản hồi để xác định điểm trung gian nào trong yêu cầu tương ứng với mã địa điểm trong phản hồi.
"geocodingResults": {
"origin": {
"geocoderStatus": {},
"type": [
enum (Type)
],
"placeId": string
},
"destination": {
"geocoderStatus": {},
"type": [
enum (Type)
],
"placeId": string
},
"intermediates": [
{
"geocoderStatus": {},
"intermediateWaypointRequestIndex": integer,
"type": [
enum (Type)
],
"placeId": string
},
{
"geocoderStatus": {},
"intermediateWaypointRequestIndex": integer,
"type": [
enum (Type)
],
"placeId": string
}
]
}
Tìm hiểu về giá trị phản hồi đã bản địa hoá
Giá trị phản hồi đã bản địa hoá là một trường phản hồi bổ sung cung cấp văn bản đã bản địa hoá cho các giá trị tham số được trả về. Văn bản được bản địa hoá được cung cấp cho thời lượng chuyến đi, quãng đường và hệ thống đơn vị (theo hệ mét hoặc hệ đo lường Anh). Bạn yêu cầu các giá trị được bản địa hoá bằng cách sử dụng mặt nạ trường và có thể chỉ định ngôn ngữ và hệ thống đơn vị hoặc sử dụng các giá trị mà API suy luận. Để biết thông tin chi tiết, hãy xem phần LocalizedValues.
Ví dụ: nếu chỉ định mã ngôn ngữ cho tiếng Đức (de) và đơn vị đo lường theo hệ thống Anh, bạn sẽ nhận được giá trị 49889, 7 cho distanceMeters, nhưng cũng có văn bản được bản địa hoá cung cấp thông tin đo lường khoảng cách đó bằng tiếng Đức và đơn vị đo lường theo hệ thống Anh, tức là "31 Meile".
Dưới đây là ví dụ về nội dung bạn sẽ thấy đối với các giá trị đã bản địa hoá:
{ "localized_values":
{
"distance": { "text": "31,0 Meile/n" },
"duration": { "text": 38 Minuten}.
"static_duration": { "text": 36 Minuten}.
}
}
Nếu bạn không chỉ định ngôn ngữ hoặc hệ thống đơn vị, API sẽ suy luận ngôn ngữ và đơn vị như sau:
- Phương thức
ComputeRoutessuy luận vị trí và đơn vị khoảng cách từ điểm trung gian gốc. Vì vậy, đối với yêu cầu định tuyến ở Hoa Kỳ, API sẽ suy luận ngôn ngữen-USvà đơn vịIMPERIAL. - Phương thức
ComputeRouteMatrixmặc định là ngôn ngữ "en-US" và đơn vị METRIC.