What is snap to roads?
The snap to roads operation allows you to align GPS track points with the nearest routable road segments in a transportation network. The operation is designed to work with GPS data which can be imprecise. By snapping the GPS points to the nearest road segments, the operation improves accuracy of GPS data and provides a more reliable representation of the actual route taken.
In addition to returning snapped points and line (road) segments, the operation can also return attributes for the features such as posted speed limits and segment lengths. These attributes can be used to perform analyses such as route adherence, which compares actual travel paths to planned or expected routes.
You use snap to roads to:
- Improve the accuracy of GPS track points by removing inaccuracies.
- Reconstruct accurate routes and route length for tax reimbursement.
- Monitor driver behavior by comparing actual driving speed against posted speed limits and comparing the snapped route with the planned route.
How to use snap to roads
Snap to roads works by using a combination of GPS data (as input) and existing road network data to determine the most likely road that a vehicle or person traveled on. This is done by analyzing the GPS data and comparing it to the road network data to find the closest routable match.
The typical workflow for performing a snap to roads operation is as follows:
- Prepare the input data: The data is typically a set of GPS track points that represents a vehicle's path.
- Call the snap to roads operation: Snap the GPS track points to the underlying road network data.
- Process the output data: The output data will be a series of snapped GPS track points along with lines representing the routes for analyzing GPS data.
URL requests
You can perform the snap to roads operation by making an HTTPS request to the Snap operation. The operation is available as a synchronous operation that will return the results immediately after processing the input data. The operation can be called using a REST API or through a web application.
https://route-api.arcgis.com/arcgis/rest/services/World/SnapToRoadsSync/GPServer/SnapToRoads/executeRequired parameters
| Name | Description | Examples |
|---|---|---|
points | The input data containing the GPS track points. | points=Featureset object |
f | The format of the data returned. | f=json f=pjson |
token | An API key or OAuth 2.0 access token. | token= |
Optional parameters
| Name | Description | Examples |
|---|---|---|
travel | The mode of travel. | travelTravel mode object |
return | Return the road segments that the GPS points were snapped to. | return |
road | Return road attributes such as speed limits and segment lengths. | road |
road | Return road attributes on the snapped road segments. | road |
context | A JSON object that contains additional parameters for the operation, for example, the spatial reference of the output features. | context={"key" |
Example request
Below is a request that shows how to use the snap to roads operation. The input data must be formatted as a Featureset which should include the geometry, attributes, and spatial reference of the features.
REST API
curl --location 'https://route-api.arcgis.com/arcgis/rest/services/World/SnapToRoadsSync/GPServer/SnapToRoads/execute' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'f=json' \
--data-urlencode 'token={YOUR_ACCESS_TOKEN}' \
--data-urlencode 'points={
"features": [
{
"attributes": {
"OBJECTID": 1,
"location_timestamp": 1704522159000
},
"geometry": {
"x": -122.43410099956145,
"y": 37.800155000053394
}
Code examples
Snap points and get route attributes
This example uses the snap to roads operation to snap GPS points to roads and return a route with road attributes. The speed limit and length attributes are provided for each segment. Hover over each segment to view the attributes.
const queryParams = new URLSearchParams({
f: "json",
token: appConfig.ACCESS_TOKEN,
points: JSON.stringify({ features: agsPoints }),
return_location_fields: true,
return_lines: true,
road_properties_on_lines: JSON.stringify([
"posted_speed_limit_mph",
"length_miles",
]),
})
const service = appConfig.SNAP_TO_ROADS_URL
const response = await fetch(service, {
method: "POST",
headers: headerParams,
body: queryParams,
})
const agsJSONResponse = await response.json()
Planned versus snapped route adherence analysis
This example uses the snap to roads operation to visualize and analyze a planned versus snapped route. The operation returns snapped points, a route, and road attributes such as posted speed limits and segment lengths. It displays the planned route provided by an operator, the actual route driven by a truck, and the snapped route generated by the operation. It also shows how route analysis can be performed for route statistics, identify speeding locations, and highlights route deviations.
// Create parameters for the Snap to Roads service
const params = {
points: inputFeatures,
token: accessToken,
travel_mode: travelMode,
return_lines: true,
return_location_fields: true,
road_properties_on_snapped_points: [
"posted_speed_limit_mph",
"length_miles",
],
road_properties_on_lines: [
"posted_speed_limit_mph",
"length_miles",
],
}
const results = await EsriGeoprocessor.execute(
serviceURLs.snapToRoads,
params
)
Upload GPX file and snap tracks points
This example uploads a GPX file, parses the GPS track points, and uses the snap to roads operation to return snapped points and a route. The snapped points, route, and GPS track points are displayed on the map. The example also allows you to download a sample GPX file to test the operation.
// Query the raw points layer for features
const features = await rawPointsLayer.queryFeatures()
// Create a feature set
const params = {
points: features,
token: apiKey,
travel_mode: travelMode,
return_lines: true,
return_location_fields: true,
road_properties_on_snapped_points: [
"posted_speed_limit_mph",
"length_miles",
],
road_properties_on_lines: ["posted_speed_limit_mph", "length_miles"],
}
try {
// Execute the geoprocessing service
const result = await EsriGeoprocessor.execute(
serviceURLs.snapToRoads,
params
)
Snap points based on walking travel mode
This example uses the snap to roads operation to snap GPS points based on the Walking Distance travel mode. The snap to roads algorithms use the travel mode settings when determining the most likely roads that were traveled. The snapped points and route returned from the operation are displayed on the map, and the attributes of the snapped points are shown in a popup.
const inputParams = {
points: pts,
travel_mode: currentTravelMode,
return_location_fields: true,
road_properties_on_lines: ["length_miles"],
token: accessToken,
return_lines: true,
}
const results = await EsriGeoprocessor.execute(serviceURL, inputParams)