FRAMES | NO FRAMES
AssignCustomersByTradeArea Method

Assigns customers to stores by using existing trade areas.

Availability: Business Analyst Server.

TaskResultOutput AssignCustomersByTradeArea (
    AssignByTradeAreaParameters  Parameters,
    RenderingParameters          RenderingParameters,
    TaskOutputType[]             OutputTypes,
    esriFolderItem               OutputAnalysisItem
);

Parameter Description
Parameters Configuration options for customers assignment. Type AssignByTradeAreaParameters.
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. In most cases, you may find it more useful to assign customers to trade areas instead of, to particular stores.

It is usually preferable to use customer data to create your own trade areas. Business Analyst Server has four different methods to create trade areas using customer data:

Usage Tips

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 RemoveOverlap method.

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.

Examples

The example below assigns 3 customers to the nearest of 3 stores as determined by ring-based trade areas. Also, the trade area and new customer layers are 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;
esriFolderItem outputReport;
 
// ========= STEP 1: Create simple rings around store points
 
// 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;
 
SimpleRingsParameters simpleRingsParameters = new SimpleRingsParameters();
 
// Set specific analysis parameters
simpleRingsParameters.DistanceUnits = esriUnits.esriMiles;
simpleRingsParameters.Radii = new double[] { 2.5 };
simpleRingsParameters.Stores = storeLayer;
 
// StoreIDField is useless for stores specified with array of PointRecord
//simpleRingsParameters.StoreIDField = "STORE_ID";
 
// Set other parameters
imageOptions = null;
outputOptions = new TaskOutputType[] { TaskOutputType.GetFeatureClass };
outputReport = null;
 
// 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.esriFolderTradeAreas;
outputLayer.itemName = "simpleRings_AssignCustomersByTradeArea";
outputLayer.projectName = "Default Project";
outputLayer.workspaceName = "Default Workspace";
 
TaskResultOutput simpleRingsResult =
    baServerHelper.SimpleRings(simpleRingsParameters, imageOptions, outputOptions, outputLayer, outputReport);
 
// Set the analysis boundary to be the simple rings trade areas.
DataLayer boundaryLayer = new DataLayer();
boundaryLayer.RecordSet = simpleRingsResult.RecordSet;
 
// ========= STEP 2: Create a record set by customer addresses
 
RecordSetByAddress[] customerAddresses = new RecordSetByAddress[3];
 
customerAddresses[0] = new RecordSetByAddress();
customerAddresses[0].Name = "customer1";
customerAddresses[0].Description = "Ocean Beach Customer";
customerAddresses[0].StoreID = "5";
customerAddresses[0].Address = "5080 Newport Ave.";
customerAddresses[0].City = "San Diego";
customerAddresses[0].State = "CA";
customerAddresses[0].ZIP = "92107";
customerAddresses[0].CustomerID = "1";
 
customerAddresses[1] = new RecordSetByAddress();
customerAddresses[1].Name = "customer2";
customerAddresses[1].Description = "La Jolla Customer";
customerAddresses[1].StoreID = "5";
customerAddresses[1].Address = "1250 Prospect St.";
customerAddresses[1].City = "La Jolla";
customerAddresses[1].State = "CA";
customerAddresses[1].ZIP = "92037";
customerAddresses[1].CustomerID = "2";
 
customerAddresses[2] = new RecordSetByAddress();
customerAddresses[2].Name = "customer3";
customerAddresses[2].Description = "Pacific Beach Customer";
customerAddresses[2].StoreID = "5";
customerAddresses[2].Address = "1762 Garnet Ave.";
customerAddresses[2].City = "San Diego";
customerAddresses[2].State = "CA";
customerAddresses[2].ZIP = "92109";
customerAddresses[2].CustomerID = "3";
 
TaskResultOutput recordSetResult =
    baServerHelper.CreateRecordSetByAddresses(customerAddresses, esriFolderType.esriFolderCustomerLayers);
 
TableData tableData = new TableData();
tableData.RecordSet = recordSetResult.RecordSet;
GeocodeData geocodeData = new GeocodeData();
geocodeData.Table = tableData;
 
// ========= STEP 3: Geocode the record set with customers
 
CustomerStoreSetupByGeocodeTableParameters geocodeParameters = new CustomerStoreSetupByGeocodeTableParameters();
 
// Set specific analysis parameters
geocodeParameters.GeocodeCustomers = true;
geocodeParameters.GeocodeData = geocodeData;
geocodeParameters.LinkField = "STORE_ID";
geocodeParameters.NameField = "NAME";
 
// Set other parameters
imageOptions = null;
outputOptions = new TaskOutputType[] { TaskOutputType.GetFeatureClass };
outputLayer = null;
 
TaskResultOutput geocodeResult =
    baServerHelper.CustomerStoreSetupByGeocodeTable(geocodeParameters, imageOptions, outputOptions, outputLayer);
 
PointLayer customerLayer = new PointLayer();
customerLayer.RecordSet = geocodeResult.RecordSet;
 
// ========= STEP 4: Assign customers by 2.5-mile ring trade areas around each of the store features
 
AssignByTradeAreaParameters parameters = new AssignByTradeAreaParameters();
 
// Set specific analysis parameters
parameters.Boundaries = boundaryLayer;
parameters.CreateLinkField = true;
parameters.CustomerLinkField = "NewStoreID";
parameters.Customers = customerLayer;
parameters.StoreIDField = "STORE_ID";
 
// 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 = "assignedCustomers_assignCustomersByTradeArea";
outputLayer.projectName = "Default Project";
outputLayer.workspaceName = "Default Workspace";
 
TaskResultOutput result = baServerHelper.AssignCustomersByTradeArea(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