The Roads API takes up to 100 independent coordinates, and returns the closest road segment for each point. The points passed do not need to be part of a continuous path.
If you are working with sequential GPS points, use Snap to Roads.
Requests
A request to nearest roads must be sent via HTTPS, and takes the following form:
https://roads.googleapis.com/v1/nearestRoads?parameters&key=YOUR_API_KEY
Required parameters
points
The points to be snapped. The points parameter accepts a list of latitude/longitude pairs. Separate latitude and longitude values with commas. Separate coordinates with the pipe character: "|". For example:
points=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796.
Examples
The following request returns a set of road segments based on the specified list of coordinates.
URL
https://roads.googleapis.com/v1/nearestRoads ?points=60.170880%2C24.942795%7C60.170879%2C24.942796%7C60.170877%2C24.942796 &key=YOUR_API_KEY
cURL
curl -L -X GET 'https://roads.googleapis.com/v1/nearestRoads?points=60.170880%2C24.942795%7C60.170879%2C24.942796%7C60.170877%2C24.942796&key=YOUR_API_KEY'
Responses
For each valid request, the Roads API will return a response in the format indicated within the request URL.
{
"snappedPoints":
[
{
"location":
{ "latitude": 60.170878428876755, "longitude": 24.94269540970182 },
"originalIndex": 0,
"placeId": "ChIJfVFHrM0LkkYRBzUQos_jR5w",
},
{
"location":
{ "latitude": 60.17087741412199, "longitude": 24.942695474405202 },
"originalIndex": 1,
"placeId": "ChIJfVFHrM0LkkYRBzUQos_jR5w",
},
{
"location":
{ "latitude": 60.170875416131736, "longitude": 24.942695601802203 },
"originalIndex": 2,
"placeId": "ChIJfVFHrM0LkkYRBzUQos_jR5w",
},
],
}
The response uses the following schema.
NearestRoadsResponse
| Field | Required | Type | Description |
|---|---|---|---|
| optional | Array<SnappedPoint> | An array of snapped points. Sometimes containing several snapped points for the same point with differing placeId or location. See SnappedPoint for more information. |
SnappedPoint
| Field | Required | Type | Description |
|---|---|---|---|
| required | LatitudeLongitudeLiteral | See LatitudeLongitudeLiteral for more information. |
| required | string | A unique identifier for a place. All place IDs returned by the Roads API correspond to road segments. |
| optional | number |
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. However, if you've set interpolate=true or if you're
using nearest roads, then it's possible that the response will
contain more coordinates than the request. Interpolated values will
not have an |
LatitudeLongitudeLiteral
An object describing a specific location with Latitude and Longitude in decimal degrees.
| Field | Required | Type | Description |
|---|---|---|---|
| required | number | Latitude in decimal degrees |
| required | number | Longitude in decimal degrees |