B U S I N E S S A N A L Y S T 10.5 R E S T T R A D E A R E A T A S K
Threshold Rings Endpoint
Creates rings around stores. The radii of the rings are determined by expanding out from the store location until they meet the given criteria.
Availability: Business Analyst Server.
URL Example
http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/ThresholdRings/execute
Specific Parameters
Parameter |
Description |
|---|---|
Radii (required) |
Array of threshold values, in ascending size. Type array of double. |
Stores (required) |
A point layer containing point features such as businesses, hospitals, schools, etc. which represent the locations from which the drive time trade/service areas will originate. Type PointLayer. |
SummarizationField (required) |
The attribute field name in the input ThresholdData layer which specifies a demographic field to be used for summarization. Type string. |
ThresholdData (required) |
A point or polygon layer containing demography data. Type DataLayer. |
AnalysisExtent (optional) |
Data extent to restrict the analysis. Type ExtentData. |
Donut (optional) |
An option specifying creation of donut-style areas instead of areas that all originate from the store/business point origins. Type boolean. Default: false. |
SingleStoreID (optional) |
ID of a single store in the Stores layer to generate threshold ring areas. Type string. |
StoreIDField (optional) |
The attribute field name in the input Stores layer which is associated with unique store/business IDs (typically store numbers for retail establishments with multiple locations). Type string. Default: STORE_ID. |
Other Parameters
Parameter |
Description |
|---|---|
OutputType (required) |
Array of task output options. Options for this endpoint include rendering an output image (GetMapImage), creating a feature layer for subsequent analysis (GetFeatureClass), and creating a report (GetReport). Type array of TaskOutputType. |
ActiveDatasetID (optional) |
ID of the active dataset. Type string. Default: ID of the first available dataset. |
DataHierarchy (optional) |
Name of a hierarchy of data layers used for generating summary reports. Type string. Use the Get Data Hierarchies lookup operation to query available geography hierarchies. Default: Standard Business Analyst Data. |
f (optional) |
Response format. Type string. Available formats: HTML, JSON, XML. Default: HTML. |
IsFullErrorMessage (optional) |
Mode for composing error messages. Type boolean. Default: false. |
OutputAnalysisItem (optional) |
Configuration options for storing the output feature layer in the repository. This will enable viewing and working with the output result in subsequent tasks. Type esriFolderItem. |
OutputReportItems (optional) |
Array of configuration options for storing the output reports in the repository. This will enable viewing and working with the output results in subsequent tasks. Type array of esriFolderItem. |
OutputSpatialReference (optional) |
An option specifying the spatial reference to return the output feature layer. Type SpatialReference. If this parameter is missing, the output record set will be returned in the default spatial reference. See Get Default Spatial Reference lookup operation to query the default spatial reference. |
RenderingParameters (optional) |
Configuration options for rendering output when GetMapImage option is specified in the OutputType parameter. Type RenderingParameters. |
ReportOptions (optional) |
Array specifying summary reports that will be generated using trade/service areas as boundary areas for analysis. Use the Get Report Templates lookup operation to query available report templates. Type array of ReportOptions. |
ReturnGeometry (optional) |
An option specifying the presence of the shape attribute in the returned record set. Type boolean. Default: true. |
token |
Authentication token. This parameter is required if your Business Analyst Server is secured. Type string. |
Returns
Variable of type TaskResultOutput
Remarks
The Threshold Rings endpoint creates ring-based trade areas that expand out from the store locations until they meet a specified criteria. You define the criteria, or size of each ring, manually.
The analysis can be restricted to an analysis extent if the AnalysisExtent parameter is specified. The optional SingleStoreID parameter restricts the analysis to a single store of the store layer.
NOTE 1: Since Business Analyst Server 10.0, the SummaryDataLayerID parameter is replaced with an optional DataHierarchy parameter.
NOTE 2: Since Business Analyst Server 10.0, the OutputReportItem parameter is replaced with the OutputReportItems parameter which is an array of folder items. The number of items in this array should be equal to the number of items in the ReportOptions array.
How Does it Work
The following is an example of how this endpoint can be used to examine the optimal location for a new community center in a given market. Assume you have several proposed community center locations in San Diego, California. To create threshold rings for each location, you would set the community center point layer as the store layer. You would then set the threshold data to a standard geographic layer. You can set the field to aggregate to total households and create the ring-based trade areas based on the values you set in the radii parameter.
Each ring created will have the same number of households but will be of different sizes. This endpoint provides an excellent visual indicator of how far each community center will have to draw the same number of households. A city may want to optimize the location of a new community center by finding the location that will minimize how far people will have to travel to a facility. This same logic can be applied to a retail business scenario.
Because the radii is the same for each store, this method is good for comparing the trade areas of similar stores.
This endpoint is typically used to create radius trade areas for competitors so a store owner can see if a store is being cannibalized by the competition. It can also be used to look for gaps in the market area.
Usage Tips
• The spatial reference of the output feature layer will be the same as the store layer.
• The input store layer must be point layer.
• In most cases, the input store layer will be a Business Analyst store layer.
• Valid numeric units must be used when defining radii values. Negative values cannot be used for threshold radii.
• The threshold data layer must be a point or polygon feature layer and be set up as a Business Analyst Dataset (BDS) layer. In most cases, you should select the block group or block points layer.
Example Usage
The example below demonstrates creation of a threshold rings-based trade areas and an associated report from a point layer.
Response
{
"results":
[
{
"paramName":"OutputFeatureClass",
"dataType":"GPFeatureRecordSetLayer",
"value":
{
"geometryType":"esriGeometryPolygon",
"spatialReference":
{
"wkid":4326
},
"fieldAliases":
{
"FID":"FID",
"AREA_ID":"AREA_ID",
"STORE_ID":"STORE_ID",
"RING":"RING",
"RING_DEFN":"RING_DEFN",
"AREA_DESC":"AREA_DESC",
"AREA_DESC2":"AREA_DESC2",
"AREA_DESC3":"AREA_DESC3",
"STORE_LAT":"STORE_LAT",
"STORE_LONG":"STORE_LONG",
"Latitude":"Latitude",
"Longitude":"Longitude",
"NAME":"NAME",
"DESCR":"DESCR",
"STORE_ADDR":"STORE_ADDR"
},
"fields":
[
{
"name":"FID",
"type":"esriFieldTypeOID",
"alias":"FID"
},
...
{
"name":"STORE_ADDR",
"type":"esriFieldTypeString",
"alias":"STORE_ADDR",
"length":254
}
],
"features":
[
{
"geometry":
{
"rings":
[
[
[
-117.195683,
34.0668611833223
],
...
[
-117.195683,
34.0668611833223
]
]
],
"spatialReference":
{
"wkid":4326
}
},
"attributes":
{
"FID":0,
"AREA_ID":"1_2",
"STORE_ID":"1",
"RING":3,
"RING_DEFN":"5000",
"AREA_DESC":"5000",
"AREA_DESC2":"ThresholdRing: 5000 radius",
"AREA_DESC3":"Threshold Rings: 1000, 3000, 5000 radii",
"STORE_LAT":34.057596,
"STORE_LONG":-117.195683,
"Latitude":34.057596,
"Longitude":-117.195683,
"NAME":"store_study_site",
"DESCR":"Store Study Site",
"STORE_ADDR":"Store address"
}
},
...
{
"geometry":
{
"rings":
[
[
[
-117.195683,
34.061852747503
],
...
[
-117.195683,
34.061852747503
]
]
],
"spatialReference":
{
"wkid":4326
}
},
"attributes":
{
"FID":2,
"AREA_ID":"1_0",
"STORE_ID":"1",
"RING":1,
"RING_DEFN":"1000",
"AREA_DESC":"1000",
"AREA_DESC2":"ThresholdRing: 1000 radius",
"AREA_DESC3":"Threshold Rings: 1000, 3000, 5000 radii",
"STORE_LAT":34.057596,
"STORE_LONG":-117.195683,
"Latitude":34.057596,
"Longitude":-117.195683,
"NAME":"store_study_site",
"DESCR":"Store Study Site",
"STORE_ADDR":"Store address"
}
}
]
}
},
{
"paramName":"Age by Sex Profile.PDF",
"dataType":"GPDataFile",
"value":
{
"url":"http://localhost/arcgisoutput/_ags_T100D440D5471CA7DC5A3ADCD40F66.pdf"
}
}
],
"messages":
[
]
}
NOTE: The response has been abbreviated where "..." is noted.
JSON Response Example Rendered with the ArcGIS API for JavaScript
See Also