Phương thức computeRoutes (REST) và phương thức ComputeRoutes (gRPC) đều trả về tuyến đường được biểu thị bằng một đa tuyến trong phản hồi. Các API này trả về hai loại đa tuyến:
Đường đa tuyến cơ bản (mặc định), biểu thị một tuyến đường nhưng không có thông tin giao thông được nhúng trong đường đa tuyến. Các yêu cầu trả về một đa tuyến cơ bản sẽ được tính phí theo mức giá cơ bản của Routes. Tìm hiểu thêm về việc thanh toán cho Routes API.
Đường đa tuyến có nhận biết tình trạng giao thông, chứa thông tin về tình trạng giao thông trên tuyến đường. Tình trạng giao thông được thể hiện theo các danh mục tốc độ (
NORMAL,SLOW,TRAFFIC_JAM) áp dụng trên một khoảng thời gian nhất định của đường đa tuyến. Các yêu cầu về đường đa tuyến có tính năng nhận biết lưu lượng truy cập sẽ được tính phí theo mức giá Routes Preferred. Tìm hiểu thêm về cách thanh toán cho Route API. Để biết thông tin chi tiết, hãy xem phần Định cấu hình chất lượng đường đa tuyến
Để biết thêm về đa tuyến, hãy xem:
Tiện ích bộ mã hoá đường đa giác tương tác cho phép bạn tạo đường đa giác được mã hoá trong giao diện người dùng hoặc giải mã đường đa giác để hiển thị trên bản đồ. Ví dụ: sử dụng tiện ích này để giải mã một đường đa tuyến do mã bên dưới tạo.
Yêu cầu một đường đa giác cơ bản cho một tuyến đường, chặng hoặc bước
Một đường đa tuyến được biểu thị bằng đối tượng Polyline (REST) hoặc Polyline (gRPC). Bạn có thể trả về một đa tuyến trong phản hồi ở cấp tuyến, chặng và bước.
Chỉ định đường đa tuyến cần trả về bằng cách sử dụng mặt nạ trường phản hồi:
Ở cấp tuyến, hãy trả về một đa tuyến trong phản hồi bằng cách đưa
routes.polylinevào mặt nạ trường phản hồi.Ở cấp chặng, hãy trả về một đa tuyến trong phản hồi cho mỗi chặng của tuyến đường bằng cách đưa vào
routes.legs.polyline.Ở cấp bước, hãy trả về một đa tuyến trong phản hồi cho mỗi bước của chân bằng cách đưa vào
routes.legs.steps.polyline.
Ví dụ: để trả về một đa tuyến cho toàn bộ tuyến đường, cho mỗi chặng và cho từng bước của mỗi chặng:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Yêu cầu này trả về phản hồi sau đây, bao gồm đường đa tuyến cho tuyến đường, cho mỗi chặng của tuyến đường và cho mỗi bước của chặng:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } }, "steps": [ { "polyline": { "encodedPolyline": "kclcF...@sC@YIOKI" } }, { "polyline": { "encodedPolyline": "wblcF~...SZSF_@?" } }, ... ], "distanceMeters": 56901, "duration": "2420s", "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } } ] }
Vì yêu cầu này chỉ chứa một điểm xuất phát và một điểm đến, nên tuyến đường được trả về chỉ chứa một chặng. Do đó, hình nhiều đường cho chặng và cho tuyến đường là giống nhau.
Nếu bạn thêm một điểm trung gian vào yêu cầu, thì tuyến đường được trả về sẽ chứa hai chặng:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "intermediates": [ { "address": "450 Serra Mall, Stanford, CA 94305, USA"}, ], "travelMode": "DRIVE", }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Yêu cầu này trả về hai chặng, mỗi chặng có một đa tuyến riêng biệt và một đa tuyến cho toàn bộ tuyến:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG" } "steps": [ { "polyline": { "encodedPolyline": "kclcFfqch...YIOKI" } }, ... }, { "polyline": { "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G" } "steps": [ { "polyline": { "encodedPolyline": "uypeFbo`jVgJq...PoBiC" } }, ... } ], "distanceMeters": 68403, "duration": "3759s", "polyline": { "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE" } } ] }
Chất lượng đường đa tuyến
Chất lượng của một đa tuyến có thể được mô tả theo các thuật ngữ sau:
Độ chính xác dấu phẩy động của các điểm
Các điểm được chỉ định dưới dạng giá trị vĩ độ và kinh độ, được biểu thị ở định dạng dấu phẩy động có độ chính xác đơn. Phương thức này hoạt động tốt đối với các giá trị nhỏ (có thể được biểu thị chính xác), nhưng độ chính xác sẽ giảm khi giá trị tăng lên do lỗi làm tròn dấu phẩy động.
Trong phương thức computeRoutes (REST) và ComputeRoutes, việc này do
polylineEncodingkiểm soát.Số điểm tạo nên đường đa tuyến
Càng có nhiều điểm thì đường đa tuyến càng mượt (đặc biệt là trong các đường cong).
Trong phương thức computeRoutes (REST) và ComputeRoutes, việc này do
polylineQualitykiểm soát.
Định cấu hình loại mã hoá đường đa tuyến
Sử dụng tuỳ chọn yêu cầu polylineEncoding để kiểm soát loại đường đa tuyến.
Thuộc tính polylineEncoding kiểm soát việc đường đa tuyến có được mã hoá dưới dạng ENCODED_POLYLINE (mặc định) hay không, nghĩa là Định dạng thuật toán đường đa tuyến được mã hoá sẽ được sử dụng hoặc GEO_JSON_LINESTRING, nghĩa là Định dạng GeoJSON LineString sẽ được sử dụng.
Ví dụ: trong phần nội dung yêu cầu:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE", "polylineEncoding": "ENCODED_POLYLINE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Định cấu hình chất lượng của đường đa tuyến
polylineQuality chỉ định chất lượng của đường đa tuyến là HIGH_QUALITY hoặc OVERVIEW (mặc định). Với OVERVIEW, đa tuyến được tạo bằng một số điểm nhỏ và có độ trễ yêu cầu thấp hơn HIGH_QUALITY.
Ví dụ: trong phần nội dung yêu cầu:
{ "origin":{ "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0827784 } } }, "destination":{ "location":{ "latLng":{ "latitude": 37.417670, "longitude": -122.079595 } } }, "travelMode": "DRIVE", "routingPreference": "TRAFFIC_AWARE", "polylineQuality": "HIGH_QUALITY", "polylineEncoding": "ENCODED_POLYLINE", "departureTime": "2023-10-15T15:01:23.045123456Z", ... }
Yêu cầu đường đa tuyến có tính năng nhận biết tình trạng giao thông
Các ví dụ hiển thị ở trên đều trả về các đa tuyến cơ bản, nghĩa là các đa tuyến không có thông tin giao thông. Ngoài ra, bạn cũng có thể yêu cầu đường đa tuyến chứa thông tin về tình trạng giao thông cho tuyến đường và cho từng chặng của tuyến đường.
Đường đa tuyến có tính năng nhận biết tình trạng giao thông chứa thông tin về tình trạng giao thông dọc theo tuyến đường. Tình trạng giao thông được biểu thị theo các danh mục tốc độ (NORMAL, SLOW, TRAFFIC_JAM) cho một khoảng thời gian nhất định của đường đa tuyến phản hồi. Các khoảng thời gian được xác định bằng chỉ mục của các điểm bắt đầu (bao gồm) và điểm kết thúc (không bao gồm) của đường đa tuyến.
Ví dụ: phản hồi sau đây cho thấy lưu lượng truy cập NORMAL giữa các điểm đường đa tuyến 2 và 4:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Để tạo yêu cầu tính toán đường đa tuyến có tính đến lưu lượng truy cập, hãy đặt các thuộc tính sau trong yêu cầu:
Đặt trường mảng
extraComputationsthànhTRAFFIC_ON_POLYLINEđể bật tính năng tính lưu lượng truy cập.Đặt
travelModethànhDRIVEhoặcTWO_WHEELER. Yêu cầu về bất kỳ phương tiện di chuyển nào khác sẽ trả về lỗi.Chỉ định tuỳ chọn định tuyến
TRAFFIC_AWAREhoặcTRAFFIC_AWARE_OPTIMALtrong yêu cầu. Để biết thêm thông tin, hãy xem phần Định cấu hình chất lượng so với độ trễ.Đặt mặt nạ trường phản hồi chỉ định trả về các thuộc tính phản hồi:
Ở cấp tuyến, hãy trả về tất cả thông tin về chuyến đi trong phản hồi bằng cách đưa
routes.travelAdvisoryvào mặt nạ trường phản hồi. Để chỉ trả về thông tin về lưu lượng truy cập, hãy chỉ địnhroutes.travelAdvisory.speedReadingIntervalsỞ cấp chặng, hãy trả về tất cả thông tin về chuyến đi trong phản hồi cho từng chặng của tuyến đường bằng cách thêm
routes.legs.travelAdvisory. Để chỉ trả về thông tin về lưu lượng truy cập, hãy chỉ địnhroutes.legs.travelAdvisory.speedReadingIntervals.
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE", "extraComputations": ["TRAFFIC_ON_POLYLINE"], "routingPreference": "TRAFFIC_AWARE_OPTIMAL" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Ví dụ về phản hồi cho đường đa tuyến có nhận biết được lưu lượng truy cập
Trong phản hồi, dữ liệu giao thông được mã hoá trong đường đa tuyến và nằm trong trường travelAdvisory, thuộc loại đối tượng RouteLegTravelAdvisory (mỗi chặng) và đối tượng RouteTravelAdvisory (tuyến).
Ví dụ:
{ "routes": [ { "legs": { "polyline": { "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD" }, // Traffic data for the leg. "travelAdvisory": { "speedReadingIntervals": [ { "endPolylinePointIndex": 1, "speed": "NORMAL" }, { "startPolylinePointIndex": 1, "endPolylinePointIndex": 2, "speed": "SLOW" }, { "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" } ] } }, "polyline": { "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD" }, // Traffic data for the route. "travelAdvisory": { "speedReadingIntervals": [ { "endPolylinePointIndex": 1, "speed": "NORMAL" }, { "startPolylinePointIndex": 1, "endPolylinePointIndex": 2, "speed": "SLOW" }, { "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" } ] } } ] }
Cả RouteTravelAdvisory và RouteLegTravelAdvisory đều có một trường mảng tên là speedReadingIntervals chứa thông tin về tốc độ giao thông. Mỗi đối tượng trong mảng được biểu thị bằng đối tượng SpeedReadingInterval (REST) hoặc SpeedReadingInterval (gRPC).
Đối tượng SpeedReadingInterval bao gồm thông tin đọc tốc độ cho một khoảng thời gian trên tuyến đường, chẳng hạn như NORMAL, SLOW hoặc TRAFFIC_JAM. Toàn bộ mảng đối tượng bao phủ toàn bộ đường đa tuyến của tuyến đường mà không bị chồng chéo. Điểm bắt đầu của một khoảng thời gian được chỉ định giống với điểm kết thúc của khoảng thời gian trước đó.
Mỗi khoảng thời gian được mô tả bằng startPolylinePointIndex, endPolylinePointIndex và danh mục tốc độ tương ứng.
Lưu ý rằng việc thiếu chỉ mục bắt đầu trong khoảng thời gian tương ứng với chỉ mục 0 theo các phương pháp proto3.
Các giá trị startPolylinePointIndex và endPolylinePointIndex không phải lúc nào cũng liên tiếp. Ví dụ:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Trong trường hợp này, điều kiện lưu lượng truy cập giống nhau từ chỉ mục 2 đến chỉ mục 4.
Kết xuất các đường đa giác nhận biết được lưu lượng truy cập bằng SDK Maps
Bạn nên hiển thị các đường đa giác nhận biết được tình trạng giao thông trên bản đồ bằng cách sử dụng nhiều tính năng mà SDK Google Maps cung cấp, bao gồm cả màu sắc, nét vẽ và hoa văn tuỳ chỉnh dọc theo các đoạn đường đa giác. Để biết thêm thông tin chi tiết về cách sử dụng đa tuyến, hãy xem bài viết Tính năng đa tuyến cho Android và Tính năng đa tuyến cho iOS.
Ví dụ về kết xuất Polyline
Người dùng SDK Maps có thể xác định logic ánh xạ tuỳ chỉnh giữa các danh mục tốc độ và giản đồ kết xuất đa tuyến. Ví dụ: bạn có thể quyết định hiển thị tốc độ "BÌNH THƯỜNG" dưới dạng một đường màu xanh dương đậm trên bản đồ, trong khi tốc độ "CHẬM" có thể hiển thị dưới dạng một đường màu cam đậm.
Các đoạn mã sau đây sẽ thêm một đa tuyến màu xanh dương đậm với các đoạn đường trắc địa từ Melbourne đến Perth. Để biết thêm thông tin, hãy xem phần Tuỳ chỉnh giao diện (dành cho Android) và Tuỳ chỉnh đường đa tuyến (dành cho iOS).
Android
Java
Polyline line = map.addPolyline(new PolylineOptions() .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734)) .width(25) .color(Color.BLUE) .geodesic(true));
Kotlin
val line: Polyline = map.addPolyline( PolylineOptions() .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734)) .width(25f) .color(Color.BLUE) .geodesic(true) )
iOS
Objective-C
GMSMutablePath *path = [GMSMutablePath path]; [path addLatitude:-37.81319 longitude:144.96298]; [path addLatitude:-31.95285 longitude:115.85734]; GMSPolyline *polyline = [GMSPolyline polylineWithPath:path]; polyline.strokeWidth = 10.f; polyline.strokeColor = .blue; polyline.geodesic = YES; polyline.map = mapView;
Swift
let path = GMSMutablePath() path.addLatitude(-37.81319, longitude: 144.96298) path.addLatitude(-31.95285, longitude: 115.85734) let polyline = GMSPolyline(path: path) polyline.strokeWidth = 10.0 polyline.geodesic = true polyline.map = mapView
Sử dụng đa tuyến đường được mã hoá bằng tính năng Tìm kiếm dọc theo tuyến đường
Sử dụng tính năng Tìm kiếm bằng văn bản của API Địa điểm để tìm kiếm dọc theo một tuyến đường đã tính toán. Bạn truyền đa tuyến được mã hoá của một tuyến đường được tính toán trước từ API Tuyến đường đến yêu cầu Tìm kiếm bằng văn bản. Sau đó, phản hồi sẽ chứa các địa điểm phù hợp với tiêu chí tìm kiếm và cũng nằm gần tuyến đường đã chỉ định. Để biết thông tin chi tiết, hãy xem phần tìm kiếm dọc theo một tuyến đường.
Ví dụ: để trả về các quán cà phê dọc theo tuyến đường giữa điểm xuất phát và điểm đến:
Node.js
const API_KEY = 'YOUR_API_KEY'; const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes'; const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';function init(){ const routes_request = { "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }; const textSearch_request = { "textQuery": "cafe", "searchAlongRouteParameters": { "polyline": { "encodedPolyline": "" } } }; fetchResources(routes_service,routes_request).then(routes => { textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline; fetchResources(textSearch_service,textSearch_request).then(places => { console.log(places); }); }); } async function fetchResources(resource,reqBody){ const response = await fetch(resource, { method: 'POST', body: JSON.stringify(reqBody), headers: { 'Content-Type': 'application/json', 'X-Goog-Api-Key': API_KEY, 'X-Goog-FieldMask': '*' } }); const responseJSON = await response.json(); return responseJSON; } init();