FRAMES | NO FRAMES
MeasureCannibalization Method

Calculates the amount of overlap between two or more trade areas.

Availability: Business Analyst Server.

TaskResultOutput MeasureCannibalization ( 
    MeasureCannibalizationParameters  Parameters, 
    esriReportFormat                  ReportFormat, 
    RenderingParameters               RenderingParameters, 
    TaskOutputType[]                  OutputTypes, 
    esriFolderItem                    OutputAnalysisItem, 
    esriFolderItem                    OutputReportItem 
);

Parameter Description
Parameters Configuration options for analysis. Type MeasureCannibalizationParameters.
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.
OutputReportItem (Optional parameter — can be null).
Configuration options for storing the output report in the repository. This will enable viewing and working with the output result in subsequent tasks. Type esriFolderItem.

Returns

Variable of type TaskResultOutput

Remarks

The MeasureCannibalization method calculates the amount of overlap between trade areas of a trade area layer linked with different store locations. This overlap refers to the extent at which trade area boundaries coincide. The report will show the amount of overlap in the trade areas. For example, you could create drive-time trade area around an existing network of stores and a proposed new store location. The Measure Cannibalization report will analyze the amount the new store will cannibalize the existing store network. This method can be used to examine the amount of influence a new competitor will have in a given market.

The illustration below is an example of the output for this method. The green shaded polygon represents the area the two yellow shaded polygons are cannibalizing each other.

The cannibalization of market areas is derived by comparing the sizes of the market areas as well as the extent of the overlap.

You can use the output polygon from the MeasureCannibalization method to determine the demographic information for the area of overlap between trade areas.

Usage Tips

Examples

The example below generates a report describing the cannibalized trade areas of 3 stores. Also, the original trade/study areas and the cannibalized areas are generated and saved to 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
 
// 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 boundary layer with simple rings around 3 stores
 
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 an 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[] { 3 };
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_MeasureCannibalization";
outputLayer.projectName = "Default Project";
outputLayer.workspaceName = "Default Workspace";
 
TaskResultOutput simpleRingsResult =
    baServerHelper.SimpleRings(simpleRingsParameters, imageOptions, outputOptions, outputLayer, outputReport);
 
DataLayer boundaryLayer = new DataLayer();
boundaryLayer.RecordSet = simpleRingsResult.RecordSet;
 
// ========= STEP 2: Execute the analysis
 
MeasureCannibalizationParameters parameters = new MeasureCannibalizationParameters();
 
// Set specific analysis parameters
parameters.AreaIDField = "AREA_ID";
parameters.AreaNameField = "AREA_DESC";
parameters.Boundaries = boundaryLayer;
 
// Set report options
ReportOptions reportOptions = new ReportOptions();
reportOptions.ReportFormat = "PDF";
reportOptions.ReportHeader = new KeyValue[1];
reportOptions.ReportHeader[0] = new KeyValue();
reportOptions.ReportHeader[0].Key = "subtitle";
reportOptions.ReportHeader[0].Value = "Measure Cannibalization Report for simple rings around 3 stores";
parameters.StandardReportOptions = reportOptions;
 
// 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 = "cannibalizedAreas_MeasureCannibalization";
outputLayer.projectName = "Default Project";
outputLayer.workspaceName = "Default Workspace";
 
TaskResultOutput result =
    baServerHelper.MeasureCannibalization(parameters, imageOptions, outputOptions, outputLayer, outputReport);
 
string reportURL = result.Reports[0].ReportURL;

See Also