Generate Customer Derived Trade Areas (Business Analyst)

Available with Business Analyst license.

Summary

Creates trade areas around stores based on the number of customers or volume attribute of each customer.

Illustration

Customer-derived trade area

Usage

  • The spatial reference of the output feature class will be the same as the store layer.

  • Stores and Customers must both be point features.

  • Valid numeric values must be used when identifying a volumetric field to be used as a weighted value.

  • The trade area boundaries can be set to expand outward until encompassing user-prescribed customer counts, or summed and weighted numeric values, such as sales.

  • Store-to-customer assignments are controlled during setup by way of a common, user-specified ID.

Syntax

arcpy.ba.CustomerDerivedTA(in_stores_layer, store_id_field, in_customers_layer, link_field, out_feature_class, method, rings, customer_aggregation_type, {customer_weight_field}, {exclude_outlying_customers}, {cutoff_distance}, {dissolve_option}, {use_customer_centroids}, {distance_type}, {units}, {travel_direction}, {time_of_day}, {time_zone}, {search_tolerance}, {polygon_detail}, {iterations_limit}, {minimum_step}, {target_percent_diff})
ParameterExplanationData Type
in_stores_layer

Input point layer representing store or facility locations.

Feature Layer
store_id_field

Unique ID representing a store or facility location.

Field
in_customers_layer

Input point layer representing customers or patrons.

Feature Layer
link_field

An ID used to assign individual customers to stores.

Field
out_feature_class

The output trade area feature class.

Feature Class
method

Specifies the type of customer-derived trade area to be generated.

  • SIMPLECreates a generalized trade area based on the percentages of customers corresponding to each store.
  • AMOEBAConnects points representing the boundary of the polygon trade area using natural curvature.
  • DETAILEDConnects points representing the boundary of the polygon trade area using straight lines.
  • DETAILED_WITH_SMOOTHINGConnects points representing the boundary of the polygon trade area with smoothed curves using cubic splines. This approach takes into account the shape and pattern of the customer distributions. This is the default.
  • THRESHOLD_RINGS Creates concentric rings that expand outward from input stores until they contain the specified threshold of customers.
  • THRESHOLD_DRIVETIMESCreates polygons that expand outward from stores, along network routes, until they contain the specified threshold of customers.
String
rings
[rings,...]

One or more values representing the percentage of customers—for example, total count or a customer attribute and total sales assigned to each store. Each value represents one trade area polygon.

Double
customer_aggregation_type

Specifies the type of aggregation.

  • COUNTCalculates percentage-based trade areas using the geographic locations of customers. This is the default.
  • WEIGHTCalculates percentage-based trade areas using a customer attribute—for example, sales.
String
customer_weight_field
(Optional)

The field used to calculate the trade areas. This is based on either the number of customers (count) or the calculated weighted value assigned to each customer.

Field
exclude_outlying_customers
(Optional)

Specifies whether to exclude outlying customers from the trade area creation process.

  • EXCLUDE_OUTLIERSOutlying customers will be excluded.
  • ALL_POINTSAll customers will be considered. This is the default.
Boolean
cutoff_distance
(Optional)

The distance beyond which customers will be considered outliers, and therefore excluded from consideration during trade area creation.

Linear Unit
dissolve_option
(Optional)

Specifies whether to create polygons of the entire area or split the polygons into individual features.

  • OVERLAP Creates output polygons where each feature begins at zero and grows to satisfy the desired percentage of customers. For example, if you request a trade area of 50 percent and 70 percent of your customers, one polygon will be generated to include 0 to 50 percent and a second polygon will include all 0 to 70 percent of customers. This is the default.
  • SPLIT Creates output polygons for individual features based on the requested percentage breaks. For example, if you request a trade area of 50 percent and 70 percent of your customers, one polygon will be generated to include 0 to 50 percent and a second polygon will include 50 to 70 percent of customers.
String
use_customer_centroids
(Optional)

Specifies the center of your customer area and calculates trade areas outward from this point.

  • USE_CENTROIDSThe centroid of customer points is used to calculate trade areas.
  • USE_STORESThe store location is used as the starting point to calculate trade areas. This is the default.
Boolean
distance_type
(Optional)

Specifies how the distance is calculated based on method of travel.

String
units
(Optional)

The units that will be used for the distance values.

String
travel_direction
(Optional)

Specifies the direction of travel that will be used between stores and customers.

  • TOWARD_STORESThe direction of travel will be from customers to stores. This is the default.
  • AWAY_FROM_STORESThe direction of travel will be from stores to customers.
String
time_of_day
(Optional)

The time and date that will be used when calculating distance.

Date
time_zone
(Optional)

Specifies the time zone that will be used for the Time of Day parameter.

  • TIME_ZONE_AT_LOCATIONThe time zone in which the territories are located will be used. This is the default.
  • UTCCoordinated universal time (UTC) will be used.
String
search_tolerance
(Optional)

The maximum distance that input points can be from the network. Points located beyond the search tolerance will be excluded from processing.

The parameter requires a distance value and units for the tolerance.

Linear Unit
polygon_detail
(Optional)

Specifies the level of detail that will be used for the output drive-time polygons.

  • STANDARD Polygons with a standard level of detail will be created. This is the default.
  • GENERALIZEDGeneralized polygons will be created using the hierarchy present in the network data source to produce results quickly.
  • HIGH Polygons with a high level of detail will be created for applications in which precise results are important.
String
iterations_limit
(Optional)

Restrict the number of drive times used to find the optimal threshold limit.

Long
minimum_step
(Optional)

The minimum increment distance or time—for example, 1 mile or 1 minute, used between iterations to expand until the threshold is reached.

Double
target_percent_diff
(Optional)

The maximum difference between the target value and threshold value when determining the threshold drive time—for example, 5%. The default value is 5.

Double

Code sample

CustomerDerivedTA example (Python window)

The following Python window script demonstrates how to use the CustomerDerivedTA tool.

import arcpy
arcpy.ba.CustomerDerivedTA("Facilities", "ID", "Customers", "ID",r"C:\Temp\Output.gdb\TradeArea75pct","DETAILED_WITH_SMOOTHING", [75], "COUNT", None,"ALL_POINTS", None, "OVERLAP", "USE_STORES", '', '',"TOWARD_STORES", None, "TIME_ZONE_AT_LOCATION", None,"STANDARD", 10, None, 5)

Licensing information

  • Basic: Requires Business Analyst
  • Standard: Requires Business Analyst
  • Advanced: Requires Business Analyst

Related topics