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 path to be snapped. The path parameter accepts a list of latitude/longitude pairs. Latitude and longitude values should be separated by commas. Coordinates should be separated by the pipe character: "|". For example:
path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796
.Note: The snapping algorithm works best for points that are not too far apart. If you observe odd snapping behavior, try creating paths that have points closer together. To ensure the best snap-to-road quality, you should aim to provide paths on which consecutive pairs of points are within 300m of each other. This will also help in handling any isolated, long jumps between consecutive points caused by GPS signal loss, or noise.
Generated from the OpenAPI specification. Edit Report bug
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'
JavaScript
var axios = require('axios'); var config = { method: 'get', url: 'https://roads.googleapis.com/v1/nearestRoads?points=60.170880%2C24.942795%7C60.170879%2C24.942796%7C60.170877%2C24.942796&key=YOUR_API_KEY', headers: { } }; axios(config) .then(function (response) { console.log(JSON.stringify(response.data)); }) .catch(function (error) { console.log(error); });
Python
import requests url = "https://roads.googleapis.com/v1/nearestRoads?points=60.170880%2C24.942795%7C60.170879%2C24.942796%7C60.170877%2C24.942796&key=YOUR_API_KEY" payload={} headers = {} response = requests.request("GET", url, headers=headers, data=payload) print(response.text)
Java
OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://roads.googleapis.com/v1/nearestRoads?points=60.170880%2C24.942795%7C60.170879%2C24.942796%7C60.170877%2C24.942796&key=YOUR_API_KEY") .method("GET", null) .build(); Response response = client.newCall(request).execute();
Ruby
require "uri" require "net/http" url = URI("https://roads.googleapis.com/v1/nearestRoads?points=60.170880%2C24.942795%7C60.170879%2C24.942796%7C60.170877%2C24.942796&key=YOUR_API_KEY") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) response = https.request(request) puts response.read_body
Go
package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://roads.googleapis.com/v1/nearestRoads?points=60.170880,24.942795%7C60.170879,24.942796%7C60.170877,24.942796&key=YOUR_API_KEY" method := "GET" client := &http.Client { } req, err := http.NewRequest(method, url, nil) if err != nil { fmt.Println(err) return } res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) }
Postman
The OpenAPI specification is also available as a Postman collection.
Run in PostmanResponses
For each valid request, the Roads API will return a response in the format indicated within the request URL.
{ "snappedPoints": [ { "location": { "latitude": 60.1708784275856, "longitude": 24.942695420280785 }, "originalIndex": 0, "placeId": "ChIJNX9BrM0LkkYRIM-cQg265e8", }, { "location": { "latitude": 60.1708774128181, "longitude": 24.94269548504503 }, "originalIndex": 1, "placeId": "ChIJNX9BrM0LkkYRIM-cQg265e8", }, { "location": { "latitude": 60.17087541483156, "longitude": 24.94269561256003 }, "originalIndex": 2, "placeId": "ChIJNX9BrM0LkkYRIM-cQg265e8", }, ], }
The response uses the following schema.
NearestRoadsResponse
Field | Required | Type | Description |
---|---|---|---|
| optional | Array<SnappedPoint> | An array of snapped points. See SnappedPoint for more information. |
Generated from the OpenAPI specification. Edit Report bug
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, then it's
possible that the response will contain more coordinates than the
request. Interpolated values will not have an
|
Generated from the OpenAPI specification. Edit Report bug
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 |
Generated from the OpenAPI specification. Edit Report bug