B U S I N E S S A N A L Y S T 10.5 R E S T A N A L Y S I S T A S K
Desire Lines Endpoint
Creates desire lines (spider diagrams) drawn from every customer to an associated store location.
Availability: Business Analyst Server.
URL Example
http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/DesireLines/execute
Specific Parameters
Parameter |
Description |
|---|---|
CustomerLinkField (required) |
The attribute field in the input Customers layer which links every customer with an associated store/business ID. Type string. |
Customers (required) |
A point layer containing point features which represent the locations of customers. Type PointLayer. |
CalculationMethod (required) |
Distance calculation method. Type esriDistanceCalcType. |
DistanceUnits (required) |
The distance units in which the distance to an associated store is calculated and saved in attributes of the output feature layer for every desire line. If the calculation method is the drive time, this property is ignored and the drive time is calculated in minutes. Type esriUnits. |
Stores (required) |
A point layer containing point features such as businesses, hospitals, schools, etc. Type PointLayer. |
AnalysisExtent (optional) |
Data extent to restrict the analysis. Type ExtentData. |
CutOffDistance (optional) |
Cut off threshold distance in the units specified in the CutOffDistance property. Type double. |
CutOffUnits (optional) |
The distance units of the CutOffDistance property which is used to calculate the cut off distance. Type esriUnits. Default: esriMiles. |
SingleStoreID (optional) |
ID of a single store to calculate desire lines. 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) 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, 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
Desire lines, or spider diagrams, are a series of rays drawn from each customer to the associated store location.
The analysis can be restricted to an analysis extent if the AnalysisExtent parameter is specified. Optional SingleStoreID parameter restricts the analysis to a single store of the store layer.
There are three ways to generate desire lines specified with the CalculationMethod parameter:
• Euclidean or straight-line distance
• Drive time
• Drive distance
The distance from a customer to an associated store is written to the output feature layer in the "DISTANCE" field for every desire line. This distance is calculated in units specified by the DistanceUnits parameter. If drive-time desire lines are calculated, the distance is calculated in minutes.
If the CutOffDistance parameter is specified, the customers out of this straight-line distance from associated stores are excluded from the analysis. The CutOffUnits parameter should specify the cut-off distance units in this case.
Desire lines can be used in following cases:
• A lawn and garden operation uses desire lines to adjust advertising expenditures by visualizing the greater draw toward expanding suburbs and a more limited reach towards the inner city. New locations are assigned accordingly.
• A national home improvement and builder supply operation maps weekday and weekend desire lines to better understand variations in these market segments.
• A convenience store and gas chain creates desire lines based on the Affinity card data to examine the impact of new, suburban locations on older, highway-oriented stores. Older, marginal operations are closed when excessive cannibalization can be seen.
• A multi-store dry cleaning and laundry operation uses customer addresses and the time of day, going to work versus travelling to home, to visualize customer travel patterns.
• Large supermarket chains use desire lines weighted by sales to analyze the effect of distance on expenditures per visit.
• A retailer uses desire lines to identify weekday versus weekend shoppers. The resulting analysis can be used to identify consumer behavior and shopping patterns. For example, weekday shoppers travel less distance than weekend shoppers.
Usage Tips
• In most cases, the input store and customer layers will be Business Analyst layers.
• The store and customer layers must be point layers.
• Creating desire lines using drive time and drive distance will take significantly longer than using the straight-line (Euclidean) distance method.
• Use the Assign Customers by Closest Store or Assign Customers by Trade Area endpoints if your customers are not assigned to a store location.
Example Usage
The example below generates desire lines between a list of stores and a list of customers associated with each store. Also, the desire lines analysis result layer is saved to the repository.
Response
{
"results": [
{
"paramName": "RecordSet",
"dataType": "GPFeatureRecordSetLayer",
"value": {
"displayFieldName": "",
"fieldAliases": {
"FID": "FID",
"Latitude": "Latitude",
"Longitude": "Longitude",
"STORE_ID": "STORE_ID",
"NAME": "NAME",
"DESCR": "DESCR",
"STORE_ADDR": "STORE_ADDR",
"Distance": "Distance"
},
"geometryType": "esriGeometryPolyline",
"spatialReference": {
"wkid": 102100,
"latestWkid": 3857
},
"fields": [
{
"name": "FID",
"type": "esriFieldTypeOID",
"alias": "FID"
},
{
"name": "Latitude",
"type": "esriFieldTypeDouble",
"alias": "Latitude"
},
{
"name": "Longitude",
"type": "esriFieldTypeDouble",
"alias": "Longitude"
},
{
"name": "STORE_ID",
"type": "esriFieldTypeString",
"alias": "STORE_ID",
"length": 254
},
{
"name": "NAME",
"type": "esriFieldTypeString",
"alias": "NAME",
"length": 254
},
{
"name": "DESCR",
"type": "esriFieldTypeString",
"alias": "DESCR",
"length": 254
},
{
"name": "STORE_ADDR",
"type": "esriFieldTypeString",
"alias": "STORE_ADDR",
"length": 254
},
{
"name": "Distance",
"type": "esriFieldTypeDouble",
"alias": "Distance"
}
],
"features": [
{
"attributes": {
"FID": 0,
"Latitude": 37.777000000000001,
"Longitude": -122.465,
"STORE_ID": "1",
"NAME": "Alex Kaepersmith",
"DESCR": "Customer of Store 1",
"STORE_ADDR": " ",
"Distance": 1.4101948843200001
},
"geometry": {
"paths": [
[
[
-13632897.28728536,
4550841.812505329
],
[
-13632741.439998249,
4547971.1125883218
]
]
]
}
},
{
"attributes": {
"FID": 1,
"Latitude": 37.779000000000003,
"Longitude": -122.447,
"STORE_ID": "1",
"NAME": "Olga Meyers",
"DESCR": "Customer of Store 1",
"STORE_ADDR": " ",
"Distance": 1.65373900491
},
"geometry": {
"paths": [
[
[
-13632897.28728536,
4550841.812505329
],
[
-13630737.68916397,
4548252.7949210051
]
]
]
}
},
{
"attributes": {
"FID": 2,
"Latitude": 37.787999999999997,
"Longitude": -122.435,
"STORE_ID": "2",
"NAME": "Tim Jones",
"DESCR": "Customer of Store 2",
"STORE_ADDR": " ",
"Distance": 0.95037572490599997
},
"geometry": {
"paths": [
[
[
-13630849.231293743,
4550808.7062027892
],
[
-13629401.855274448,
4549520.4597420003
]
]
]
}
}
]
}
}
],
"messages": [
]
}
See Also