Speed limits

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 a placeId 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 the path parameter, the API first snaps the path to the most likely road traveled by a vehicle (as it does for the snapToRoads 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 a placeId parameter as explained below. The following example shows the path 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 a snapToRoads or nearestRoads request to find the relevant place IDs then supply them as input to the speedLimits request. The following example shows the placeId 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 either KPH or MPH. Defaults to KPH.

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 either KPH or MPH.
  • snappedPoints — an array of snapped points. This array is present only if the request contained a path parameter. Each point consists of the following fields:
    • location — contains a latitude and longitude 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 from 0, so a point with an originalIndex of 4 will be the snapped value of the 5th latitude/longitude passed to the path parameter.
    • placeId — A unique identifier for a place. All place IDs returned by the Roads API will correspond to road segments. The placeId 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.