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
- 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 AssignCustomersByTradeArea method 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.
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]); } |