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.

GPS TrackSnap to roads result

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,

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.

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
65
66
67
68
69
70
{
  "features": [
    {
      "attributes": {
        "OBJECTID": 1,
        "location_timestamp": 1704522159000,
        "track_id": "track 1"
      },
      "geometry": {
        "x": -122.43410099956145,
        "y": 37.800155000053394
      }
    },
    {
      "attributes": {
        "OBJECTID": 2,
        "location_timestamp": 1704522171000,
        "track_id": "track 1"
      },
      "geometry": {

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 wouldn't use all the travel mode settings as is, but it will take the travel mode into account when determining 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"]

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 following attributes that are either generated or altered by the service.

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 following attributes that are generated by the service.

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.

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.