Roads API 会返回指定路段张贴的限速信息。如果路段具有可变速度限制,则返回相应路段的默认速度限制。
无法保证 Roads API 返回的速度限制数据的准确性。提供的限速数据并非实时数据,可能是预估、不准确、不完整和/或过时的数据。如需了解提供速度限制数据的区域,请参阅覆盖范围详情。
请求
速度限制请求必须通过 HTTPS 发送,并采用以下格式:
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY
参数用法
必需参数
path
或placeId
参数。path
- 表示路径的纬度/经度对列表(最多 100 个)。纬度值和经度值必须以英文逗号分隔。纬度/经度对必须以竖线字符“|”分隔。当您提供path
参数时,API 会先将路径捕捉到车辆最可能行驶的道路(与处理snapToRoads
请求时一样),然后确定相关路段的速度限制。如果您不希望 API 贴靠路径,则必须传递placeId
参数(如下所述)。以下示例展示了包含三个纬度/经度对的path
参数:path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796
。placeId
- 表示一个或多个路段的地点 ID。请确保每个地点 ID 都代表一个路段,而不是不同类型的地点。在每个请求中,您最多可以传递 100 个地点 ID。该 API 不会对提供的地点 ID 执行道路贴靠。响应包含请求中每个地点 ID 的速度限制。您可以发送snapToRoads
或nearestRoads
请求来查找相关地点 ID,然后将其作为输入提供给speedLimits
请求。下例显示的是具有两个地点 ID 的placeId
参数:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
key
- 您的应用的 API 密钥。您的应用必须在每次向 Roads API 发送请求时标识自身的身份,方法是在每个请求中添加 API 密钥。了解如何获取密钥。
可选参数
units
- 以公里/小时还是英里/小时为单位返回速度限制。此字段可以设置为KPH
或MPH
。默认设置为KPH
。
响应
speedLimits
响应中可能存在以下元素:
speedLimits
- 一组道路元数据。每个元素都由以下字段组成:placeId
- 地点的唯一标识符。Roads API 返回的所有地点 ID 都将对应于路段。speedLimit
- 该路段的速度限制。units
- 返回KPH
或MPH
。
snappedPoints
- 贴靠点数组。仅当请求包含path
参数时,此数组才会显示。每个点都由以下字段组成:location
- 包含latitude
和longitude
值。originalIndex
- 一个整数,表示原始请求中的相应值。请求中的每个值都应映射到响应中的一个贴靠值。这些值从0
开始编入索引,因此originalIndex
为4
的点将成为传递给path
参数的第 5 个纬度/经度的贴靠值。placeId
- 地点的唯一标识符。Roads API 返回的所有地点 ID 都将与路段相对应。您可以在速度限制请求中传递placeId
,以确定相应路段沿线的速度限制。
warning_message
- 包含用户可见警告的字符串。
使用路径的示例请求
此请求获取一条穿越葡萄牙里斯本瓦斯科达伽马大桥的路径中最接近指定纬度/经度对的每个路段的速度限制。
请求
https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY
答案
{ 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." }
请注意上述响应中针对点稀疏性的警告消息。如果您要为任意点最近路段请求限速,则必须改为使用从 nearestRoads
端点检索的地点 ID 调用 speedLimits
。
使用地点 ID 的请求示例
您可以传递路段的地点 ID,而不是使用纬度/经度对。我们建议您使用 snapToRoads
或 nearestRoads
请求获取路段的地点 ID。当您传递地点 ID 时,API 会返回每个地点 ID 所表示路段的速度限制。此 API 不会对所提供的地点 ID 应用任何道路贴靠。
以下示例请求了在葡萄牙里斯本穿越瓦斯科达伽马大桥的部分路段的速度限制。
请求
https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY
答案
{ "speedLimits": [ { placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE", speedLimit: 105, units: "KPH" }, { placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU", speedLimit: 70, units: "KPH" }, { placeId: "ChIJJ4vQRudkJA0RpednU70A-5M", speedLimit: 55, units: "KPH" } ] }
使用建议
为了尽可能减少对速度限制服务的调用次数,我们建议以 5 到 15 分钟的间隔对资产位置进行采样(确切值取决于资产的行驶速度)。如果资产不固定,一个位置样本就足够了(无需进行多次调用)。
为了尽可能缩短总体延迟时间,我们建议您在累积一些数据后再调用速度限制服务,而不是每次收到移动资产位置时都调用 API。
为什么缺少部分/所有速度限制?
缺少 speedLimits
的最常见原因是请求对非路段地点的速度限制。
上面的示例使用瓦斯科达伽马大桥来解释概念;桥梁支撑着横跨里约特霍的 E90 公路。该桥本身的地点 ID 为 ChIJUzt97ZEwGQ0RM1JzQfqoDtU。上述响应中的第一个路段是 E90 道路的一部分,地点 ID 为 ChIJX12duJAwGQ0Ra0d4Oi4jOGE。在示例请求中,如果您将道路地点 ID 替换为桥梁的地点 ID,则在响应中,speedLimits
数组将只有两个速度限制,因为桥梁的地点 ID 不指单个路段。此外,如果没有任何地点 ID 适用于路段,则响应将不包含任何速度限制。
使用地点 ID 发出限速请求时,请确保每个地点 ID 都指的是路段,而不是不同类型的地点。最好使用 snapToRoads
或 nearestRoads
请求检索各个路段的地点 ID,其中任一请求都可以通过单次调用返回多个地点 ID。