B U S I N E S S A N A L Y S T 10.1 R E S T C U S T O M E R / S T O R E S E T U P T A S K
Assign Customers by Trade Area Endpoint
Assigns customers to stores by using existing trade areas.
Availability: Business Analyst Server.
URL Example
http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/AssignCustomersByTradeArea/execute
Specific Parameters
Parameter |
Description |
|---|---|
Boundaries (required) |
The polygon layer that will be used to assign customers to areas. This boundary layer is usually a Business Analyst trade area layer. Type DataLayer. |
CustomerLinkField (required) |
The name of field in the Customers layer to be used for assignment customers with stores. Type string. |
Customers (required) |
The customer layer used to make the customers assignment to stores. Type PointLayer. |
AnalysisExtent (optional) |
Data extent to restrict the analysis. Type ExtentData. |
StoreIDField (optional) |
The attribute field name in the Boundaries 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) and/or creating a feature layer for subsequent analysis (GetFeatureClass). Type array of TaskOutputType. |
ActiveDatasetID (optional) |
ID of the active dataset. Type string. Default: ID of the first available dataset. |
f (optional) |
Response format. Type string. Available formats: HTML, JSON, PJSON, 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. |
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. |
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
For most Business Analyst Server analyses you need to assign customers contained in the customer datasets either to stores or to trade areas. In most cases, you may find it more useful to assign customers to trade areas instead of particular stores. This endpoint assigns customers to stores by using existing trade areas.
The analysis can be restricted to an analysis extent if the AnalysisExtent parameter is specified.
It is usually preferable to use customer data to create your own trade areas. Business Analyst Server has four different endpoints to create trade areas using customer data:
• Customer-derived areas create trade areas based on where your customers reside.
• Market penetration areas compare the number of customers you have within a geographic area with the total population in that area.
• Trade Area Penetration area compares the number of customers within a trade area to a base value, such as total households.
• Distance decay areas calculate the market penetration values for a number of ring or drive time areas around your stores. The Distance Decay report illustrates how far your customers are traveling to a store compared with a base value such as the population or households.
Usage Tips
• You cannot undo the assignment of customers to stores in an existing field.
• Any customers that do not fall inside a trade area will not be assigned to a store.
• If any of the trade areas are overlapping, you can remove trade area overlap before executing this function.
• You can remove trade area overlap using the Remove Overlap endpoint.
How Does it Work
This method assigns customers to stores by using existing trade areas. You can assign your customers to a store based on any polygon layer. In most cases, the polygon layer will be a Business Analyst trade area (for example simple ring, drive time). Each trade area has a store ID associated with it. The function assigns that store ID to all the customers that fall within the trade area.
The image below illustrates how the assignment works. All the customer points (purple dots) that are within the yellow shaded trade area will inherit the store ID of the trade area. Any customers that do not fall inside a trade area will not be assigned to the store.
If any of the trade areas are overlapping, you can remove trade area overlap before executing this method. You can remove the trade area overlap using the Remove Overlap endpoint.
For example, if you want to assign customers to their nearest store using drive-time polygons, you can create the drive-time polygons in Business Analyst Server, then remove the overlap. You cannot undo the assignment of customers to stores in an existing field. Be careful not to overwrite an existing field.
Example Usage
The example below assigns three customers to stores as determined by drive-time trade areas.
NOTE: The example uses the "Drive Time Polygons 1" polygon layer already created in the Trade Areas folder of the San Francisco Tutorial Project of the Default Workspace.
Response
{
"results": [
{
"paramName": "RecordSet",
"dataType": "GPFeatureRecordSetLayer",
"value": {
"displayFieldName": "",
"fieldAliases": {
"OBJECTID": "Object ID",
"Latitude": "Latitude",
"Longitude": "Longitude",
"STORE_ID": "STORE_ID",
"NAME": "NAME",
"DESCR": "DESCR",
"STORE_ADDR": "STORE_ADDR"
},
"geometryType": "esriGeometryPoint",
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"fields": [
{
"name": "OBJECTID",
"type": "esriFieldTypeOID",
"alias": "Object ID"
},
{
"name": "Latitude",
"type": "esriFieldTypeDouble",
"alias": "Latitude"
},
{
"name": "Longitude",
"type": "esriFieldTypeDouble",
"alias": "Longitude"
},
{
"name": "STORE_ID",
"type": "esriFieldTypeString",
"alias": "STORE_ID",
"length": 256
},
{
"name": "NAME",
"type": "esriFieldTypeString",
"alias": "NAME",
"length": 256
},
{
"name": "DESCR",
"type": "esriFieldTypeString",
"alias": "DESCR",
"length": 256
},
{
"name": "STORE_ADDR",
"type": "esriFieldTypeString",
"alias": "STORE_ADDR",
"length": 256
}
],
"features": [
{
"attributes": {
"OBJECTID": 1,
"Latitude": 37.733249999999998,
"Longitude": -122.4329,
"STORE_ID": "2",
"NAME": "Customer 2",
"DESCR": "Bosworth and Arlington",
"STORE_ADDR": ""
},
"geometry": {
"x": -122.43289999999999,
"y": 37.733249999999998
}
},
{
"attributes": {
"OBJECTID": 2,
"Latitude": 37.784149999999997,
"Longitude": -122.4346,
"STORE_ID": "2",
"NAME": "Customer 1",
"DESCR": "Steiner St. and Geary Blvd",
"STORE_ADDR": ""
},
"geometry": {
"x": -122.4346,
"y": 37.784149999999997
}
}
]
}
}
],
"messages": [
]
}
NOTE: The response has been abbreviated where "..." is noted.
JSON Response Example Rendered with the ArcGIS API for JavaScript
See Also