> [!NOTE]
> **Notice:** The Speed Limit service is available to all customers with an [Asset
> Tracking](https://cloud.google.com/maps-platform/asset-tracking) license. For [Google Maps Platform Premium Plan](https://developers.google.com/maps/premium) customers who transitioned to pay-as-you-go pricing, the Speed Limit feature remains active on projects with Asset Tracking capabilities (projects with a project ID in the format maps-asset-xxx).

The Roads API returns the speed limit for given road segments. In
the case of road segments with variable speed limits, the maximum speed limit
for automobiles on that 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, or outdated. See [coverage details](https://developers.google.com/maps/coverage.md.txt)
to see the regions where speed limit data is available.

## Requests

Send requests for speed limits using HTTPS, in the following form:

```
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY
```

<br />

### 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`](https://developers.google.com/maps/documentation/roads/snap.md.txt) 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 response includes a speed limit for each place ID in the request.

    The API does not perform road-snapping on the supplied place IDs.
    You can send a [`snapToRoads`](https://developers.google.com/maps/documentation/roads/snap.md.txt) or [`nearestRoads`](https://developers.google.com/maps/documentation/roads/nearest.md.txt) 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=ChIJs5ydyTiuEmsR0fRSlU0C7k0&placeId=ChIJW__r4ERXzpQRgkeRL6P0m3Y`

> [!CAUTION]
> **Caution:** Each speed limit entry in the `speedLimits` array of the response body triggers [SKU: Roads - Speed Limits](https://developers.google.com/maps/billing-and-pricing/sku-details/routes.md.txt#speed-limits-pro-sku). The more `path` and `placeID` inputs that are included in the request, the more speed limit elements are returned in the response. To optimize costs, pass in the minimum required number of input parameters.

- `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](https://developers.google.com/maps/documentation/roads/get-api-key.md.txt).

**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`](https://developers.google.com/maps/documentation/roads/nearest.md.txt) 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 won't 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.

## What if a road segment posts separate speed limits for cars and trucks?

The Roads API returns the maximum posted speed limit for
automobiles only.