Create Threshold Areas

inputLayer (Required)

The point features to be used to create threshold areas.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

• A URL to a feature service layer with an optional filter to select specific features
• A feature collection

Examples:

• {"url": <feature service layer url>, "filter": <where clause>}
• {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

idField (Required)

A field on the inputLayer that uniquely identifies each output threshold feature as an attribute.

Example: "idField": "STORE_ID"

thresholdVariable (Required)

Defines a variable in a data collection you want to use for the threshold variable. Its value is a list of strings in the form of dataCollection.VariableName.

Example: "thresholdVariable": "KeyUSFacts.TOTPOP10"

thresholdValues

An array of double values representing the threshold values.

Examples:

• "thresholdValues": [10000]
• "thresholdValues": [10000,20000,30000]

thresholdExpression

An Arcade expression used for defining the threshold values.

Example: "thresholdExpression": $feature.USER_SALES * 100

distanceType

Defines how distance is calculated. You can specify either straight line distance or a travel mode.

Valid values are a string, StraightLine, which indicates Euclidean distance to be used as distance measure or a JSON object representing settings for a travel mode.

Travel modes are managed and can be configured by the administrator of your organization to better reflect your organization's workflows. You need to specify the JSON object containing the settings for a travel mode supported by your organization. To get a list of supported travel modes, execute the GetTravelModes tool from the Utilities service.

The value for the distanceType parameter should be a JSON object representing travel mode settings. When you use the GetTravelModes tool from the Utilities service, you get a string representing the travel mode JSON. You need to convert this string to a valid JSON object using your API and then pass the JSON object as the value for the distanceType parameter.

Examples:

• "distanceType":"StraightLine"
• "distanceType":

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
{
 "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"
}

distanceUnits

The units of the distanceType parameter.

Example: "distanceUnits": "Kilometers"

maxIterations

The maximum number of times Network Analysis will iterate to find the threshold values.

The default is null and results in no limits to the number of iterations used to reach the threshold value.

Example: "maxIterations": 5

travelDirection

Specify whether the direction of travel used to generate the travel areas is toward or away from the input locations.

Values: FromFacility | ToFacility

Default: FromFacility

Example: "travelDirection": "ToFacility"

timeOfDay

Specify whether travel times should consider traffic conditions. The timeOfDay value represents the time at which travel begins, or departs, from the input points. The time is specified as Unix time (milliseconds since midnight, January 1, 1970).

The service supports two types of traffic, typical and live:

• Typical traffic references travel speeds that are made up of historical averages for each five-minute interval spanning a week.
• Live traffic retrieves speeds from a traffic feed that processes phone probe records, sensors, and other data sources to record actual travel speeds and predict speeds for the near future.

The Data Coverage page shows the countries Esri currently provides traffic data for.

Typical Traffic: To ensure the task uses typical traffic in locations where it is available, choose a time and day of the week, and then convert the day of the week to one of the following dates from 1990:

• Monday—1/1/1990
• Tuesday—1/2/1990
• Wednesday—1/3/1990
• Thursday—1/4/1990
• Friday—1/5/1990
• Saturday—1/6/1990
• Sunday—1/7/1990

Set the time and date as Unix time in milliseconds.

For example, to solve for 1:03 p.m. on Thursdays, set the time and date to 1:03 p.m., 4 January 1990, and convert to milliseconds (631458180000).

Live Traffic: To use live traffic when and where it is available, choose a time and date and convert to Unix time.

Esri saves live traffic data for 4 hours and references predictive data extending 4 hours into the future. If the time and date you specify for this parameter is outside the 8-hour time window, or the travel time in the analysis continues past the predictive data window, the task falls back to typical traffic speeds.

Syntax: The number of milliseconds since the Unix epoch (January 1, 1970).

Examples:

• "timeOfDay": 631458180000 // 13:03, 4 January 1990. Typical traffic on Thursdays at 1:03 p.m.
• "timeOfDay": 631731600000 // 17:00, 7 January 1990. Typical traffic on Sundays at 5:00 p.m.
• "timeOfDay": 1413964800000 // 8:00, 22 October 2014. If the current time is between 8:00 p.m., 21 Oct. 2014, and 8:00 p.m., 22 Oct. 2014, live traffic speeds are referenced in the analysis; otherwise, typical traffic speeds are referenced.
• "timeOfDay": 1426674000000 // 10:20, 18 March 2015. If the current time is between 10:20 p.m., 17 Mar. 2015, and 10:20 p.m., 18 Mar. 2015, live traffic speeds are referenced in the analysis; otherwise, typical traffic speeds are referenced.

timeZoneForTimeOfDay

Specify the time zone or zones of the timeOfDay parameter. There are two options: GeoLocal (default) and UTC.

GeoLocal:

The timeOfDay value refers to the time zone in which the analysisLayer points are located.

GeoLocal example:

• timeOfDay set to 9:00 a.m., 4 January 1990 (631443600000 milliseconds)
• timeZoneForTimeOfDay set to GeoLocal

Submitting a valid request causes the drive times for points in the eastern time zone to start at 9:00 a.m. (2:00 p.m. UTC).

UTC:

The timeOfDay value refers to coordinated universal time (UTC).

UTC example:

• timeOfDay set to 9:00 a.m., 4 January 1990 (631443600000 milliseconds)
• timeZoneForTimeOfDay set to UTC

The start time for points in the eastern time zone is 4:00 a.m. eastern time (9:00 a.m. UTC).

Values: GeoLocal | UTC

polygonDetail

Specifies the level of detail that will be used for the output drive-time polygons.

Values: Standard | Generalized | High

The default is Standard.

Example: "polygonDetail": "Standard"

minimumStep

The minimum increment distance or time—for example, 1 mile or 1 minute—used between iterations to expand until the threshold is reached. The units will be dependent on the distanceUnits parameter that is used.

The default is null.

Example: "minimumStep": 1

targetPercentDifference

The maximum difference between the target value and threshold value when determining the threshold drive time—for example, 5 percent.

The default is 5.

Example: "targetPercentDifference": 5

outputName

If provided, the task will create a feature service of the results. You define the name of the service. If an outputName value is not provided, the task will return a feature collection.

Syntax:

1
2
3
4
5
{
  "serviceProperties": {
    "name": "<service name>"
  }
}

In ArcGIS Online or ArcGIS Enterprise 10.9.1 and later, you can overwrite an existing feature service by providing the itemId value of the existing feature service and setting the overwrite property to true. Including the serviceProperties parameter is optional. As described in the Feature output topic, you must either be the owner of the feature service or have administrative privileges to perform the overwrite.

Syntax:

1
2
3
4
5
6
7
{

  "itemProperties": {
			"itemId": "<itemID of the existing feature service>",
			"overwrite": true
	}
}

or

1
2
3
4
5
6
7
8
9
{
"serviceProperties": {
    "name": "<existing service name>"
  },
"itemProperties": {
				"itemId": "<itemID of the existing feature service>",
				"overwrite": true
	}
}

context

Context contains additional settings that affect task execution.

1. Extent (extent)—A bounding box that defines the analysis area.
2. Output spatial reference (outSR):

• If the output is a feature service, the spatial reference will be the same as inputLayer. Setting outSR for feature services has no effect.
• If the output is a feature collection, the features will be in the spatial reference of the outSRvalue or the spatial reference of inputLayer when outSR is not specified.

Syntax:

1
2
3
4
{
"extent" : {extent}
"outSR" : {spatial reference}
}

useData

Defines the country and hierarchy to be used for the threshold variable.

Example: {"sourceCountry":"US", "hierarchy":"census"}

resultLayer

The result layer.

The default is null.

thresholdLayer

The output layer containing the threshold features. Features are copied from the thresholdLayer to this output layer.

Example:

1
{"url":"http://<analysis url>/CreateThresholdAreas/jobs/<jobId>/results/thresholdLayer"}

The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter provided in the initial request.

• If outputName was provided, value contains the URL to the feature service layer.

1
2
3
4
5
{
"paramName":"thresholdLayer",
"dataType":"GPString",
"value":{"url":"<hosted featureservice layer url>"}
}

• If outputName was not provided, value contains a feature collection.

1
2
3
4
5
{
"paramName": "thresholdLayer",
"dataType": "GPString",
"value":{"layerDefinition": {}, "featureSet": {}}
}

See Feature output for more information about how the result layer or collection is accessed.

createThresholdLayer

The output layer containing the lines connecting the analysis features to the threshold features.

Example:

1
{"url":"http://<analysis url>/CreateThresholdAreas/jobs/<jobId>/results/createThresholdLayer"}

The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter provided in the initial request.

• If outputName was provided, value contains the URL to the feature service layer.

1
2
3
4
5
{
"paramName":"createThresholdLayer",
"dataType":"GPString",
"value":{"url":"<hosted featureservice layer url>"}
}

• If outputName was not provided, value contains a feature collection.

1
2
3
4
5
{
"paramName": "createThresholdLayer",
"dataType": "GPString",
"value":{"layerDefinition": {}, "featureSet": {} }
}

See Feature output for more information about how the result layer or collection is accessed.