Roads API trả về giới hạn tốc độ được đăng cho một con đường nhất định phân khúc. Trong trường hợp đoạn đường có giới hạn tốc độ thay đổi, giá trị mặc định giới hạn tốc độ cho đoạn đường được trả về.
Độ chính xác của dữ liệu giới hạn tốc độ do Roads API trả về không thể được đảm bảo. Dữ liệu về giới hạn tốc độ được cung cấp không theo thời gian thực và có thể ước tính, không chính xác, không đầy đủ và/hoặc đã lỗi thời. Xem thông tin chi tiết về phạm vi cung cấp để xem những khu vực có dữ liệu giới hạn tốc độ.
Yêu cầu
Yêu cầu giới hạn tốc độ phải được gửi qua HTTPS và có dạng sau:
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY
Cách sử dụng thông số
Tham số bắt buộc
- Tham số
path
hoặcplaceId
.path
– Một danh sách gồm tối đa 100 cặp vĩ độ/kinh độ đại diện cho một đường dẫn. Các giá trị vĩ độ và kinh độ phải được phân tách bằng dấu phẩy. Cặp vĩ độ/kinh độ phải được phân tách bằng các ký tự sổ thẳng: "|". Khi bạn cung cấp tham sốpath
, trước tiên, API sẽ chụp nhanh đường dẫn đến con đường có nhiều khả năng nhất mà xe đi qua (như đối vớisnapToRoads
), sau đó xác định giới hạn tốc độ cho đoạn đường có liên quan. Nếu bạn không muốn API chụp nhanh đường dẫn, bạn phải chuyển thông sốplaceId
như giải thích dưới đây. Ví dụ sau đây hiển thị tham sốpath
có 3 cặp vĩ độ/kinh độ:path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796
.placeId
— (Các) mã địa điểm đại diện cho một hoặc nhiều đoạn đường. Hãy đảm bảo mỗi mã địa điểm là một đoạn đường chứ không phải một loại khác của địa điểm. Bạn có thể truyền tối đa 100 mã địa điểm với mỗi mã của bạn. API không thực hiện chụp ảnh đường trên các mã địa điểm đã cung cấp. Phản hồi bao gồm giới hạn tốc độ cho mỗi mã địa điểm trong yêu cầu. Bạn có thể gửi yêu cầusnapToRoads
hoặcnearestRoads
để tìm các mã địa điểm có liên quan, sau đó cung cấp chúng làm dữ liệu đầu vào cho Yêu cầuspeedLimits
. Ví dụ sau đây cho thấy Tham sốplaceId
với hai mã địa điểm:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
key
— Khoá API cho ứng dụng của bạn. Thông tin ứng dụng phải tự xác định mỗi khi gửi yêu cầu đến Roads API bằng cách thêm một khoá API vào mỗi yêu cầu. Tìm hiểu cách lấy khoá.
Tham số không bắt buộc
units
— Liệu sẽ trả về giới hạn tốc độ tính bằng km hay dặm trên mỗi giờ. Bạn có thể thiết lập giá trị này làKPH
hoặcMPH
. Giá trị mặc định làKPH
.
Phản hồi
Các phần tử sau đây có thể có trong phản hồi speedLimits
:
speedLimits
— Một mảng siêu dữ liệu về đường. Mỗi phần tử bao gồm các trường sau:placeId
– Giá trị nhận dạng duy nhất của một địa điểm. Đã trả về tất cả mã địa điểm bởi Roads API sẽ tương ứng với đoạn đường.speedLimit
— Giới hạn tốc độ cho đoạn đường đó.units
— Trả vềKPH
hoặcMPH
.
snappedPoints
— một loạt các điểm chụp nhanh. Mảng này tồn tại chỉ khi yêu cầu chứa tham sốpath
. Mỗi điểm bao gồm các trường sau:location
– chứa giá trịlatitude
vàlongitude
.originalIndex
– Một số nguyên cho biết giá trị tương ứng trong yêu cầu ban đầu. Mỗi giá trị trong yêu cầu phải ánh xạ đến một giá trị được chụp nhanh trong câu trả lời. Các giá trị này được lập chỉ mục từ0
, vì vậy, điểm cóoriginalIndex
là4
sẽ là giá trị được chụp nhanh của điểm thứ 5 vĩ độ/kinh độ được truyền đến tham sốpath
.placeId
– Giá trị nhận dạng duy nhất của một địa điểm. Đã trả về tất cả mã địa điểm bởi Roads API sẽ tương ứng với đoạn đường.placeId
có thể được truyền trong yêu cầu giới hạn tốc độ để xác định giới hạn tốc độ dọc theo đoạn đường đó.
warning_message
– Một chuỗi chứa cảnh báo mà người dùng thấy được.
Ví dụ về yêu cầu sử dụng đường dẫn
Yêu cầu này sẽ nhận giới hạn tốc độ cho mỗi đoạn đường gần với cặp vĩ độ/kinh độ được chỉ định trên con đường băng qua sông Vasco da Gama cây cầu ở Lisbon, Bồ Đào Nha.
Yêu cầu
https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY
Đáp
{ speedLimits: [ { placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE", speedLimit: 105, units: "KPH" }, { placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU", speedLimit: 70, units: "KPH" }, { placeId: "ChIJJ4vQRudkJA0RpednU70A-5M", speedLimit: 55, units: "KPH" } ], snappedPoints: [ { location: { latitude: 38.75807927603043, longitude: -9.037417546438084 }, originalIndex: 0, placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE" }, { location: { latitude: 38.689653701836896, longitude: -9.177051486847693 }, originalIndex: 1, placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU" }, { location: { latitude: 41.13993011767777, longitude: -8.609400794783655 }, originalIndex: 2, placeId: "ChIJJ4vQRudkJA0RpednU70A-5M" } ], warningMessage: "Input path is too sparse. You should provide a path where consecutive points are closer to each other. Refer to the 'path' parameter in Google Roads API documentation." }
Hãy lưu ý thông báo cảnh báo về độ ít điểm trong phản hồi trên. Nếu bạn
đang yêu cầu giới hạn tốc độ cho các đoạn đường gần nhất tại các điểm tuỳ ý,
bạn phải gọi speedLimits
kèm theo mã địa điểm được truy xuất từ
Thay vào đó, điểm cuối nearestRoads
.
Ví dụ về yêu cầu sử dụng mã địa điểm
Thay vì sử dụng cặp vĩ độ/kinh độ, bạn có thể chuyển mã địa điểm của
đoạn đường. Bạn nên lấy mã địa điểm cho các đoạn đường bằng cách sử dụng
Yêu cầu snapToRoads
hoặc nearestRoads
. Khi bạn chuyển mã địa điểm, API
trả về giới hạn tốc độ cho đoạn đường được biểu thị bằng từng mã địa điểm. Chiến lược phát hành đĩa đơn
API không áp dụng bất kỳ hoạt động chụp ảnh đường nào cho mã địa điểm được cung cấp.
Ví dụ sau đây yêu cầu giới hạn tốc độ cho một số đoạn đường băng qua cây cầu Vasco da Gama ở Lisbon, Bồ Đào Nha.
Yêu cầu
https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY
Đáp
{ "speedLimits": [ { placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE", speedLimit: 105, units: "KPH" }, { placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU", speedLimit: 70, units: "KPH" }, { placeId: "ChIJJ4vQRudkJA0RpednU70A-5M", speedLimit: 55, units: "KPH" } ] }
Đề xuất sử dụng
Để giảm thiểu số lượng cuộc gọi đến dịch vụ Giới hạn tốc độ, bạn nên lấy mẫu vị trí nội dung của mình theo khoảng thời gian từ 5 đến 15 phút (độ chính xác phụ thuộc vào tốc độ di chuyển của nội dung). Nếu một thành phần là cố định, thì chỉ cần lấy một mẫu vị trí là đủ (không cần nhiều lệnh gọi).
Để giảm thiểu độ trễ tổng thể, bạn nên gọi dịch vụ Giới hạn tốc độ sau khi bạn đã tích luỹ một số dữ liệu, thay vì gọi API mỗi khi địa điểm của nội dung di động được nhận.
Tại sao lại bị thiếu một số/tất cả giới hạn tốc độ?
Nguyên nhân phổ biến nhất khiến speedLimits
bị thiếu là việc yêu cầu giới hạn tốc độ
của một địa điểm không phải là đoạn đường.
Ví dụ trên sử dụng cầu Vasco da Gama để minh hoạ các khái niệm;
cây cầu dẫn lối cho con đường E90 băng qua sông Rio Tejo. Cây cầu
có mã địa điểm là ChIJUzt97ZEwGQ0RM1JzQfqoDtU. Đoạn đường đầu tiên
trong câu trả lời ở trên là một phần của đường E90 và có mã địa điểm là
ChIJX12duJAwGQ0Ra0d4Oi4jOGE. Trong yêu cầu ví dụ, nếu bạn thay thế đường
địa điểm ID với ID địa điểm của cầu nối, thì trong phản hồi sẽ chỉ có
hai giới hạn tốc độ trong mảng speedLimits
vì mã địa điểm của cầu
không đề cập đến đoạn đường riêng lẻ. Hơn nữa, nếu không có
mã địa điểm là dành cho đoạn đường, thì phản hồi sẽ không chứa bất kỳ
giới hạn tốc độ.
Khi đưa ra yêu cầu giới hạn tốc độ bằng mã địa điểm, hãy đảm bảo từng mã địa điểm
đề cập đến một đoạn đường chứ không phải là một loại địa điểm khác. Mã địa điểm cho
đoạn đường riêng lẻ được truy xuất tốt nhất bằng cách sử dụng snapToRoads
hoặc yêu cầu nearestRoads
, một trong hai yêu cầu này có thể trả về nhiều mã địa điểm từ
một cuộc gọi duy nhất.