Roads API trả về giới hạn tốc độ đã đăng cho một đoạn đường nhất định. Trong trường hợp các đoạn đường có giới hạn tốc độ thay đổi, giới hạn tốc độ mặc định cho đoạn đường sẽ được trả về.
Không thể đảm bảo độ chính xác của dữ liệu giới hạn tốc độ do Roads API trả về. Dữ liệu giới hạn tốc độ được cung cấp không phải là dữ liệu theo thời gian thực và có thể là dữ liệu ước tính, không chính xác, chưa đầy đủ và/hoặc lỗi thời. Hãy xem thông tin chi tiết về phạm vi cung cấp để biết những khu vực có dữ liệu về giới hạn tốc độ.
Yêu cầu
Yêu cầu về giới hạn tốc độ phải được gửi qua HTTPS và có dạng như sau:
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEYCách sử dụng thông số
Tham số bắt buộc
- Tham số
pathhoặcplaceId.path– Danh sách tối đa 100 cặp vĩ độ/kinh độ đại diện cho một đường dẫn. Bạn phải phân tách các giá trị vĩ độ và kinh độ bằng dấu phẩy. Các cặp vĩ độ/kinh độ phải được phân tách bằng ký tự ố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 mà xe có khả năng đi qua nhất (như đối với yêu cầusnapToRoads), sau đó xác định giới hạn tốc độ cho đoạn đường có liên quan. Nếu không muốn API chụp nhanh đường dẫn, bạn phải truyền tham sốplaceIdnhư giải thích bên dưới. Ví dụ sau đây cho thấy tham sốpathvới ba 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. Đảm bảo mỗi mã địa điểm đều tham chiếu đến một đoạn đường chứ không phải một loại địa điểm khác. Bạn có thể truyền tối đa 100 mã địa điểm với mỗi yêu cầu. API không chụp nhanh đường trên mã địa điểm được cung cấp. Nội dung phản hồi bao gồm giới hạn tốc độ cho từng mã địa điểm trong yêu cầu. Bạn có thể gửi yêu cầusnapToRoadshoặcnearestRoadsđể tìm mã địa điểm có liên quan, sau đó cung cấp các mã đó làm dữ liệu đầu vào cho yêu cầuspeedLimits. Ví dụ sau đây cho thấy tham sốplaceIdcó hai mã địa điểm:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
key– Khoá API của ứng dụng. Ứng dụng của bạn phải tự xác định mỗi khi gửi yêu cầu đến Roads API bằng cách đưa khoá API vào mỗi yêu cầu. Tìm hiểu cách lấy khoá.
Thông số tuỳ chọn
units– Liệu có trả về giới hạn tốc độ tính bằng km hay dặm/giờ hay không. Bạn có thể đặt giá trị này thànhKPHhoặcMPH. Giá trị mặc định làKPH.
Phản hồi
Các phần tử sau đây có thể xuất hiện 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. Tất cả mã địa điểm do Roads API trả về sẽ tương ứng với các đoạn đường.speedLimit– Giới hạn tốc độ cho đoạn đường đó.units– Trả vềKPHhoặcMPH.
snappedPoints– một mảng các điểm được chụp nhanh. Mảng này chỉ xuất hiện nếu 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ịlatitudevà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 liên kết với một giá trị đã chụp trong phản hồi. Các giá trị này được lập chỉ mục từ0, vì vậy, một điểm cóoriginalIndexlà4sẽ là giá trị được chụp nhanh của vĩ độ/kinh độ thứ 5 được truyền đến tham sốpath.placeId– Giá trị nhận dạng duy nhất của một địa điểm. Tất cả mã địa điểm do Roads API trả về sẽ tương ứng với các đoạn đường. Bạn có thể truyềnplaceIdtrong 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 có thể nhìn thấy.
Ví dụ về yêu cầu sử dụng đường dẫn
Yêu cầu này sẽ lấy giới hạn tốc độ cho từng đoạn đường gần nhất với cặp vĩ độ/kinh độ đã chỉ định trong một đường đi qua cầu Vasco da Gama ở 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ề độ thưa thớt của đ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 bằng mã địa điểm được truy xuất từ đ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ể truyền mã địa điểm của các phân đoạn đường. Bạn nên lấy mã nhận dạng đị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 truyền mã địa điểm, API sẽ trả về giới hạn tốc độ cho đoạn đường được biểu thị bằng từng mã địa điểm. API này không áp dụng bất kỳ tính năng chụp nhanh đường nào cho mã địa điểm được cung cấp.
Ví dụ sau yêu cầu giới hạn tốc độ cho một số đoạn đường đi qua 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 về cách sử dụng
Để giảm thiểu số lượng lệnh gọi đến dịch vụ Giới hạn tốc độ, bạn nên lấy mẫu vị trí của tài sản theo khoảng thời gian từ 5 đến 15 phút (giá trị chính xác phụ thuộc vào tốc độ di chuyển của tài sản). Nếu một thành phần cố định, thì chỉ cần một mẫu vị trí là đủ (không cần thực hiệ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 tích luỹ một số dữ liệu, thay vì gọi API mỗi khi nhận được vị trí của một thành phần trên thiết bị di động.
Tại sao một số/tất cả biển báo giới hạn tốc độ bị thiếu?
Nguyên nhân phổ biến nhất khiến speedLimits bị thiếu là 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ầu này hỗ trợ đường E90 bắc qua sông Rio Tejo. Bản thân cây cầu có mã địa điểm là ChIJUzt97ZEwGQ0RM1JzQfqoDtU. Đoạn đường đầu tiên trong phản hồ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 mẫu, nếu bạn thay thế mã nhận dạng địa điểm đường bằng mã nhận dạng địa điểm của cầu, thì trong phản hồi sẽ chỉ có hai giới hạn tốc độ trong mảng speedLimits vì mã nhận dạng địa điểm của cầu không tham chiếu đến một đoạn đường riêng lẻ. Hơn nữa, nếu không có mã nhận dạng địa điểm nào dành cho các đoạn đường, thì phản hồi sẽ không chứa giới hạn tốc độ nào.
Khi tạo yêu cầu giới hạn tốc độ bằng mã địa điểm, hãy đảm bảo mỗi mã địa điểm tham chiếu đến một đoạn đường chứ không phải một loại địa điểm khác. Tốt nhất là bạn nên truy xuất mã địa điểm cho từng đoạn đường bằng các yêu cầu snapToRoads hoặc nearestRoads. Mỗi yêu cầu có thể trả về nhiều mã địa điểm từ một lệnh gọi.