Direct request

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

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
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,
Expand

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_snapped_points with the input 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
  "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
Expand

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_lines 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_kilometers: The length of the road segment the snapped points locate on in kilometers.
  • length_miles: The length of the road segment the snapped points locate on in miles.
  • posted_speed_limit_kph: The posted speed limit of the road segment the snapped points locate on in kilometers per hour.
  • posted_speed_limit_mph: The posted speed limit of the road segment the snapped points locate on in miles per hour.
  • posted_speed_limit_mps: The posted speed limit of the road segment the snapped points locate on in meters per second.
  • posted_truck_speed_limit_kph: The posted truck speed limit of the road segment the snapped points locate on in kilometers per hour.
  • posted_truck_speed_limit_mph: The posted truck speed limit of the road segment the snapped points locate on in miles per hour.
  • posted_truck_speed_limit_mps: The posted truck speed limit of the road segment the snapped points locate on in meters per second.

Specify the road properties that the service should return on the output_snapped_points output.

For example: road_properties_on_snapped_points=["posted_speed_limit_kph", "posted_truck_speed_limit_kph"]

road_properties_on_lines

type:array of enum

Allowed values:

  • length_kilometers: The length of the road segment in kilometers.
  • length_miles: The length of the road segment the in miles.
  • posted_speed_limit_kph: The posted speed limit of the road segment in kilometers per hour.
  • posted_speed_limit_mph: The posted speed limit of the road segment in miles per hour.
  • posted_speed_limit_mps: The posted speed limit of the road segment in meters per second.
  • posted_truck_speed_limit_kph: The posted truck speed limit of the road segment in kilometers per hour.
  • posted_truck_speed_limit_mph: The posted truck speed limit of the road segment in miles per hour.
  • posted_truck_speed_limit_mps: The posted truck speed limit of the road segment in meters per second.

Specify the road properties that the service should return on the output_lines output.

For example: road_properties_on_lines=["length_miles", "length_kilometers"]

return_location_fields

type:booldefault:false

Specify whether the service will return fields on the output_snapped_points and output_lines 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_properties_on_snapped_points 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_lines. This field is only present if return_lines is specified as 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 Side
    • 2: Left Side

output_lines

type:feature

This output is returned if return_lines is specified as true in the input. It includes fields for the properties specified in the road_properties_on_lines 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 valueLimit 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:

  1. 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.

  2. Click Services > Manage Services.

  3. 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) >.

  4. 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.

  5. 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.

  6. Click Save and Restart to apply your edits and restart the service.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close