Khi API Tuyến tính tính một tuyến, API này sẽ lấy các điểm tham chiếu và mà bạn cung cấp làm đầu vào. Sau đó, API này sẽ trả về một phản hồi có chứa tuyến đường mặc định và một hoặc nhiều tuyến thay thế.
Câu trả lời của bạn có thể bao gồm nhiều loại tuyến đường và dữ liệu khác, dựa trên các trường bạn yêu cầu:
Để đưa nội dung này vào câu trả lời | Hãy 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ế |
Hình nhiều đường 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ân. | Yêu cầu hình nhiều đường tuyến đường |
Phí cầu đường ước tính, có tính đến mọi khoản chiết khấu theo giá cầu đường hoặc thẻ và vé dành cho người lái xe hoặc phương tiện. | Tính phí cầu đường |
Phản hồi được bản địa hoá theo mã ngôn ngữ và đơn vị đo lường (hệ thống Vương quốc Anh hoặc chỉ số). | 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 |
Các phép tính bổ sung |
Để xem danh sách đầy đủ các tuỳ chọn nhập, hãy xem Các tuỳ chọn tuyến đường có sẵn và Nội dung yêu cầu.
Bằng cách sử dụng câu trả lời, bạn có thể cung cấp thông tin cho khách hàng để chọn tuyến đường 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 một tuyến đường, bạn phải chỉ định một trường mặt nạ xác định các trường bạn muốn được trả về trong phản hồi. Không có danh sách mặc định 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ề .
Các ví dụ trong tài liệu này hiển thị toàn bộ đối tượng phản hồi mà không cần lấy mặt nạ thực địa. 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ả lại.
Giới thiệu về việc hiển thị bản quyền
Bạn phải đính kè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, số chân và số bước
Trước khi xem phản hồi do Routes API trả về, bạn phải hiểu được các thành phần tạo nên một tuyến đường:
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ộ chuyến đi từ điểm tham chiếu gốc, qua bất kỳ điểm tham chiếu nào điểm tham chiếu trung gian đến điểm tham chiếu đích. Một tuyến đường gồm một hoặc nhiều chân hơn.
Chân: Con đường từ một điểm tham chiếu trong một tuyến đường đến điểm tham chiếu tiếp theo trong tuyến đường. Mỗi chân bao gồm một hoặc nhiều bước riêng biệt.
Một tuyến đường chứa một chặng riêng biệt dành cho đường đi từ mỗi điểm tham chiếu đến điểm tham chiếu tiếp theo. Ví dụ: nếu tuyến chứa một điểm tham chiếu gốc và một điểm tham chiếu gốc điểm tham chiếu đích, thì tuyến đường chứa một chặng. Đối với mỗi điểm tham chiếu bổ sung mà bạn thêm vào tuyến đường sau điểm khởi hành và điểm đến, có tên là điểm tham chiếu trung gian, API sẽ thêm một chân riêng.
API không thêm chân cho điểm trung gian chuyển qua. Cho ví dụ: một tuyến chứa điểm tham chiếu gốc, một đường truyền xuyên qua điểm tham chiếu trung gian và điểm tham chiếu đích chỉ chứa một chặng từ từ điểm gốc đến đích trong khi đi qua điểm tham chiếu. Để biết thêm thông tin về các điểm tham chiếu cụ thể, hãy xem Xác định điểm tham chiếu truyền.
Bước: Một chỉ dẫn duy nhất dọc theo đoạn đường của một tuyến đường. Một bước là quan trọng nhất đơn vị nguyên tử của một tuyến đường. Ví dụ: một bước có thể biểu thị "Rẽ trái trên đường Chính Đường phố''.
Nội dung phản hồi
Đối tượng JSON biểu thị phản hồi của API chứa các thuộc tính cấp cao nhất sau đây:
routes
, một mảng các phần tử thuộc loại Tuyến đường. Mảngroutes
chứa một phần tử cho mỗi tuyến do API trả về. Mảng có thể chứa tối đa năm phần tử: tuyến mặc định, tuyến đường 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 (gốc, đích hoặc trung gian tham chiếu) mà bạn đã chỉ định làm 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í. Vị trí trong yêu cầu được chỉ định là mã địa điểm hoặc vĩ độ/kinh độ không được bao gồm. Nếu bạn đã chỉ định tất cả các vị trí bằng mã địa điểm hoặc vĩ độ và kinh độ toạ độ thì mảng này không được cung cấp.fallbackInfo
, thuộc loại FallbackInfo. Nếu API không thể tính toán một tuyến từ tất cả thuộc tính đầu vào, thì có thể phương thức tính đó là dùng một phương pháp tính toán khác. Khi dự phòng được sử dụng, trường này chứa thông tin chi tiết về chế độ dự phòng của bạn. Nếu không, trường này sẽ không được đặt.
Câu trả lờ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 đường
Phản hồi chứa mảng routes
, trong đó mỗi phần tử mảng là một loại
Tuyến đường.
Mỗi phần tử mảng đại diện cho toàn bộ một tuyến từ điểm gốc tới đích. Chiến lược phát hành đĩa đơ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 đường. Nếu bạn yêu cầu một
tuyến đường thân thiện với môi trường thì mảng có thể chứa 2 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 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 |
T chỉ định một tuyến đường thay thế. |
Mảng legs
chứa định nghĩa của từng chặng của tuyến đường. Phần còn lại
các thuộc tính, 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ũng có thể giống như vậy. 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 mảng legs
phần tử thuộc loại
RouteLeg.
Mỗi chân trong mảng xác định đường dẫn từ một điểm tham chiếu đến điểm tham chiếu tiếp theo
dọc theo 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 của 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ặng đó.
{ "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 bước
Mỗi chân trong phản hồi chứa một mảng steps
, trong đó mỗi mảng steps
phần tử 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. Chân luôn chứa
ít nhất một bước.
Mỗi phần tử trong mảng steps
đều có navigationInstruction
thuộc tính, loại
NavigationInstruction,
chứa hướng dẫn bước. Ví dụ:
"navigationInstruction": { "maneuver": "TURN_LEFT", "instructions": "Turn left toward Frontage Rd" }
instructions
có thể chứa thông tin bổ sung 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 này, chẳng hạn như
dưới dạng 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 các bước
API trả về thông tin tuyến đường bằng ngôn ngữ địa phương, được chuyển tự sang tập lệnh mà người dùng có thể đọc được, nếu cần, trong khi vẫn quan sát ngôn ngữ. Tất cả các thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ.
Dùng tham số
languageCode
của yêu cầu đến đặt rõ ràng ngôn ngữ tuyến đường từ danh sách các ngôn ngữ được hỗ trợ ngôn ngữ. Google thường cập nhật các nên danh sách này có thể chưa đầy đủ.Nếu tên không có sẵn bằng ngôn ngữ được chỉ định, API sẽ sử dụng kết quả phù hợp 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ề. Chiến lược phát hành đĩa đơn bộ mã hoá địa lý diễn giải chữ viết tắt theo cách khác nhau tuỳ thuộc vào ngôn ngữ, chẳng hạn như những từ viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ trong một nhưng không được trình bày bằng ngôn ngữ khác. Ví dụ: utca và tér là từ đồng nghĩa với đường phố bằng tiếng Hungary.
Hiểu mảng mã hoá địa lý kết quả
Đối với mọi vị trí trong yêu cầu (gốc, đích hoặc trung gian
tham chiếu) được chỉ định dưới dạng chuỗi địa chỉ hoặc Mã cộng, thì
API cố gắng tìm vị trí có liên quan nhất có địa điểm tương ứng
Mã nhận dạng. Mỗi phần tử của
geocodingResults
mảng chứa trường placeID
chứa vị trí dưới dạng mã địa điểm và trường type
chỉ định vị trí
chẳng hạn như street_address
, premise
hoặc airport
.
Mảng geocodingResults
chứa 3 trường:
origin
: Nếu được chỉ định dưới dạng chuỗi địa chỉ hoặc dưới dạng mã Cộng, mã địa điểm của điểm khởi hành. Nếu không, trường này sẽ bị bỏ qua trong câu trả lời.destination
: Nếu được chỉ định dưới dạng chuỗi địa chỉ hoặc dưới dạng mã Cộng, mã địa điểm của điểm đến. Nếu không, trường này sẽ bị bỏ qua của bạn.intermediates
: Một mảng chứa mã địa điểm của bất kỳ đơn vị trung gian nào điểm tham chiếu được chỉ định làm chuỗi địa chỉ hoặc mã Cộng. Nếu bạn chỉ định một điểm tham chiếu trung gian sử dụng mã địa điểm hoặc vĩ độ và kinh độ, toạ độ này bị lược bỏ khỏi câu trả lời. Sử dụngintermediateWaypointRequestIndex
thuộc tính trong phản hồi để xác định điểm tham chiếu trung gian trong yêu cầu tương ứng với mã địa điểm trong nội dung 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 các giá trị của câu trả lời đã bản địa hoá
Giá trị phản hồi đã bản địa hoá là trường phản hồi bổ sung cung cấp văn bản được bản địa hoá cho các giá trị tham số được trả về. Văn bản đã 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 mặt nạ trường, đồng thời có thể chỉ định ngôn ngữ và hệ thống đơn vị quảng cáo hoặc sử dụng các giá trị do API suy ra. Để biết thông tin chi tiết, hãy xem LocalizedValues (Giá trị đã bản địa hoá).
Ví dụ: nếu bạn chỉ định mã ngôn ngữ cho tiếng Đức (de) và hệ Anh
đơn vị, bạn sẽ nhận được giá trị của distanceMeters
là 49889,7,
mà còn bản địa hoá văn bản cung cấp số liệu đo khoảng cách bằng tiếng Đức và
đơn vị hệ đo lường của Hoa Kỳ, nên "31 Meile".
Dưới đây là ví dụ về những gì 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 ra ngôn ngữ và đơn vị như sau:
- Phương thức
ComputeRoutes
dự đoán vị trí và khoảng cách đơn vị từ điểm tham chiếu gốc. Vì vậy, đối với yêu cầu định tuyến ở Hoa Kỳ, API suy raen-US
ngôn ngữ vàIMPERIAL
đơn vị. - Phương thức
ComputeRouteMatrix
mặc định là "en-US" ngôn ngữ và METRIC.