The Create Threshold Areas task creates rings or drive-time areas based on the value for a threshold variable such as population, income, or any demographic variable.
It can help you answer questions such as the following:
- How far do I need to travel to reach a population of 500,000?
- How large of a drive time is needed to encompass an annual budget expenditure of $100,000,000?
- How are our stores performing in relation to the number of potential customers?
Note:
Currently, only online services are supported.
Licensing
As described in the Get Started topic, to use any analysis task, the administrator of the organization needs to grant you certain basic privileges. To use the Create Threshold Areas task, you need to be granted GeoEnrichment permissions. In addition, to create threshold areas based on one of the available travel modes, you need to access to Network Analysis.
Request URL
http://<analysis url>/CreateThresholdAreas/submitJob
Request parameters
Parameter | Details |
---|---|
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:
Examples:
|
idField (Required) | A field on the inputLayer that uniquely identifies each output threshold feature as an attribute. Example:
|
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:
|
thresholdValues | An array of double values representing the threshold values. Example:
|
thresholdExpression | An Arcade expression used for defining the threshold values. Example:
|
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. Example:
|
distanceUnits | The units of the distanceType parameter. Example:
|
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:
|
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:
|
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:
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:
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). Note:Although the dates representing days of the week are from 1990, typical traffic is calculated from recent traffic trends—usually over the last several months. 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. Note:
Syntax: The number of milliseconds since the Unix epoch (January 1, 1970). Examples:
|
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:
UTC: The timeOfDay value refers to coordinated universal time (UTC). UTC example:
Note:All points in analysisLayer need to be in the same time zone when using traffic. 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:
|
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:
|
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:
|
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: Syntax: |
context | Context contains additional settings that affect task execution.
|
useData | Defines the country and hierarchy to be used for the threshold variable. Example:
|
resultLayer | The result layer. The default is null. |
Response
When you submit a request, the service assigns a unique job ID for the transaction.
{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}
After the initial
request is submitted, you can use the
jobId to periodically check the status of the job and messages as described in the Checking job status topic.
Once the job has successfully completed, use
the jobId to retrieve the results. To track the status, you can make a request:http://<analysis url>/CreateThresholdAreas/jobs/<jobId>
Accessing results
When the status of the job request is esriJobSucceeded, you can access the results of the analysis by making a request of the following form: http://<analysis url>/CreateThresholdAreas/jobs/<jobId>/results/thresholdArea?token=<your token>&f=json
Parameter | Description |
---|---|
thresholdLayer | The output layer containing the threshold features. Features are copied from the thresholdLayer to this output layer. 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.
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. 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.
See Feature output for more information about how the result layer or collection is accessed. |