The Roads API returns the posted speed limit for a given road segment. In the case of road segments with variable speed limits, the default speed limit for the segment is returned.
The accuracy of speed limit data returned by the Roads API cannot be guaranteed. The speed limit data provided is not real-time, and may be estimated, inaccurate, incomplete, and/or outdated. See coverage details to see the regions where speed limit data is available.
Requests
A request for speed limits must be sent via HTTPS, and takes the following form:
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY
Parameter usage
Required parameters
- Either a
path
or aplaceId
parameter.path
— A list of up to 100 latitude/longitude pairs representing a path. Latitude and longitude values must be separated by commas. Latitude/longitude pairs must be separated by the pipe character: "|". When you supply thepath
parameter, the API first snaps the path to the most likely road traveled by a vehicle (as it does for thesnapToRoads
request), then determines the speed limit for the relevant road segment. If you don't want the API to snap the path, you must pass aplaceId
parameter as explained below. The following example shows thepath
parameter with three latitude/longitude pairs:path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796
.placeId
— The place ID(s) representing one or more road segments. Make sure each place ID refers to a road segment and not a different type of place. You can pass up to 100 place IDs with each request. The API does not perform road-snapping on the supplied place IDs. The response includes a speed limit for each place ID in the request. You can send asnapToRoads
ornearestRoads
request to find the relevant place IDs then supply them as input to thespeedLimits
request. The following example shows theplaceId
parameter with two place IDs:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
key
— Your application's API key. Your application must identify itself every time it sends a request to the Roads API by including an API key with each request. Learn how to get a key.
Optional parameters
units
— Whether to return speed limits in kilometers or miles per hour. This can be set to eitherKPH
orMPH
. Defaults toKPH
.
Responses
The following elements may be present in a speedLimits
response:
speedLimits
— An array of road metadata. Each element consists of the following fields:placeId
— A unique identifier for a place. All place IDs returned by the Roads API will correspond to road segments.speedLimit
— The speed limit for that road segment.units
— Returns eitherKPH
orMPH
.
snappedPoints
— an array of snapped points. This array is present only if the request contained apath
parameter. Each point consists of the following fields:location
— contains alatitude
andlongitude
value.originalIndex
— An integer that indicates the corresponding value in the original request. Each value in the request should map to a snapped value in the response. These values are indexed from0
, so a point with anoriginalIndex
of4
will be the snapped value of the 5th latitude/longitude passed to thepath
parameter.placeId
— A unique identifier for a place. All place IDs returned by the Roads API will correspond to road segments. TheplaceId
can be passed in a speed limits request to determine the speed limit along that road segment.
warning_message
— A string containing a user-visible warning.
Example request using a path
This request gets the speed limit for each road segment nearest to the specified latitude/longitude pairs in a path crossing the Vasco da Gama bridge in Lisbon, Portugal.
Request
https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY
Response
{ 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." }
Notice the warning message for point sparsity in the above response. If you
are requesting speed limits for the nearest road segments at arbitrary points,
you must call speedLimits
with place IDs retrieved from the
nearestRoads
endpoint instead.
Example request using place IDs
Instead of using latitude/longitude pairs, you can pass the place IDs of the
road segments. We recommend you obtain place IDs for road segments using
snapToRoads
or nearestRoads
requests. When you pass place IDs, the API
returns the speed limit for the road segment represented by each place ID. The
API does not apply any road-snapping to the place IDs supplied.
The following example requests the speed limits for some of the road segments that cross the Vasco da Gama bridge in Lisbon, Portugal.
Request
https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY
Response
{ "speedLimits": [ { placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE", speedLimit: 105, units: "KPH" }, { placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU", speedLimit: 70, units: "KPH" }, { placeId: "ChIJJ4vQRudkJA0RpednU70A-5M", speedLimit: 55, units: "KPH" } ] }
Usage recommendations
To minimize the volume of calls to the Speed Limit service, we recommend sampling the locations of your assets at 5 to 15 minute intervals (the exact value depends on the speed at which an asset is traveling). If an asset is stationary, a single location sample is sufficient (there is no need to make multiple calls).
To minimize overall latency, we recommend calling the Speed Limit service once you have accumulated some data, rather than calling the API every time the location of a mobile asset is received.
Why are some/all speed limits missing?
The most common cause of missing speedLimits
is requesting the speed limit
of a place that is not a road segment.
The above example uses the Vasco da Gama bridge to illustrate concepts;
the bridge supports the road E90 crossing over the Rio Tejo. The bridge
itself has a place ID of ChIJUzt97ZEwGQ0RM1JzQfqoDtU. The first road segment
in the above response is part of the E90 road and has a place ID of
ChIJX12duJAwGQ0Ra0d4Oi4jOGE. In the example request, if you replace the road
place ID with the bridge's place ID, then in the response there will only be
two speed limits in the speedLimits
array because the bridge's place ID
does not refer to an individual road segment. Furthermore, if none of the
place IDs are for road segments, then the response will not contain any
speed limits.
When making speed limit requests using place IDs, make sure each place ID
refers to a road segment and not a different type of place. Place IDs for
individual road segments are best retrieved using snapToRoads
or nearestRoads
requests, either of which can return multiple place IDs from
a single call.