Locate service

Description

When performing analysis using routing services, the inputs to an analysis rarely fall exactly on top of the edges or junctions of the network dataset the service is using. For example, you may be using a network dataset constructed from street centerlines to power your routing services, and the input points you want to analyze are the centroids of parcels in your city. These parcel centroids do not fall on top of the street centerlines; rather, they are offset some distance from the streets. To successfully perform a network analysis using your routing services, the routing services must identify the location on the network dataset where each analysis input lies. This network location, rather than the input's original location, is used in the analysis. Typically, the longitude and latitude of the inputs are passed in and the routing services compute the location on the network during the solve operation. With the locate service, you can compute the locations on the network before calling the solve operation.

Learn more about locating inputs

The locate service is performed on a network dataset layer resource. You can provide arguments to the locate service as query parameters defined in the parameters table below. The locate service can be used in scenarios such as the following:

• Reuse location fields during the solve operation—You have a set of regularly serviced customers. You can use the locate service to calculate location fields, and use the located inputs in the routing services. This helps to speed up routing services since the service doesn't need to locate inputs again and you can reuse the locations in multiple places.

• Compute serviceability—Before you perform a routing request, you can call locate to determine serviceability. For example, the mode of travel may only allow service inputs that are 500 meters off the streets. You can perform a locate service with 500 meters as the search tolerance and determine which inputs cannot be serviced before you perform a more advanced routing service.
• Use DistanceToNetworkInMeters to calculate service time—You can gain information from the locate service response to fine-tune your routing service settings. For example, if you want to know how far each input is off network to perform delivery analysis, and it takes time to go from the parked vehicle location to the delivery location, you can use the DistanceToNetworkInMeters field for each record in the response. Once you know how far away the actual location is from the network, you can use a speed factor to calculate a service time for each input based on its distance off the network.
• Query fields from the underlying source features—The locate service also supports returning additional field values from the source features where the inputs are located. For example, you can set different curb approaches on the inputs depending on the type of road on which they're located. If the input is located on a major road, you can set it to right or left side of the vehicle, depending on the driving side of the country where it's located. If the input is located on a local road, either side of curb approach will work since a vehicle can cross a local road for a delivery.

Request parameters

1
outputSourceFieldNames=ROAD_CLASS,FULL_STREET_NAME

Required parameters

inputLocations

Specify one or more locations to locate.

You can use a simple comma- and semicolon-based syntax if you are passing the input locations using their longitude and latitude values in the WGS84 coordinate system and don't need to pass additional fields for each location.

Simple syntax for incidents

1
inputLocations=x1,y1; x2, y2; ...; xn, yn

Example using simple syntax

1
inputLocations=-117.1957,34.0564; -117.184,34.0546

Attributes for inputLocations

You can specify attributes for each inputLocations using the FeatureSet object. The attributes listed below are predefined for inputLocations . If these attributes are specified, it may impact the location. Custom attributes that you specify for the inputLocations , will be included in the outputLocations parameter in the response.

• ObjectID

  The object ID of the input. ObjectID is a unique identifier for each input. If the ObjectID is not specified, a unique ID is automatically generated in the output.

• SourceID

  The numeric identifier of the network dataset source feature class on which the input point is located.

• SourceOID

  The ObjectID of the feature in the source on which the input point is located.

• PosAlong

  The position along the digitized direction of the source line feature. This value is stored as a ratio. This field is null if the network location references a junction.

• SideOfEdge

  The side of the edge in relation to the digitized direction of the line feature. This field is limited to a domain of two values: Right Side (1) and Left Side (2).

• CurbApproach

  Specify the direction a vehicle can arrive at and depart from the input location.

  One of the integers listed in the Coded value column in the following table must be specified as a value of this attribute. The values in the Setting column are the descriptive names for CurbApproach attribute values that you may have seen when using the ArcGIS Network Analyst extension software.

  Setting	Coded value	Description
  Either side of vehicle	0	The vehicle can approach and depart the input location in either direction, so a U-turn is allowed at the input location. This is the default value. This setting can be chosen if it is possible and desirable for a vehicle to turn around at the input location. This decision may depend on the width of the road and the amount of traffic or whether the input location has a parking lot where vehicles can pull in and turn around. All arrival and departure combinations are allowed with the Either side of vehicle curb approach setting.
  Right side of vehicle	1	When the vehicle approaches and departs the input location, the input location must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive with the bus stop on the right side. The allowed arrival and departure combination for the Right side of vehicle curb approach setting is shown.
  Left side of vehicle	2	When the vehicle approaches and departs the input location, the input location must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive with the bus stop on the left side. The allowed arrival and departure combination for the Left side of vehicle curb approach setting is shown.
  No U-Turn	3	When the vehicle approaches the input location, the input location can be on either side of the vehicle; however, when it departs, the vehicle must continue in the same direction it arrived. A U-turn is prohibited. The allowed arrival and departure combinations for the No U-Turn curb approach setting is shown.

  The CurbApproach attribute is designed to work with both types of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider a location on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach this location from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, if you want to arrive at a location and not have a lane of traffic between the vehicle and the location, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

  

  

• Bearing

  The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

  Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

  Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

  Learn more about bearing and bearing tolerance

• BearingTol

  The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the Bearing field value is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

  The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

  Learn more about bearing and bearing tolerance

• BuildTime

  The build time stamp of the network dataset when the locations were last located. This is used when locating to know whether there is a need to relocate.

Example for inputLocations

Specify inputLocations geometries and attributes using a feature set object. This example shows how to specify the ObjectID, Name, and Tag attributes for each input location. (Name and Tag are examples of custom fields that contain information you may want to use in further analysis.)

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
{
    "displayFieldName": "",
    "geometryType": "esriGeometryPoint",
    "spatialReference": {
        "wkid": 4326,
        "latestWkid": 4326
    },
    "fields": [{
            "name": "OBJECTID",
            "type": "esriFieldTypeOID",
            "alias": "OBJECTID"
        },
        {
            "name": "Name",
            "type": "esriFieldTypeString",
            "alias": "Name",
            "length": 500
        },
        {
            "name": "Tag",
            "type": "esriFieldTypeString",
            "alias": "Tag",
            "length": 1000
        }
    ],
    "features": [{
            "attributes": {
                "ObjectID": 1,
                "Name": "Stop1",
                "TAG": "TAG-001"
            },
            "geometry": {
                "x": -122.4079,
                "y": 37.78356
            }
        },
        {
            "attributes": {
                "ObjectID": 2,
                "Name": "Stop2",
                "TAG": "TAG-002"
            },
            "geometry": {
                "x": -122.404,
                "y": 37.782
            }
        }
    ]
}

token

Use this parameter to 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.

1
token=<yourToken>

Optional parameters

f

Use this parameter to specify the response format. The parameter can have html , json or pjson as arguments, for example, f=json . The pjson value is used for printing the JSON response in a prettified format.

travelMode

Choose the mode of transportation for the analysis.

The selected travel mode may affect locating input locations, because some streets that are restricted for vehicles may not be restricted for pedestrians. When locating the input locations, the restrictions on the travel mode are taken into consideration so the service doesn't locate on restricted elements.

Travel modes are managed in ArcGIS Enterprise and can be configured by the administrator of your organization to better reflect the organization's workflows.

To learn more about travel modes, see Configure travel modes.

The value for the travelMode parameter is the JSON object containing the settings for a travel mode supported by your organization. To get the supported travel modes, run the retrieveTravelModes service.

You can make a request to retrieve travel modes using the following form:

1
https://machine.domain.com/webadaptor/rest/services/Routing/NetworkAnalysis/NAServer/Routing_ND/retrieveTravelModes?f=json&token=<yourToken>

The response below is returned by the retrieveTravelModes service.

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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
{
    "currentVersion": 11.1,
    "defaultTravelMode": "FEgifRtFndKNcJMJ",
    "supportedTravelModes": [
     {
      "attributeParameterValues": [
       {
        "attributeName": "Avoid Private Roads",
        "parameterName": "Restriction Usage",
        "value": "AVOID_MEDIUM"
       },
       {
        "attributeName": "Walking",
        "parameterName": "Restriction Usage",
        "value": "PROHIBITED"
       },
       {
        "attributeName": "Preferred for Pedestrians",
        "parameterName": "Restriction Usage",
        "value": "PREFER_LOW"
       },
       {
        "attributeName": "WalkTime",
        "parameterName": "Walking Speed (km/h)",
        "value": 5
       },
       {
        "attributeName": "Avoid Roads Unsuitable for Pedestrians",
        "parameterName": "Restriction Usage",
        "value": "AVOID_HIGH"
       }
      ],
      "description": "Follows paths and roads that allow pedestrian traffic and finds solutions that optimize travel time. The walking speed is set to 5 kilometers per hour.",
      "distanceAttributeName": "Kilometers",
      "id": "caFAgoThrvUpkFBW",
      "impedanceAttributeName": "WalkTime",
      "name": "Walking Time",
      "restrictionAttributeNames": [
       "Avoid Private Roads",
       "Avoid Roads Unsuitable for Pedestrians",
       "Preferred for Pedestrians",
       "Walking"
      ],
      "simplificationTolerance": 2,
      "simplificationToleranceUnits": "esriMeters",
      "timeAttributeName": "WalkTime",
      "type": "WALK",
      "useHierarchy": false,
      "uturnAtJunctions": "esriNFSBAllowBacktrack"
     },
     {
      "attributeParameterValues": [
       {
        "attributeName": "Avoid Private Roads",
        "parameterName": "Restriction Usage",
        "value": "AVOID_MEDIUM"
       },
       {
        "attributeName": "Walking",
        "parameterName": "Restriction Usage",
        "value": "PROHIBITED"
       },
       {
        "attributeName": "Preferred for Pedestrians",
        "parameterName": "Restriction Usage",
        "value": "PREFER_LOW"
       },
       {
        "attributeName": "WalkTime",
        "parameterName": "Walking Speed (km/h)",
        "value": 5
       },
       {
        "attributeName": "Avoid Roads Unsuitable for Pedestrians",
        "parameterName": "Restriction Usage",
        "value": "AVOID_HIGH"
       }
      ],
      "description": "Follows paths and roads that allow pedestrian traffic and finds solutions that optimize travel distance.",
      "distanceAttributeName": "Kilometers",
      "id": "yFuMFwIYblqKEefX",
      "impedanceAttributeName": "Kilometers",
      "name": "Walking Distance",
      "restrictionAttributeNames": [
       "Avoid Private Roads",
       "Avoid Roads Unsuitable for Pedestrians",
       "Preferred for Pedestrians",
       "Walking"
      ],
      "simplificationTolerance": 2,
      "simplificationToleranceUnits": "esriMeters",
      "timeAttributeName": "WalkTime",
      "type": "WALK",
      "useHierarchy": false,
      "uturnAtJunctions": "esriNFSBAllowBacktrack"
     },
     {
      "attributeParameterValues": [
       {
        "attributeName": "Avoid Private Roads",
        "parameterName": "Restriction Usage",
        "value": "AVOID_MEDIUM"
       },
       {
        "attributeName": "Driving an Automobile",
        "parameterName": "Restriction Usage",
        "value": "PROHIBITED"
       },
       {
        "attributeName": "Through Traffic Prohibited",
        "parameterName": "Restriction Usage",
        "value": "AVOID_HIGH"
       },
       {
        "attributeName": "TravelTime",
        "parameterName": "Vehicle Maximum Speed (km/h)",
        "value": 0
       },
       {
        "attributeName": "Roads Under Construction Prohibited",
        "parameterName": "Restriction Usage",
        "value": "PROHIBITED"
       },
       {
        "attributeName": "Avoid Gates",
        "parameterName": "Restriction Usage",
        "value": "AVOID_MEDIUM"
       },
       {
        "attributeName": "Avoid Express Lanes",
        "parameterName": "Restriction Usage",
        "value": "PROHIBITED"
       },
       {
        "attributeName": "Avoid Carpool Roads",
        "parameterName": "Restriction Usage",
        "value": "PROHIBITED"
       }
      ],
      "description": "Models the movement of cars and other similar small automobiles, such as pickup trucks, and finds solutions that optimize travel time. Travel obeys one-way roads, avoids illegal turns, and    follows other rules that are specific to cars, but does not discourage travel on unpaved roads. When you specify a start time, dynamic travel speeds based on traffic are used where it is available.",
      "distanceAttributeName": "Kilometers",
      "id": "NmNhNDUwZmE1YTlj",
      "impedanceAttributeName": "TravelTime",
      "name": "Rural Driving Time",
      "restrictionAttributeNames": [
       "Avoid Carpool Roads",
       "Avoid Express Lanes",
       "Avoid Gates",
       "Avoid Private Roads",
       "Driving an Automobile",
       "Roads Under Construction Prohibited",
       "Through Traffic Prohibited"
      ],
      "simplificationTolerance": 10,
      "simplificationToleranceUnits": "esriMeters",
      "timeAttributeName": "TravelTime",
      "type": "AUTOMOBILE",
      "useHierarchy": true,
      "uturnAtJunctions": "esriNFSBAtDeadEndsAndIntersections"
     },
     {
      "attributeParameterValues": [
       {
        "attributeName": "Avoid Private Roads",
        "parameterName": "Restriction Usage",
        "value": "AVOID_MEDIUM"
       },
       {
        "attributeName": "Driving an Automobile",
        "parameterName": "Restriction Usage",
        "value": "PROHIBITED"
       },
       {
        "attributeName": "Through Traffic Prohibited",
        "parameterName": "Restriction Usage",
        "value": "AVOID_HIGH"
       },
       {
        "attributeName": "TravelTime",
        "parameterName": "Vehicle Maximum Speed (km/h)",
        "value": 0
       },
       {
        "attributeName": "Roads Under Construction Prohibited",
        "parameterName": "Restriction Usage",
        "value": "PROHIBITED"
       },
       {
        "attributeName": "Avoid Gates",
        "parameterName": "Restriction Usage",
        "value": "AVOID_MEDIUM"
       },
       {
        "attributeName": "Avoid Express Lanes",
        "parameterName": "Restriction Usage",
        "value": "PROHIBITED"
       },
       {
        "attributeName": "Avoid Carpool Roads",
        "parameterName": "Restriction Usage",
        "value": "PROHIBITED"
       }
      ],
      "description": "Models the movement of cars and other similar small automobiles, such as pickup trucks, and finds solutions that optimize travel distance. Travel obeys one-way roads, avoids illegal turns,   and follows other rules that are specific to cars, but does not discourage travel on unpaved roads.",
      "distanceAttributeName": "Kilometers",
      "id": "Yzk3NjI1NTU5NjVj",
      "impedanceAttributeName": "Kilometers",
      "name": "Rural Driving Distance",
      "restrictionAttributeNames": [
       "Avoid Carpool Roads",
       "Avoid Express Lanes",
       "Avoid Gates",
       "Avoid Private Roads",
       "Driving an Automobile",
       "Roads Under Construction Prohibited",
       "Through Traffic Prohibited"
      ],
      "simplificationTolerance": 10,
      "simplificationToleranceUnits": "esriMeters",
      "timeAttributeName": "TravelTime",
      "type": "AUTOMOBILE",
      "useHierarchy": true,
      "uturnAtJunctions": "esriNFSBAtDeadEndsAndIntersections"
     },
     ...
    ],
   }

From the JSON above, to pass Walking Time as the travel mode, use the following JSON as the value for the travelMode parameter:

1
travelMode={"attributeParameterValues": [{"parameterName": "Restriction Usage","attributeName": "Walking","value": "PROHIBITED"},{"parameterName": "Restriction Usage","attributeName": "Preferred for Pedestrians","value": "PREFER_LOW"},{"parameterName": "Walking Speed (km/h)","attributeName": "WalkTime","value": 5}],"description": "Follows paths and roads that allow pedestrian traffic and finds solutions that optimize travel time. The walking speed is set to 5 kilometers per hour.","impedanceAttributeName": "WalkTime","simplificationToleranceUnits": "esriMeters","uturnAtJunctions": "esriNFSBAllowBacktrack","restrictionAttributeNames": ["Preferred for Pedestrians","Walking"],"useHierarchy": false,"simplificationTolerance": 2,"timeAttributeName": "WalkTime","distanceAttributeName": "Miles","type": "WALK","id": "caFAgoThrvUpkFBW","name": "Walking Time"}

locateSettings

Use this parameter to specify settings that affect how inputs are located, such as the maximum search distance to use when locating the inputs on the network or the network sources being used for locating. To restrict locating on a portion of the source, you can specify a where clause for a source.

The parameter value is specified as a JSON object. The JSON object allows you to specify a locator JSON for all input feature in the analysis, or you can specify an override for a particular input. The override allows you to have different settings for each analysis input. For example, you can disallow stops to locate on highway ramps and allow point barriers to locate on highway ramps. When specifying the locateSettings JSON, you must provide all the properties including tolerance , toleranceUnits , sources , and allowAutoRelocate in the default locator JSON object. The where clause for each source is optional. If you need to provide a different locator JSON for a particular input class, you must include the overrides property for that input. The property name must match the input parameter name. The locator JSON for a particular input doesn't need to include all the properties; you only need to include the properties that are different from the default locator JSON properties.

Learn more about locating inputs

The locator JSON object has the following properties:

• tolerance and toleranceUnits —Allows you to control the maximum search distance when locating inputs. If no valid network location is found within this distance, the input features will be considered unlocated. A small search tolerance decreases the likelihood of locating on the wrong street but increases the likelihood of not finding any valid network location. The toleranceUnits parameter value should be specified as one of the following values:

  • esriFeet
  • esriKilometers
  • esriMeters
  • esriMiles
  • esriNauticalMiles
  • esriYards

• sources —Allows you to control which network source can be used for locating. For example, you can configure the analysis to locate inputs on streets but not on sidewalks. The list of possible sources on which to locate is specific to the network dataset this service references. Only the sources that are present in the sources array are used for locating. Optionally, you can specify a where clause on each source you specified in the sources array to further restrict locating on that source matching certain characteristics using a SQL expression. For example, you can configure the analysis to locate inputs only on street features matching certain road classes, for example, to avoid highway ramps. Sources is specified as an array of objects, each having the following properties:

  • name —The name of the network source feature class that can be used for locating inputs.
  • where —An SQL expression on the network source feature class.

• allowAutoRelocate —Allows you to control whether inputs with existing network location fields can be automatically relocated to ensure valid, routable location fields for the analysis. If the value is true , points located on restricted network elements and points affected by barriers will be relocated to the closest routable location. If the value is false , network location fields will be used as is even if the points are unreachable. Even if the value is false , inputs with no location fields or incomplete location fields will be located.

Syntax for locateSettings

Syntax for specifying locateSettings using JSON structure.

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
{
    "default": {
        "tolerance": <value>,
        "toleranceUnits": "<unit>",
        "allowAutoRelocate": true | false,
        "sources": [{
            "name": "<sourceName>",
            "where": "<whereClause>"
        }]
    },
    "overrides": {
         "inputLocations": {
            "tolerance": <value>,
            "toleranceUnits": "<unit>",
            "allowAutoRelocate": true | false,
            "sources": [{
                "name": "<sourceName>",
                "where": "<whereClause>"
            }]
        },
        "barriers": {
            "tolerance": <value>,
            "toleranceUnits": "<unit>",
            "allowAutoRelocate": true | false,
            "sources": [{
                "name": "<sourceName>",
                "where": "<whereClause>"
            }]
        },
        "polylineBarriers": {
            "allowAutoRelocate": true | false,
            "sources": [{
                "name": "<sourceName>",
                "where": "<whereClause>"
            }]
        },
        "polygonBarriers": {
            "allowAutoRelocate": true | false,
            "sources": [{
                "name": "<sourceName>",
                "where": "<whereClause>"
            }]
        }
    }
}

Examples for locateSettings

Example 1: Specify default locate settings using JSON structure

This example shows how to specify locate settings so inputs are only located within 500 meters of the specified location. A small search tolerance like this may be valuable if you are locating using a walking travel mode and don't want inputs to be located farther than 500 meters from the original point location.

1
2
3
4
5
6
7
8
9
10
{
    "default": {
        "tolerance": 500,
        "toleranceUnits": "esriMeters",
        "allowAutoRelocate": true,
        "sources": [{
            "name": "Routing_Streets"
        }]
    }
}

Example 2: Specify default locate settings and locate settings overrides for some inputs using JSON structure

This example shows how to specify locate settings to prevent input locations from locating on highway ramps. The default locate settings allow locating on the Routing_Streets source. For input locations, the overrides option is used to specify a where clause for the Routing_Streets source to prevent locating on highway ramps (a ROAD_CLASS field value of 3). With this locateSettings JSON, input locations cannot locate on highway ramps, but barriers can because they use the default locate settings, which do not include a where clause.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "default": {
        "tolerance": 20,
        "toleranceUnits": "esriKilometers",
        "allowAutoRelocate": true,
        "sources": [{
            "name": "Routing_Streets"
        }]
    },
    "overrides": {
        "inputLocations": {
            "sources": [{
                "name": "Routing_Streets",
                "where": "ROAD_CLASS <> 3"
            }]
        }
    }
}

barriers

Use this parameter to specify one or more points that will act as temporary restrictions on the underlying streets. For example, a point barrier can be used to represent a fallen tree along a street.

You can use a simple comma- and semicolon-based syntax if you are passing the point barrier locations using their longitude and latitude values in the WGS84 coordinate system and don't need to pass additional fields for each location.

Simple syntax for barriers

1
barriers=x1,y1; x2, y2; ...; xn, yn

Example using simple syntax

1
barriers=-117.1957,34.0564; -117.184,34.0546

Attributes for barriers

You can specify attributes for each barrier using the FeatureSet object. The attributes listed below are predefined on the barriers. Locating the barrier may be impacted if these attribute values are specified.

ObjectID

The object ID of the barrier. The ObjectID is a unique identifier for each barrier. If no ObjectID is specified, a unique ID is automatically generated in the output.

SourceID

The numeric identifier of the network dataset source feature class on which the input point is located.

SourceOID

The ObjectID of the feature in the source on which the input point is located.

PosAlong

The position along the digitized direction of the source line feature. This value is stored as a ratio. This field is null if the network location references a junction.

SideOfEdge

The side of the edge in relation to the digitized direction of the line feature. This field is limited to a domain of two values: Right Side (1) and Left Side (2).

Example for barriers

Specify barrier geometries and attributes using a FeatureSet object.

This example shows how to specify barriers using ObjectID :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "displayFieldName": "",
    "geometryType": "esriGeometryPoint",
    "spatialReference": {
        "wkid": 4326,
        "latestWkid": 4326
    },
    "fields": [{
            "name": "ObjectID",
            "type": "esriFieldTypeOID",
            "alias": "ObjectID"
        }
    ],
    "features": [{
        "attributes": {
            "ObjectID": 1
        },
        "geometry": {
            "x": -122.053461,
            "y": 37.541479
        }
    }]
}

polylineBarriers

Use this parameter to specify one or more lines that prohibit travel anywhere the lines intersect the streets. For example, a parade or protest that blocks traffic across several street segments can be modeled with a polyline barrier.

Attributes for polylineBarriers

You can specify attributes for each polyline barrier using the FeatureSet object. The following attributes are predefined on the polyline barriers. Locating the barrier may be impacted if these attributes are specified.

ObjectID

The object ID of the line barrier. The ObjectID is a unique identifier for the line barrier. If no ObjectID is specified, a unique ID is automatically generated in the output.

Locations

The locations range BLOB field representing the location of the polyline barrier on the network

Example for polylineBarriers

Specify polylineBarriers geometries and attributes using a feature set object.

This example shows how to specify polyline barriers using ObjectID .

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
{
    "displayFieldName": "",
    "geometryType": "esriGeometryPolyline",
    "spatialReference": {
        "wkid": 4326,
        "latestWkid": 4326
    },
    "fields": [{
            "name": "ObjectID",
            "type": "esriFieldTypeOID",
            "alias": "ObjectID"
        }
    ],
    "features": [{
        "attributes": {
            "ObjectID": 1
        },
        "geometry": {
            "paths": [
                [
                    [-117.15881790299994, 32.721517814000038],
                    [-117.15873274499995, 32.71621669600006]
                ]
            ]
        }
    }]
}

polygonBarriers

Use this parameter to specify polygons that restrict travel on the streets intersected by the polygons.

Attributes for polygonBarriers

You can specify attributes for each polygon barrier using the FeatureSet object. The attributes listed below are predefined on the polygon barriers. Locating the barrier may be impacted if these attributes are specified.

ObjectID

The object ID of the polygon barrier. The ObjectID is a unique identifier for the polygon barrier. If no ObjectID is specified, a unique ID is automatically generated in the output.

Locations

The locations range BLOB field representing the location of the polygon barrier on the network.

Example for polygonBarriers

Specify polygonBarriers geometries and attributes using a feature set object.

This example shows how to specify polygon barriers using ObjectID .

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
{
    "displayFieldName": "",
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {
        "wkid": 4326,
        "latestWkid": 4326
    },
    "fields": [{
            "name": "ObjectID",
            "type": "esriFieldTypeOID",
            "alias": "ObjectID"
        }
    ],
    "features": [{
        "attributes": {
            "ObjectID": 1
        },
        "geometry": {
            "rings": [
                [
                    [-117.16058494299995, 32.715982512000039],
                    [-117.15681667899997, 32.715939932000026],
                    [-117.15690183699996, 32.711809745000039],
                    [-117.16064881099999, 32.71180974400005],
                    [-117.16058494299995, 32.715982512000039]
                ]
            ]
        }
    }]
}

returnBarriers

Specify whether barriers will be returned by the service.

• true —The input point barriers are returned as part of the barriers property in the JSON response.
• false —Point barriers are not returned. This is the default.

For this parameter to take effect, you must also specify a value for the barriers parameter.

You can set the returnBarriers parameter to true to see where the barriers were located on the street network or, if they weren't located, understand what the problem was by checking the Status property in the JSON response.

returnPolylineBarriers

Specify whether polyline barriers will be returned by the service.

• true —The input polyline barriers are returned as part of the polylineBarriers property in the JSON response.
• false —Polyline barriers are not returned. This is the default.

For this parameter to take effect, you must also specify a value for the polylineBarriers parameter.

returnPolygonBarriers

Specify whether polygon barriers will be returned by the service.

• true —The input polygon barriers are returned as part of the polygonBarriers property in the JSON response.
• false —Polygon barriers are not returned. This is the default.

For this parameter to take effect, you must also specify a value for the polygonBarriers parameter.

outputSourceFieldNames

Use this parameter to specify the fields from which the located source feature values will be retrieved. The parameter is specified as a comma-separated list of names.

For example, you may want to know the road class for the feature where the inputs are located so you know whether the inputs are located on a local road, major road, or highway. This information can be helpful to set the curb approach for the input when you use other routing services to solve, so your drivers don't cross a major road or highway for a delivery. Another example is you know the street names where the inputs are supposed to locate, and you want to know the street name where the inputs located during the locate process so you can validate they locate on the correct feature. In this case, you can set outputSourceFieldNames to the fields you are interested in. For example, if you want to return both road class and street name, you can specify outputSourceFieldNames as "ROAD_CLASS, FULL_STREET_NAME" (ROAD_CLASS, FULL_STREET_NAME for the fields on the street source feature of the ArcGIS StreetMap Premium network dataset. (The fields may be different if you use other data for the service). You can find the field names for each source feature by querying network dataset layer resource.

If the feature where the input is located doesn't have the field you specified, it will not be included in the output. If you have multiple inputs that locate on different feature classes, some fields might exist on one feature but not the other. In those cases, the field will be included in the output, but the value may be empty.

outSR

Use this parameter to specify the spatial reference of the geometries, such as line or point features, returned by the service.

The parameter value can be specified as a well-known ID (WKID) for the spatial reference. See Using spatial references to look up WKID values.

Many of the basemaps provided by ArcGIS Online are in the Web Mercator spatial reference (WKID 102100). Specifying outSR=102100 returns the geometries in the Web Mercator spatial reference, which can be drawn on top of the basemaps.

Output parameters

Upon successful operation, the service returns the located inputs and barriers if requested. The status field on the outputs indicates whether each feature is located. The service won't fail if the inputs are not located, so you need to inspect the status field to know which features are located and which features are not. The fields for each output are described below. Custom fields defined on inputs are included in the output but are not included in the table below.

outputLocations

This provides access to the attributes of the locations located by the service. You can use the attributes from this parameter, such as the Status field, to determine whether a particular input was located.

barriers

This provides access to attributes of the barriers located by the service.

polylineBarriers

This provides access to attributes of the polyline barriers located by the service.

polygonBarriers

This provides access to attributes of the polygon barriers located by the service.

JSON Response syntax

The JSON response from the locate service is based on the syntax below. The actual properties returned in the response depend on the request parameters. For example, the barriers property is returned only if returnBarriers is set to true . If a request fails, the JSON response only contains the error property. The examples in the subsequent section illustrate the response returned with specific request parameters.

JSON Response syntax for a successful request

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
{
    "requestID": "<requestID>",
    "outputLocations": {
        "displayFieldName": "",
        "geometryType": "esriGeometryPoint",
        "spatialReference": {<spatialReference>},
        "fields": [{
                "name": "<fieldName>",
                "type": "<fieldType>",
                "alias": "<fieldAlias>"
            },
            ...
        ],
        "features": [{
            "attributes": {
                "<fieldName>": <fieldValue>,
                ...
            },
            "geometry": {<point>}
        },
        ...
        ]
    },
    "barriers": {
        "displayFieldName": "",
        "geometryType": "esriGeometryPoint",
        "spatialReference": {<spatialReference>},
        "fields": [{
            "name": "<fieldName>",
            "type": "<fieldType>",
            "alias": "<fieldAlias>"
            },
            ...
        ],
        "features": [{
            "attributes": {
                "<fieldName>": <fieldValue>,
                ...
            },
            "geometry": {<point>}
        },
        ...
        ]
    },
    "polylineBarriers": {
        "displayFieldName": "",
        "geometryType": "esriGeometryPolyline",
        "spatialReference": {<spatialReference>},
        "fields": [{
            "name": "<fieldName>",
            "type": "<fieldType>",
            "alias": "<fieldAlias>"
            },
            ...
        ],
        "features": [{
            "attributes": {
                "<fieldName>": <fieldValue>,
                ...
            },
            "geometry": {<polyline>}
        },
        ...
        ]
    },
    "polygonBarriers": {
        "displayFieldName": "",
        "geometryType": "esriGeometryPolygon",
        "spatialReference": {<spatialReference>},
        "fields": [{
            "name": "<fieldName>",
            "type": "<fieldType>",
            "alias": "<fieldAlias>"
            },
            ...
        ],
        "features": [{
            "attributes": {
                "<fieldName>": <fieldValue>,
                ...
            },
            "geometry": {<polygon>}
        },
        ...
        ]
    }
}

JSON Response syntax for a failed request

1
2
3
4
5
6
7
8
9
{
  "error": {
    "code": <code>,
    "message": "<message>",
    "details": [
      "<details>"
    ]
  }
}