- URL:URL:https://<ndlayer-url>/locate
- Version Introduced:11.1
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.
Note:
The settings and barriers you use to locate inputs should match the eventual analysis settings when you perform routing service; otherwise, the routing services may still relocate because the locations are not valid for a different travel mode or with barriers.
- 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
| Parameter | Details |
|---|---|
| inputLocations (Required) | One or more input locations. Syntax: |
| token (Required) | The identity of a user who has permissions to access the service. |
| f (Optional) | The response format. The default value is html. Values: html | json| pjson |
| travelMode (Optional) | The mode of transportation for the analysis. Value: JSON object |
| locateSettings (Optional) | Specify the settings that affect how inputs are located. Value: JSON object |
| barriers (Optional) | One or more points that act as temporary restrictions to prevent locating on streets that intersect with the point barriers. Syntax: |
| polylineBarriers (Optional) | One or more polyline barriers that act as temporary restrictions to prevent locating on streets that intersect with polyline barriers. Syntax: |
| polygonBarriers (Optional) | One or more polygon barriers that act as temporary restrictions to prevent locating on streets that intersect with polygon barriers. Syntax: |
| returnBarriers (Optional) | Specify whether barriers will be returned by the service. The default value is false. Values: true | false |
| returnPolylineBarriers (Optional) | Specify whether polyline barriers will be returned by the service. The default value is false. Values: true | false |
| returnPolygonBarriers (Optional) | Specify whether polygon barriers will be returned by the service. The default value is false. Values: true | false |
| outputSourceFieldNames (optional) | The fields from which the located source feature values will be retrieved. This parameter is specified as a comma-separated list of names. The values can be specified as in the example below: Note:These value are specific to the services published with the ArcGIS StreetMap Premium data. The values will be different if you are using other data for the analysis. |
| outSR (Optional) | The spatial reference of the output geometries. |
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 incidentsinputLocations=x1,y1; x2, y2; ...; xn, yn
Example using simple syntaxinputLocations=-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).
Note:
SourceID, SourceOID, PosAlong, and SideOfEdge are location fields. If these fields are included in the input, and if allowAutoRelocate is set to false in the locateSettings parameter, the analysis will use the location fields as is, without relocating. Otherwise, the analysis will calculate the location of input based on the geometry of the input. These fields are not required or needed in most cases when using the locate service.
- 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.
With right-hand traffic, the curb approach that leaves the vehicle closest to the input location is Right side of vehicle. 
With left-hand traffic, the curb approach that leaves the vehicle closest to the input location is Left side of vehicle. - 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.
- 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.
- 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.)
{
"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.
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:
https://machine.domain.com/webadaptor/rest/services/Routing/NetworkAnalysis/NAServer/Routing_ND/retrieveTravelModes?f=json&token=<yourToken>Note:
See Implementing App Login for ArcGIS Online and Acquire ArcGIS tokens for ArcGIS Enterprise to learn how to generate one.
The response below is returned by the retrieveTravelModes service.
Note:
Because the response is quite verbose, the elements in the response are abbreviated for clarity.
{
"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:
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 allowAutoRelocatein 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
Note:
To obtain the default value for the parameter, see the network dataset layer resource.
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 whereclause 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.
Note:
Polyline barriers and polygon barriers doesn't support the tolerance and toleranceUnits properties.
{
"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.{
"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.
{
"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 barriersbarriers=x1,y1; x2, y2; ...; xn, yn
Example using simple syntaxbarriers=-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).
Note:
SourceID, SourceOID, PosAlong, and SideOfEdge are location fields. If these fields are present on the barrier, and if allowAutoRelocate is set to false in the locateSettings parameter, the analysis will use the location fields as is without relocating. Otherwise, the analysis will calculate the location of the barrier based on the geometry of the barrier. These fields are not required or needed in most locate service cases.
Example for barriers
Specify barrier geometries and attributes using a FeatureSet object.
This example shows how to specify barriers using ObjectID:
{
"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
Note:
If the locations field is present on the polylineBarriers, and if allowAutoRelocate is set to false in the locateSettings parameter, the analysis will use the location fields as is without relocating. Otherwise, the analysis will calculate the location of the polyline barrier based on the geometry of the line barrier. This field is not required or needed in most locate service cases.
Example for polylineBarriers
Specify polylineBarriersgeometries and attributes using a feature set object.
This example shows how to specify polyline barriers using ObjectID.
{
"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.
Note:
If the locations field is present on the polylgonBarriers, and if allowAutoRelocate is set to false in the locateSettings parameter, the analysis will use the location fields as is without relocating. Otherwise, the analysis will calculate the location of the polygon barrier based on the geometry of the polygon barrier. This field is not required or needed in most locate service cases.
Example for polygonBarriers
Specify polygonBarriersgeometries and attributes using a feature set object.
This example shows how to specify polygon barriers using ObjectID.
{
"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.
| Field name | Description |
|---|---|
ObjectID | The value for this field will be the ObjectID of the associated input. If the ObjectID is not specified on the input, 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 |
The direction a vehicle can arrive at and depart from the stop. The values for this field are copied from the CurbApproach field on the input stops. |
Status | Specifies the status of the point with respect to its location on the network and the outcome of the analysis. The possible values are the following:
|
SnapX | The x-coordinate of the position on the network dataset where the point was located, in the coordinate system of the network dataset. |
SnapY | The y-coordinate of the position on the network dataset where the point was located, in the coordinate system of the network dataset. |
SnapZ | The z-coordinate of the position on the network dataset where the point was located, in the coordinate system of the network dataset. The SnapZ field is 0 if the network is two dimensional. |
DistanceToNetworkInMeters | The distance in meters between the point's geographic location and the position where it was located on the network. |
BuildTime | The build timestamp of the network dataset used by the locating service. |
barriers
This provides access to attributes of the barriers located by the service.
| Field name | Description |
|---|---|
ObjectID | The value for this field will be the ObjectID of the associated input. If the ObjectID is not specified on the input, 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 |
The direction a vehicle can arrive at and depart from the stop. The values for this field are copied from the CurbApproach field on the input stops. |
Status | Specifies the status of the point with respect to its location on the network and the outcome of the analysis. The possible values are the following:
|
SnapX | The x-coordinate of the position on the network dataset where the point was located, in the coordinate system of the network dataset. |
SnapY | The y-coordinate of the position on the network dataset where the point was located, in the coordinate system of the network dataset. |
SnapZ | The z-coordinate of the position on the network dataset where the point was located, in the coordinate system of the network dataset. The SnapZ field is 0 if the network is two dimensional. |
DistanceToNetworkInMeters | The distance in meters between the point's geographic location and the position where it was located on the network. |
BuildTime | The build timestamp of the network dataset used by the locating service. |
polylineBarriers
This provides access to attributes of the polyline barriers located by the service.
| Field name | Description |
|---|---|
ObjectID | The value for this field will be the ObjectID of the associated input. If the ObjectID is not specified on the input, a unique ID is automatically generated in the output. |
Locations | The location ranges of polyline barriers as base64. |
BarrierType | Specify if the barrier restricts travel completely or scales time or distance when it is crossed. The value for this attribute is specified as one of the following integers (use the numeric code, not the name in parentheses):
|
polygonBarriers
This provides access to attributes of the polygon barriers located by the service.
| Field name | Description |
|---|---|
ObjectID | The value for this field will be the ObjectID of the associated input. If the ObjectID is not specified on the input, a unique ID is automatically generated in the output. |
Locations | The location ranges of polygon barriers as base64. |
BarrierType | Specify if the barrier restricts travel completely or scales time or distance when it is crossed. The value for this attribute is specified as one of the following integers (use the numeric code, not the name in parentheses):
|
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
{
"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
{
"error": {
"code": <code>,
"message": "<message>",
"details": [
"<details>"
]
}
}