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 Closest Store Endpoint

Assigns or reassigns customer features to stores using straight-line distance to the closest store feature location.

Availability: Business Analyst Server.

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/AssignCustomersByClosestStore/execute

Specific Parameters

Other Parameters

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. To create customer-derived trade areas around your customers or to create desire lines, your customer data must contain a field that associates each customer with a particular store. A number of analyses in Business Analyst Server require that your customer data has a store assignment field. If you do not have such a field, you can create one using the Assign Customers by Closest Store endpoint. This endpoint assigns customers to the closest store.

Two algorithms for closest store assignment are implemented: direct assignment and assignment based on the creation of Thiessen polygons. The first algorithm compares the straight-line distance from a customer to every store and selects a store with minimal distance from the customer. The last algorithm constructs Thiessen equal-competition polygons around stores and then assigns all customers to stores by their polygons.

The analysis can be restricted to an analysis extent if the AnalysisExtent parameter is specified.

Usage Tips

• You cannot undo the assignment of customers to stores in an existing field.

• Customers are assigned to the closest store location.

• Assignments are based on a straight-line Euclidean distance calculation.

• The UseThiessenPolygons option can essentially improve performance of the assignment if the number of customers is big enough.

• If a customer is at an equal distance from two or more stores, the customer will be assigned to any of these stores.

• Use the Assign Customers by Trade Area endpoint if you do not want to assign customers using a straight-line distance. This method can be used with drive-time polygons.

How Does it Work

This method assigns each customer the ID of the store that is closest, using a straight-line distance. The image below illustrates how these assignments are made. The image has two store locations (yellow and blue squares) and a set of customers (red triangles). In this simplified example, each of the customer points will inherit the store ID of the closest store location.

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 four customers to the nearest of three stores using the straight-line distance calculation algorithm.

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/AssignCustomersByClosestStore/execute?
Stores={"Points":[
  {"longitude":-117.246866,"description":"La Jolla Store","latitude":32.869087,"name":"lj_store","storeID":"1"},
  {"longitude":-117.238426,"description":"Ocean Beach Store","latitude":32.746841,"name":"ob_store","storeID":"2"},
  {"longitude":-117.235344,"description":"Pacific Beach Store","latitude":32.800998,"name":"pb_store","storeID":"3"}
]}&
Customers={"Points":[
  {"name":"jane_smith","latitude":32.74198,"longitude":-117.24996,"storeId":"5","description":"Jane Smith"},
  {"name":"miguel_sanchez","latitude":32.781143,"longitude":-117.235664,"storeId":"5","description":"Miguel Sanchez"},
  {"name":"pam_lee","latitude":32.811494,"longitude":-117.231709,"storeId":"5","description":"Pam Lee"},
  {"name":"byron_jackson","latitude":32.854672,"longitude":-117.204533,"storeId":"5","description":"Byron Jackson"}
]}&
CustomerLinkField=NewStoreID&
ActiveDatasetID=USA_ESRI_2011&
StoreIDField=STORE_ID&
OutputType=GetFeatureClass&
f=PJSON

{
  "results":
  [
    {
      "paramName":"OutputFeatureClass",
      "dataType":"GPFeatureRecordSetLayer",
      "value":
      {
        "geometryType":"esriGeometryPoint",
        "spatialReference":
        {
          "wkid":4326
        },
        "fieldAliases":
        {
          "OBJECTID":"Object ID",
          "Latitude":"Latitude",
          "Longitude":"Longitude",
          "STORE_ID":"STORE_ID",
          "NAME":"NAME",
          "DESCR":"DESCR",
          "STORE_ADDR":"STORE_ADDR",
          "NewStoreID":"NewStoreID"
        },
        "fields":
        [
          {
            "name":"OBJECTID",
            "type":"esriFieldTypeOID",
            "alias":"Object ID"
          },
          ...
          {
            "name":"NewStoreID",
            "type":"esriFieldTypeString",
            "alias":"NewStoreID",
            "length":256
          }
        ],
        "features":
        [
          {
            "geometry":
            {
              "x":-117.24996,
              "y":32.74198,
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "OBJECTID":1,
              "Latitude":32.74198,
              "Longitude":-117.24996,
              "STORE_ID":"5",
              "NAME":"jane_smith",
              "DESCR":"Jane Smith",
              "STORE_ADDR":"",
              "NewStoreID":"2"
            }
          },
          ...
          {
            "geometry":
            {
              "x":-117.204533,
              "y":32.854672,
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "OBJECTID":4,
              "Latitude":32.854672,
              "Longitude":-117.204533,
              "STORE_ID":"5",
              "NAME":"byron_jackson",
              "DESCR":"Byron Jackson",
              "STORE_ADDR":"",
              "NewStoreID":"1"
            }
          }
        ]
      }
    }
  ],
  "messages":
  [
  ]
}

NOTE: The response has been abbreviated where "..." is noted.

JSON Response Example Rendered with the ArcGIS API for JavaScript

See Also

• Assign Customers by Trade Area Endpoint

• Business Analyst Server REST Reference