FRAMES | NO FRAMES
MarketPenetration Method

Calculates the market penetration based on the customer data within an area.

Availability: Business Analyst Server.

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

Parameter Description
Parameters Configuration options for analysis. Type MarketPenetrationParameters.
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 MarketPenetration method allows you to examine how well you are reaching your market areas. This method can be used to examine the percentage of customers for each area of your boundary layer. The denominator in the percent penetration of customers can be any Business Analyst variable. In most cases, this variable will be total households or total population.

This method provides a measure of how you are performing in each trade area. The example below shows the report generated for three trade areas around store with calculation the market penetration based on sales.

Usage Tips

Examples

The example below generates a Market Penetration report based on a list of customers and ring-based trade areas.

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: Geocode the table of customers
 
RecordSet table = new RecordSet();
 
// Create table fields
string[] fieldNames = new string[] {
    "CUST_ID", "NAME", "ADDRESS", "CITY", "STATE", "ZIP", "STORE_ID", "SALES"
};
table.Fields = new Fields();
table.Fields.FieldArray = new Field[fieldNames.Length];
for (int i = 0; i < fieldNames.Length; i++)
{
    Field field = new Field();
    field.Name = fieldNames[i];
    field.Type = esriFieldType.esriFieldTypeString;
    table.Fields.FieldArray[i] = field;
}
// The last field is numeric
table.Fields.FieldArray[fieldNames.Length - 1].Type = esriFieldType.esriFieldTypeInteger;
 
// Create table records
table.Records = new Record[5];
table.Records[0] = new Record();
table.Records[0].Values = new object[] {
    "101", "CUST1", "2355 Pine St.", "San Francisco", "CA", "94115", "1", 12343
};
table.Records[1] = new Record();
table.Records[1].Values = new object[] {
    "102", "CUST2", "2501 California St.", "San Francisco", "CA", "94115", "1", 10008
};
table.Records[2] = new Record();
table.Records[2].Values = new object[] {
    "103", "CUST3", "563 Ruger St.", "San Francisco", "CA", "94129", "2", 3200
};
table.Records[3] = new Record();
table.Records[3].Values = new object[] {
    "104", "CUST4", "301 Finley Rd.", "San Francisco", "CA", "94129", "2", 15802
};
table.Records[4] = new Record();
table.Records[4].Values = new object[] {
    "105", "CUST5", "614 Balboa St.", "San Francisco", "CA", "94129", "2", 4750
};
 
TableData tableData = new TableData();
tableData.RecordSet = table;
 
// Specify geocode data
GeocodeData geocodeData = new GeocodeData();
geocodeData.Table = tableData;
 
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 customerGeocodeResult =
    baServerHelper.CustomerStoreSetupByGeocodeTable(geocodeParameters, imageOptions, outputOptions, outputLayer);
 
PointLayer customerLayer = new PointLayer();
customerLayer.RecordSet = customerGeocodeResult.RecordSet;
 
// ========= STEP 2: Create a boundary layer with simple rings around a store
 
PointRecord[] storePoints = new PointRecord[1];
 
storePoints[0] = new PointRecord();
storePoints[0].Name = "store_study_site";
storePoints[0].Description = "Store Study Site";
storePoints[0].StoreID = "1";
storePoints[0].Latitude = 37.787;
storePoints[0].Longitude = -122.45;
 
// 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[] { 0.2, 0.4, 0.6, 0.8, 1.0, 1.2, 1.4, 1.6, 1.8, 2.0 };
simpleRingsParameters.SingleStoreID = "1";
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 };
outputLayer = null;
outputReport = null;
 
TaskResultOutput simpleRingsResult =
    baServerHelper.SimpleRings(simpleRingsParameters, imageOptions, outputOptions, outputLayer, outputReport);
 
DataLayer boundaryLaeyr = new DataLayer();
boundaryLaeyr.RecordSet = simpleRingsResult.RecordSet;
 
// ========= STEP 3: Execute the analysis
 
MarketPenetrationParameters parameters = new MarketPenetrationParameters();
 
// Set specific analysis parameters
parameters.AreaDescField = "AREA_DESC";
parameters.AreaIDField = "AREA_ID";
parameters.Boundaries = boundaryLaeyr;
parameters.CustomerLinkField = "STORE_ID";
parameters.Customers = customerLayer;
parameters.CustomerWeightField = "SALES";
parameters.ReportOrientation = esriReportOrientation.esriReportOrientationPortrait;
parameters.StoreIDField = "STORE_ID";
parameters.TotalMarketCountField = "TOTPOP_CY";
parameters.UseGeographyLevel = true;
 
// 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 = "Market Penetration Report for 10 rings around a store";
parameters.StandardReportOptions = reportOptions;
 
// Set other parameters
imageOptions = null;
outputOptions = new TaskOutputType[] { TaskOutputType.GetFeatureClass, TaskOutputType.GetReport };
outputLayer = null;
outputReport = null;
 
TaskResultOutput result =
    baServerHelper.MarketPenetration(parameters, imageOptions, outputOptions, outputLayer, outputReport);
 
string reportURL = result.Reports[0].ReportURL;

See Also