B U S I N E S S A N A L Y S T 10.5 R E S T R E P O R T T A S K
Market Penetration Endpoint
Calculates the market penetration based on the customer data within an area.
Availability: Business Analyst Server.
URL Example
http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/MarketPenetration/execute
Specific Parameters
Parameter |
Description |
|---|---|
AreaDescField (required) |
Name of area description field in the Boundaries layer. Type string. |
Boundaries (required) |
The polygon layer whose features represent trade areas. Type DataLayer. |
Customers (required) |
A point layer containing point features which represent the locations of customers. Type PointLayer. |
TotalMarketCountField (required) |
Total market count field name. Type string. |
AnalysisExtent (optional) |
Data extent to restrict the analysis. Type ExtentData. |
AreaIDField (optional) |
Name of area ID field in the Boundaries layer. Type string. Default: AREA_ID |
CustomerLinkField (optional) |
The attribute field in the input Customers layer which links every customer with associated store/business ID. Type string. Default: STORE_ID |
CustomerWeightField (optional) |
The weight field in the Customers layer used for calculation a weight rather than number of customers, sales for example. Type string. |
DataHierarchy (optional) |
Name of a hierarchy of data layers used for summarization. Type string. Use the Get Data Hierarchies lookup operation to query available geography hierarchies. Default: Standard Business Analyst Data. |
Multiplier (optional) |
Multiplier of penetration values. Type double. Default: 100. |
ReportOrientation (optional) |
Orientation of the report. Default orientation is the portrait orientation. Type esriReportOrientation. Default: esriReportOrientationPortrait. |
SingleAreaID (optional) |
ID of a single area of the Boundaries layer to calculate market penetration. Type string. |
StoreIDField (optional) |
The attribute field name in the Boundaries layer which links every trade area with associated store/business ID. Type string. Default: STORE_ID. |
UseGeographyLevel (optional) |
An option specifying the use of geography hierarchy for calculation market penetration or not. Type boolean. Default: false. |
Other Parameters
Parameter |
Description |
|---|---|
OutputType (required) |
Array of task output options. Options for this endpoint include rendering an output image (GetMapImage), creating a feature layer for subsequent analysis (GetFeatureClass), and creating a report (GetReport). Type array of TaskOutputType. |
ActiveDatasetID (optional) |
ID of the active dataset. Type string. Default: ID of the first available dataset. |
f (optional) |
Response format. Type string. Available formats: HTML, JSON, XML. Default: HTML. |
IsFullErrorMessage (optional) |
Mode for composing error messages. Type boolean. Default: false. |
OutputAnalysisItem (optional) |
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) |
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. |
OutputSpatialReference (optional) |
An option specifying the spatial reference to return the output feature layer. Type SpatialReference. If this parameter is missing, the output record set will be returned in the default spatial reference. See Get Default Spatial Reference lookup operation to query the default spatial reference. |
RenderingParameters (optional) |
Configuration options for rendering output when GetMapImage option is specified in the OutputType parameter. Type RenderingParameters. |
ReturnGeometry (optional) |
An option specifying the presence of the shape attribute in the returned record set. Type boolean. Default: true. |
StandardReportOptions (optional) |
Report parameters. Type ReportOptions. The TemplateName parameter is ignored. |
token |
Authentication token. This parameter is required if your Business Analyst Server is secured. Type string. |
Returns
Variable of type TaskResultOutput
Remarks
The Market Penetration endpoint 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.
The analysis can be restricted to an analysis extent if the AnalysisExtent parameter is specified. The optional SingleAreaID parameter restricts the analysis to a single area of the boundary layer.
Market penetration options:
• The UseGeographyLevel parameter specifies the use of summarization variables of a geography hierarchy in calculation of market penetration. If this parameter is true, the DataHierarchy value can be specified.
• The TotalMarketCountField parameter specifies the total market count field from summarization variables of the geography hierarchy if the last one is in use or from the store layer.
• The CustomerWeightField parameter can specify a weight field in the customer layer for calculating a weight rather than number of customers. This would be a good example for sales.
NOTE: Since Business Analyst Server 10.0, the DataLayerID parameter is replaced with an optional DataHierarchy parameter.
How Does it Work
This method can be used to examine the percentage of customers for each trade area of your trade area layer. It 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
• The spatial reference of the output feature layer will be the same as the layer for calculating market penetration.
• The boundary layer for calculating market penetration should be a trade area layer.
• The customer layer must be a point feature layer.
• In most cases, the customer layer will be a Business Analyst customer layer.
• When calculating market penetration, the final percentages are a direct result of the number of customers used in the method. If you are comparing the penetration of your customers based on 1,000 customers in a large metropolitan area against the total population, the percentage of market penetration will be very low. These percentages are still a valuable function if taken in consideration of the market you are attempting to penetrate.
• You can optionally calculate market penetration based on a weight field in the customer layer instead of the customer counts. For example, you can calculate penetration based on total sales per household for each ZIP Code.
Example Usage
The example below generates a Market Penetration report based on a list of customers and drive-time trade areas.
NOTE: The example uses the "Drive Time Polygons 1" polygon layer already created in the Trade Areas folder of the San Francisco Tutorial Project of the Default Workspace.
Response
{
"results": [
{
"paramName": "RecordSet",
"dataType": "GPFeatureRecordSetLayer",
"value": {
"displayFieldName": "",
"fieldAliases": {
"OBJECTID": "Object ID",
"AREA_ID": "AREA_ID",
"AREA_DESC": "AREA_DESC",
"STORE_ID": "STORE_ID",
"BA_CUST": "BA_CUST",
"BA_TCUST": "BA_TCUST",
"BA_PCUST": "BA_PCUST",
"BA_CUSTW": "BA_CUSTW",
"BA_TCUSTW": "BA_TCUSTW",
"BA_PCUSTW": "BA_PCUSTW",
"BA_BASEVAL": "BA_BASEVAL",
"BA_MKT_P": "BA_MKT_P"
},
"geometryType": "esriGeometryPolygon",
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"fields": [
{
"name": "OBJECTID",
"type": "esriFieldTypeOID",
"alias": "Object ID"
},
{
"name": "AREA_ID",
"type": "esriFieldTypeString",
"alias": "AREA_ID",
"length": 256
},
{
"name": "AREA_DESC",
"type": "esriFieldTypeString",
"alias": "AREA_DESC",
"length": 256
},
{
"name": "STORE_ID",
"type": "esriFieldTypeString",
"alias": "STORE_ID",
"length": 256
},
{
"name": "BA_CUST",
"type": "esriFieldTypeInteger",
"alias": "BA_CUST"
},
{
"name": "BA_TCUST",
"type": "esriFieldTypeInteger",
"alias": "BA_TCUST"
},
{
"name": "BA_PCUST",
"type": "esriFieldTypeDouble",
"alias": "BA_PCUST"
},
{
"name": "BA_CUSTW",
"type": "esriFieldTypeDouble",
"alias": "BA_CUSTW"
},
{
"name": "BA_TCUSTW",
"type": "esriFieldTypeDouble",
"alias": "BA_TCUSTW"
},
{
"name": "BA_PCUSTW",
"type": "esriFieldTypeDouble",
"alias": "BA_PCUSTW"
},
{
"name": "BA_BASEVAL",
"type": "esriFieldTypeDouble",
"alias": "BA_BASEVAL"
},
{
"name": "BA_MKT_P",
"type": "esriFieldTypeDouble",
"alias": "BA_MKT_P"
}
],
"features": [
{
"attributes": {
"OBJECTID": 1,
"AREA_ID": "1_1",
"AREA_DESC": "0 - 5 Miles",
"STORE_ID": "1",
"BA_CUST": 2,
"BA_TCUST": 2,
"BA_PCUST": 100,
"BA_CUSTW": 0,
"BA_TCUSTW": 0,
"BA_PCUSTW": 0,
"BA_BASEVAL": 1,
"BA_MKT_P": 200
},
"geometry": {
"rings": [
[
[
-122.4346,
37.856647637107599
],
[
-122.36065585891501,
37.826739954428007
],
[
-122.34774970314601,
37.761714833162003
],
[
-122.406398364369,
37.715196713342294
],
[
-122.48825015542499,
37.725485501761895
],
[
-122.525947479981,
37.784114591286993
],
[
-122.488335196333,
37.842789641231093
],
[
-122.4346,
37.856647637107599
]
]
]
}
},
{
"attributes": {
"OBJECTID": 2,
"AREA_ID": "2_1",
"AREA_DESC": "0 - 5 Miles",
"STORE_ID": "2",
"BA_CUST": 2,
"BA_TCUST": 2,
"BA_PCUST": 100,
"BA_CUSTW": 0,
"BA_TCUSTW": 0,
"BA_PCUSTW": 0,
"BA_BASEVAL": 1,
"BA_MKT_P": 200
},
"geometry": {
"rings": [
[
[
-122.43289999999999,
37.805748265065105
],
[
-122.35900658433999,
37.775840365753993
],
[
-122.34610914286401,
37.710814697494598
],
[
-122.404717633044,
37.664296122518394
],
[
-122.48651348554,
37.674585016191301
],
[
-122.524184911958,
37.733214655796402
],
[
-122.486598312884,
37.791890171551003
],
[
-122.43289999999999,
37.805748265065105
]
]
]
}
}
]
}
},
{
"paramName": "Market Penetration.PDF",
"dataType": "GPDataFile",
"value": {
"url": "http://localhost:6080/arcgis/rest/directories/arcgisoutput/DefaultMap_MapServer/_ags_T371945693463EBBF9329135A45C42.pdf"
}
}
],
"messages": [
]
}
JSON Response Example Rendered with the ArcGIS API for JavaScript
See Also