FRAMES | NO FRAMES
AssignCustomersByClosestStore Method

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

Availability: Business Analyst Server.

TaskResultOutput AssignCustomersByClosestStore (
    AssignByClosestStoreParameters  Parameters,
    RenderingParameters             RenderingParameters,
    TaskOutputType[]                OutputTypes,
    esriFolderItem                  OutputAnalysisItem
);

Parameter Description
Parameters Configuration options for customers assignment. Type AssignByClosestStoreParameters.
RenderingParameters Configuration options for rendering output when GetMapImage option is specified in the OutputTypes parameter. Type RenderingParameters.
OutputTypes Array of task output options. Options for this method include rendering output image (GetMapImage) and/or creating a feature layer for subsequent analysis (GetFeatureClass). Type TaskOutputType[].
OutputAnalysisItem (Optional parameter — can be null). 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.

Returns

Variable of type TaskResultOutput

Remarks

Most Business Analyst Server analyses need you 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 AssignCustomersByClosestStore method. This method assigns customers to the closest store.

Usage Tips

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.

Examples

The example below assigns 3 customers to the nearest of 3 stores by straight-line distance. Also, the new customer layer is stored in the repository.

C#
// Instantiate the BAServerHelper class to access analysis methods
BAServerHelper baServerHelper = new BAServerHelper();
baServerHelper.ActiveDatasetID = "USA_ESRI"; // Optional parameter
baServerHelper.IsFullErrorMessage = true;    // Default is false
 
RenderingParameters imageOptions;
TaskOutputType[] outputOptions;
esriFolderItem outputLayer;
 
// Create a PointRecord array of 3 store locations.
PointRecord[] storePoints = new PointRecord[3];
 
storePoints[0] = new PointRecord();
storePoints[0].Name = "lj_store";
storePoints[0].Description = "La Jolla Store";
storePoints[0].StoreID = "1";
storePoints[0].Latitude = 32.869087;
storePoints[0].Longitude = -117.246866;
 
storePoints[1] = new PointRecord();
storePoints[1].Name = "ob_store";
storePoints[1].Description = "Ocean Beach Store";
storePoints[1].StoreID = "2";
storePoints[1].Latitude = 32.746841;
storePoints[1].Longitude = -117.238426;
 
storePoints[2] = new PointRecord();
storePoints[2].Name = "pb_store";
storePoints[2].Description = "Pacific Beach Store";
storePoints[2].StoreID = "3";
storePoints[2].Latitude = 32.800998;
storePoints[2].Longitude = -117.235344;
 
// Create a store feature layer based on the array of point records.
PointLayer storeLayer = new PointLayer();
storeLayer.Points = storePoints;
 
// Create a PointRecord array of 4 customer locations.
// StoreID field is set to the original store assignment.
// This field is not overwritten since a new attribute field will be created.
PointRecord[] customerPoints = new PointRecord[4];
 
customerPoints[0] = new PointRecord();
customerPoints[0].Name = "jane_smith";
customerPoints[0].Description = "Jane Smith";
customerPoints[0].StoreID = "5";
customerPoints[0].Latitude = 32.74198;
customerPoints[0].Longitude = -117.24996;
 
customerPoints[1] = new PointRecord();
customerPoints[1].Name = "miguel_sanchez";
customerPoints[1].Description = "Miguel Sanchez";
customerPoints[1].StoreID = "5";
customerPoints[1].Latitude = 32.781143;
customerPoints[1].Longitude = -117.235664;
 
customerPoints[2] = new PointRecord();
customerPoints[2].Name = "pam_lee";
customerPoints[2].Description = "Pam Lee";
customerPoints[2].StoreID = "5";
customerPoints[2].Latitude = 32.811494;
customerPoints[2].Longitude = -117.231709;
 
customerPoints[3] = new PointRecord();
customerPoints[3].Name = "byron_jackson";
customerPoints[3].Description = "Byron Jackson";
customerPoints[3].StoreID = "5";
customerPoints[3].Latitude = 32.854672;
customerPoints[3].Longitude = -117.204533;
 
// Create a customer feature layer based on the array of point records.
PointLayer customerLayer = new PointLayer();
customerLayer.Points = customerPoints;
 
AssignByClosestStoreParameters parameters = new AssignByClosestStoreParameters();
 
// Set specific analysis parameters
parameters.CreateLinkField = true;
parameters.CustomerLinkField = "NewStoreID";
parameters.Customers = customerLayer;
parameters.StoreIDField = "STORE_ID";
parameters.Stores = storeLayer;
 
// Set other parameters
imageOptions = null;
outputOptions = new TaskOutputType[] { TaskOutputType.GetFeatureClass };
 
// In general, a non-null esriFolderItem is specified to save a newly-created
// item to the server-side repository or to reference an existing item in it.
outputLayer = new esriFolderItem();
outputLayer.folderType = esriFolderType.esriFolderCustomerLayers;
outputLayer.itemName = "customerLayer_AssignCustomersByClosestStore";
outputLayer.projectName = "Default Project";
outputLayer.workspaceName = "Default Workspace";
 
TaskResultOutput result = baServerHelper.AssignCustomersByClosestStore(parameters, imageOptions, outputOptions, outputLayer);
 
// Determine indices of attribute fields
int indexNameField = -1;
int indexStoreIDField = -1;
int indexNewStoreIDField = -1;
Field[] fields = result.RecordSet.Fields.FieldArray;
for (int i = 0; i < fields.Length; i++)
{
    switch (fields[i].Name)
    {
    case "NAME": indexNameField = i; break;
    case "STORE_ID": indexStoreIDField = i; break;
    case "NewStoreID": indexNewStoreIDField = i; break;
    }
}
 
// Save the output values in the recordDescriptions array
Record[] records = result.RecordSet.Records;
string[] recordDescriptions = new string[records.Length];
for (int i = 0; i < records.Length; i++)
{
    Record record = records[i];
    recordDescriptions[i] = string.Format("RECORD: {0}; NAME: {1}; ORIGINAL STORE ID: {2}; NEW STORE ID: {3}",
        i, record.Values[indexNameField], record.Values[indexStoreIDField], record.Values[indexNewStoreIDField]);
}

See Also