FRAMES | NO FRAMES
CustomerDerivedAreas Method

Creates trade areas around store features based on percentages of their customers measured in straight-line distance from stores.

Availability: Business Analyst Server.

TaskResultOutput CustomerDerivedAreas ( 
    CustomerDerivedAreasParameters  Parameters, 
    esriReportFormat                ReportFormat, 
    RenderingParameters             RenderingParameters, 
    TaskOutputType[]                OutputTypes, 
    esriFolderItem                  OutputAnalysisItem, 
    esriFolderItem[]                OutputReportItems 
);

Parameter Description
Parameters Configuration options for trade area creation. Type CustomerDerivedAreasParameters.
ReportFormat This parameter should be null. This parameter is deprecated.
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), creating a feature layer for subsequent analysis (GetFeatureClass), and creating a report (GetReport). 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.
OutputReportItems (Optional parameter — can be null).
Array of configuration options for storing the output reports in the repository. This will enable viewing and working with the output result in subsequent tasks. Type esriFolderItem[]. Available with Business Analyst Server 10.0.

Returns

Variable of type TaskResultOutput

Remarks

This method calculates the size and shape of the market area based on your customer points or a numeric field contained within your customer file, such as sales. This method accurately represents each store's actual area of influence, and the detail and extent of the trade area is based on the type of analysis you select.

Business Analyst Server allows you to create 1, 2, or 3 market areas around your store, called primary, secondary, and tertiary markets, respectively. More than three are not often used but are possible with Business Analyst Server.

These market areas can be determined by:

NOTE: Since Business Analyst Server 10.0, the OutputReportItem parameter is replaced with the OutputReportItems parameter which is an array of folder items. The number of items in this array should be equal to the number of items in the ReportOptions array.

How the outline is created

Business Analyst Server creates a boundary around the outermost set of customer points that meet the specified criteria. This is the most accurate method of defining a market area.

There are four types of analyses available when creating customer derived trade areas.

Usage Tips

Examples

The example below generates a study/trade area consisting of regions derived from the spatial distribution of customer locations in a customer layer.

NOTE: The signature of the BAServerHelper.CustomerDerivedAreas method is made compatible with the previous version of this method—the OutputReportItems parameter is specified with the params keyword allowing users to pass output report items in the variable-length list of parameters.

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
 
// You can specify below a domain of your local Business Analyst Server.
//baServerHelper.BAServerDomain = "esri.com";
 
// If a domain name is specified, a local server name in output URLs is replaced with the
// fully-addressable server name so people and machines outside the domain of your local
// Business Analyst Server instance can access these URLs.
 
RenderingParameters imageOptions;
TaskOutputType[] outputOptions;
esriFolderItem outputLayer;
esriFolderItem outputReport;
 
// ========= STEP 1: Create a record set by customer addresses
 
RecordSetByAddress[] customerAddresses = new RecordSetByAddress[7];
 
customerAddresses[0] = new RecordSetByAddress();
customerAddresses[0].Name = "customer1";
customerAddresses[0].Description = "Ocean Beach Customer";
customerAddresses[0].StoreID = "1";
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 = "1";
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 = "1";
customerAddresses[2].Address = "1762 Garnet Ave.";
customerAddresses[2].City = "San Diego";
customerAddresses[2].State = "CA";
customerAddresses[2].ZIP = "92109";
customerAddresses[2].CustomerID = "3";
 
customerAddresses[3] = new RecordSetByAddress();
customerAddresses[3].Name = "customer4";
customerAddresses[3].Description = "Morena Customer";
customerAddresses[3].StoreID = "1";
customerAddresses[3].Address = "1240 W. Morena Blvd.";
customerAddresses[3].City = "San Diego";
customerAddresses[3].State = "CA";
customerAddresses[3].ZIP = "92111";
customerAddresses[3].CustomerID = "4";
 
customerAddresses[4] = new RecordSetByAddress();
customerAddresses[4].Name = "customer5";
customerAddresses[4].Description = "Clairemont Customer";
customerAddresses[4].StoreID = "1";
customerAddresses[4].Address = "6393 Balboa Ave.";
customerAddresses[4].City = "San Diego";
customerAddresses[4].State = "CA";
customerAddresses[4].ZIP = "92111";
customerAddresses[4].CustomerID = "5";
 
customerAddresses[5] = new RecordSetByAddress();
customerAddresses[5].Name = "customer6";
customerAddresses[5].Description = "Bird Rock Customer";
customerAddresses[5].StoreID = "1";
customerAddresses[5].Address = "5735 La Jolla Blvd.";
customerAddresses[5].City = "La Jolla";
customerAddresses[5].State = "CA";
customerAddresses[5].ZIP = "92037";
customerAddresses[5].CustomerID = "6";
 
customerAddresses[6] = new RecordSetByAddress();
customerAddresses[6].Name = "customer7";
customerAddresses[6].Description = "University City Customer";
customerAddresses[6].StoreID = "1";
customerAddresses[6].Address = "3254 Governor Dr.";
customerAddresses[6].City = "San Diego";
customerAddresses[6].State = "CA";
customerAddresses[6].ZIP = "92122";
customerAddresses[6].CustomerID = "7";
 
TaskResultOutput recordSetResult =
    baServerHelper.CreateRecordSetByAddresses(customerAddresses, esriFolderType.esriFolderCustomerLayers);
 
TableData tableData = new TableData();
tableData.RecordSet = recordSetResult.RecordSet;
GeocodeData geocodeData = new GeocodeData();
geocodeData.Table = tableData;
 
// ========= STEP 2: 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 };
 
// 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_CustomerDerivedAreas";
outputLayer.projectName = "Default Project";
outputLayer.workspaceName = "Default Workspace";
 
TaskResultOutput geocodeResult =
    baServerHelper.CustomerStoreSetupByGeocodeTable(geocodeParameters, imageOptions, outputOptions, outputLayer);
 
PointLayer customerLayer = new PointLayer();
customerLayer.RecordSet = geocodeResult.RecordSet;
 
// ========= STEP 3: Execute the analysis
 
// Create a PointRecord array of 1 store location.
PointRecord[] storePoints = new PointRecord[1];
 
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[0].StoreAddress = "3252 Holiday Court";
 
//  Create a store feature layer based on an array of point records.
PointLayer storeLayer = new PointLayer();
storeLayer.Points = storePoints;
 
CustomerDerivedAreasParameters parameters = new CustomerDerivedAreasParameters();
 
// Set specific analysis parameters
parameters.CustomerLinkField = "STORE_ID";
parameters.Customers = customerLayer;
parameters.HullType = esriHullType.Detailed;
parameters.Percentages = new double[] { 50, 80, 100 };
parameters.SingleStoreID = "1";
parameters.Stores = storeLayer;
 
// StoreIDField is useless for stores specified with array of PointRecord
//parameters.StoreIDField = "STORE_ID";
 
// Set summary report parameters
ReportOptions demoReport = new ReportOptions();
demoReport.ReportFormat = "PDF";
demoReport.TemplateName = "Demographic and Income Report";
parameters.ReportOptions = new ReportOptions[] { demoReport };
 
// Set other parameters
imageOptions = null;
outputOptions = new TaskOutputType[] { TaskOutputType.GetFeatureClass, TaskOutputType.GetReport };
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 = "tradeArea_CustomerDerivedAreas";
outputLayer.projectName = "Default Project";
outputLayer.workspaceName = "Default Workspace";
 
TaskResultOutput result =
    baServerHelper.CustomerDerivedAreas(parameters, imageOptions, outputOptions, outputLayer, outputReport);
 
string reportURL = result.Reports[0].ReportURL;

See Also