Description
The Snap to Roads service can be used to snap a series of GPS track points to the underlying roads. You can return just the snapped points, or lines representing the roads that were traversed. In addition to the geometry, you can have the service return attributes of the roads like the posted speed limit and length in case you need this to perform route adherence.
For example, the following image shows a series of GPS points that were collected while driving a vehicle. The result shows the points snapped to the underlying roads and the roads that were traversed.
![Snap to roads GPS Track](/rest/services-reference/enterprise/static/8712ba782e92ccac291521e714198e5d/4cdf7/STR_GPSTrack.png)
How to use the service
To use the snap to roads service, you need to pass in a set of point features to which you want to snap to roads. In addition to the point geometry, you can include additional GPS-related data to better guide the snapping. You can also specify if you want to return attributes from the underlying roads and if you want to add them on the output points or lines returned.
Below is an example of a request to the Snap to Roads service and a few sample responses:
POST https://{{machineName}}/{{serverWebAdaptorName}}/rest/services/Routing/NetworkAnalysisSync/GPServer/SnapToRoads/execute HTTP/1.1
Content-Type: application/x-www-form-urlencoded
token=<ACCESS_TOKEN>
&f=json
&points={
"features": [
{
"attributes": {
"OBJECTID": 1,
"location_timestamp": 1704522159000
},
"geometry": {
"x": -122.43410099956145,
"y": 37.800155000053394
}
},
{
"attributes": {
"OBJECTID": 2,
Required parameters
points
type:featureRequired
Specify the points that you want to snap to the road the vehicle is most likely traveling along. The points can be the GPS points from a navigation device, the tracks captured using ArcGIS Field Maps, or some other set of points that were collected while driving the vehicle.
The distance between the points will affect the performance and final quality of the output. If the points are close together, the algorithm will have a better chance of deducing the probable roads at the expense of processing time. Fewer points will process faster, but may result in the route that was deduced potentially taking different roads.
Show attributes for points
Attributes for points
-
ObjectIDIntegernullable
The ID of the feature. This field is used to link the
output
with the input points._snapped _points This field will be used to sequence the points if the location_timestamp field is not present.
-
location_timestampdatetimenullable
The date and time at which the point was collected. This is the same as the Time field in a GPX file.
This field will be used to sequence the points if it is available.
-
horizonal_accuracydouble (non-negative)nullable
The horizontal accuracy of the point measured in meters. This is the same as the HDOP field in a GPX file.
-
speeddouble (non-negative)nullable
The speed of the point in meters per second.
-
coursedouble (non-negative)nullable
The compass direction of the point in units of 0 to 360 degrees. 0 is due North, 90 is due East and so on.
Example:
{
"features": [
{
"attributes": {
"OBJECTID": 1,
"location_timestamp": 1704522159000
},
"geometry": {
"x": -122.43410099956145,
"y": 37.800155000053394
}
},
{
"attributes": {
"OBJECTID": 2,
"location_timestamp": 1704522171000
},
"geometry": {
"x": -122.43459799999755,
"y": 37.800737999958812
token
type:stringRequired
Specify a token that provides the identity of a user that has the permissions to access the service. The security and authentication page provides more information about how an access token can be obtained.
f
type:enumRequired
Allowed values: json
, pjson
Specify the response format.
The pjson
value is used for printing the JSON response in a prettified format.
Optional parameters
travel_mode
type:travel_mode_object
Choose the mode of transportation for the analysis. This is the mode of transportation that matches the track data you are analyzing. The algorithms will use the travel_mode to determine the most likely roads that were traveled.
To learn more about travel modes, see Configure travel modes.
return_lines
type:booldefault:false
Specify whether or not the service will return output
representing the roads traversed.
true
—The output_lines will be returned.false
—The output_lines will not be returned.
road_properties_on_snapped_points
type:array of enum
Allowed values:
length
: The length of the road segment the snapped points locate on in kilometers._kilometers length
: The length of the road segment the snapped points locate on in miles._miles posted
: The posted speed limit of the road segment the snapped points locate on in kilometers per hour._speed _limit _kph posted
: The posted speed limit of the road segment the snapped points locate on in miles per hour._speed _limit _mph posted
: The posted speed limit of the road segment the snapped points locate on in meters per second._speed _limit _mps posted
: The posted truck speed limit of the road segment the snapped points locate on in kilometers per hour._truck _speed _limit _kph posted
: The posted truck speed limit of the road segment the snapped points locate on in miles per hour._truck _speed _limit _mph posted
: The posted truck speed limit of the road segment the snapped points locate on in meters per second._truck _speed _limit _mps
Specify the road properties that the service should return on the output
output.
For example: road
road_properties_on_lines
type:array of enum
Allowed values:
length
: The length of the road segment in kilometers._kilometers length
: The length of the road segment the in miles._miles posted
: The posted speed limit of the road segment in kilometers per hour._speed _limit _kph posted
: The posted speed limit of the road segment in miles per hour._speed _limit _mph posted
: The posted speed limit of the road segment in meters per second._speed _limit _mps posted
: The posted truck speed limit of the road segment in kilometers per hour._truck _speed _limit _kph posted
: The posted truck speed limit of the road segment in miles per hour._truck _speed _limit _mph posted
: The posted truck speed limit of the road segment in meters per second._truck _speed _limit _mps
Specify the road properties that the service should return on the output
output.
For example: road
return_location_fields
type:booldefault:false
Specify whether the service will return fields on the output
and output
defining the snapped point's location with respect to the road.
true
—The output points and lines will contain these additional location fields and they will be populated.false
—The location fields will not be included in the outputs.
context
type:context_object
This parameter contains additional settings that affect task operation, for example, the spatial reference of the output features.
overrides
Response objects
output_snapped_points
type:feature
This output is always returned. It includes all of the fields from the input specified in the points
parameter plus any fields for the properties specified in the road
parameter. The output also contains attributes that are generated by the service.
Show attributes for output snapped points
-
ObjectIDint
The ID of the feature. This field has the same values as the input
points
if the ObjectID field was passed in. Otherwise, they are sequential numbers starting with 1 and going up through the number of features returned. -
Confidenceint
This field defines the confidence level of the computed solution - how likely it is that the computed snapped location is accurate. Its value is between 0 and 1 where 0 means it didn't snap to a road at all and 1 is very confident that the snapping is correct.
-
LineIDint
The ObjectID of the line feature in the
output
. This field is only present if_lines return
is specified as_lines true
in the input. This field is used to link the output snapped points with the output lines.
-
SourceIDlong (non-negative)
The numeric identifier of the network dataset source feature class on which the input point is located.
-
SourceOIDlong (non-negative)
The object ID of the feature in the source on which the input point is located.
-
PosAlongdouble (non-negative)
The position along the digitized direction of the source line feature. This value is stored as a ratio.
-
SideOfEdgeint enum
The side of the edge in relation to the digitized direction of the line feature. The possible values are as following:
1
: Right Side2
: Left Side
output_lines
type:feature
This output is returned if return
is specified as true
in the input. It includes fields for the properties specified in the road
parameter. The output also contains attributes that are generated by the service.
Show attributes for output lines
-
ObjectIDint
The ID of the feature.
-
FromPositiondouble
Indicates where the output line begins in reference to the digitized direction of the road. The value is between 0 and 1 where 0 is the beginning of the road and 1 is the end of the road.
-
ToPositiondouble
Indicates where the output line ends in reference to the digitized direction of the road. The value is between 0 and 1 where 0 is the beginning of the road and 1 is the end of the road.
usage_cost
type:usage_cost_object
This parameter returns the credits used by the analysis.
Usage limits
The table below lists the default limits that apply to this service.
Limit value | Limit description |
---|---|
100,000 | The maximum number of point or line features that can be returned. |
10 minutes | The maximum time a client can use the Snap to Roads service. |
The limits can be configured by following the steps below:
-
Open Server Manager for the ArcGIS Server site that contains the snap to roads service and sign in. If you need help with this step, see Log in to Manager.
-
Click Services > Manage Services.
-
In the Manage Services module, locate NetworkAnalysisSync geoprocessing service and click Edit Service.
If you don't see the service under the Routing folder, it may be located within another folder under the Site (root) >.
-
Click the Parameters option and change the limit for the number of records returned by the service by editing the value in Maximum Number of Records Returned by Server text box.
-
Click the Pooling option and change the maximum time the service can be used by editing the value in the The maximum time a client can use a service text box.
-
Click Save and Restart to apply your edits and restart the service.