Create Territories

Available with Business Analyst license.

Summary

Creates new territories using specified values on a selected territory level.

Usage

• The Territory Level must be of a specific format: Level_Name[Level_Index].

• The Balancing Variables should be specified (via UI or SetupBalancingVariables_td tool) for creating balanced territories.

• A Seed Points layer must be specified when creating territories from locations (with NUMBER_OF_SEED_POINTS value of in_territories_number_option parameter).

• A Names Table must be specified when creating territories (with NUMBER_OF_IMPORTED_NAMES value of in_territories_number_option parameter).

• The Distance constraints (see Maximum Distance, Minimum Distance, and Minimum Distance Between Centers parameters) or Capacity constraints must be specified (via UI or appropriate GP tool) before creating territories (with OPTIMAL_NUMBER value of in_territories_number_option parameter).

• The in_territories_number parameter is used only if the USED_DEFINED value of the in_territories_number_option parameter is specified.

• The Value of the in_territories_number parameter must be greater than zero.

• Density influence can be specified only for the CREATE_FROM_CENTERS_OF_DENSITY value of the in_additional_territories_option parameter. Higher values will result in a territory being placed in a denser area.

• Point, or Multipoint, layers can be used for the Seed Points Layer parameter (in_seed_points).

• The in_name_table and in_name_field parameters must be specified together or omitted together.

Syntax

arcpy.td.CreateTerritories_TD(in_territory_solution_layer, in_level, {in_remove_existing_territories}, {in_territories_number_option}, {in_territories_number}, {in_additional_territories_option}, {in_summary_attribute}, {in_density_influence}, {in_seed_points}, {in_name_table}, {in_name_field}, {in_unique_names}, {in_autofill_extent}, {in_override_constraints})

Parameter	Explanation	Data Type
in_territory_solution_layer	The Territory Solution layer that is used to create territories.	GP TD Layer
in_level	The Territory level.	String
in_remove_existing_territories (Optional)	This option specifies what to do with exiting territories on the selected level. REMOVE_TERRITORIES — Existing territories will be removed and replaced by new territories. LEAVE_TERRITORIES — New territories will be added to existing territories.	Boolean
in_territories_number_option (Optional)	The number of territories to create can be defined automatically or specified by the user. NUMBER_OF_SEED_POINTS —The number of territories will be equal to the number of seed points of a specified Seed Points layer. NUMBER_OF_IMPORTED_TERRITORY_NAMES —The number of territories will be equal to the number of territory names imported from a Name Table. OPTIMAL_NUMBER — The number of territories will automatically be calculated according to settings and constraints of the specified Territory Level. USER_DEFINED —The number of territories to create will be determined by the user using the in_territories_number parameter.	String
in_territories_number (Optional)	The number of territories to create.	Long
in_additional_territories_option (Optional)	This option can be used to build territories around optimally placed virtual centers or around centers of density at the base level. CREATE_FROM_OPTIMAL_LOCATIONS —The territory centers will be placed at locations that are optimal due to the specified options and constraints applied. CREATE_FROM_CENTERS_OF_DENSITY —The territory centers will be placed at the base level centers of density (Alignment Layer for first level).	String
in_summary_attribute (Optional)	Territories can be calculated using the geographic locations of each geography element, or based on the summary value assigned to each geography element. This parameter is used to specify the field of base level to calculate territories. Set empty value when using spatial locations only.	Field
in_density_influence (Optional)	The Density influence for locating territories. Value can be an integer number from 0 to 100.	Long
in_seed_points (Optional)	A Seed Points layer.	Feature Layer
in_name_table (Optional)	The newly created territories can import names from a Name Table. Set to an empty value for default naming according to the ATDConfig.xml file content.	Table
in_name_field (Optional)	The field of the Name Table that is used for importing territory names.	Field
in_unique_names (Optional)	The option in determining whether only unique, or all, names can be imported from the Name Table. UNIQUE_NAMES —Skip names already used in this import session. ALL_NAMES —Use every record for naming territories. Territories with the same names can be created.	Boolean
in_autofill_extent (Optional)	This parameter ensures that all unassigned features will be added to their closest territories regardless of the constraint parameters. This option may affect the assigned parameters in order to include all territories in the solution. AUTO_FILL_EXTENT —Add all unassigned features to their closest territories. DO_NOT_AUTO_FILL_EXTENT —Unassigned features will not change their state.	Boolean
in_override_constraints (Optional)	This parameter ensures that all created territories exceeding constraints will not be automatically removed. It can be useful for finding the reasons why a lower number of territories were created than was required. E.g., if constraints were opposite each other. OVERRIDE_CONSTRAINTS —Do not automatically remove created territories if specified constraints are exceeded. DO_NOT_OVERRIDE_CONSTRAINTS —Automatically remove created territories if specified constraints are exceeded (a warning message will appear in this case).	Boolean

Code sample

CreateTerritories example (Python window)

The following Python window script demonstrates how to use the tool in immediate mode.

import arcgisscripting
gp = arcgisscripting.create()
gp.CreateTerritories_TD("new layer", "Territories[1]", "REMOVE_TERRITORIES", "USER_DEFINED", 40, "CREATE_FROM_CENTERS_OF_DENSITY", "TOTPOP_CY", 50, "Points20.lyr", "ZIPCodes_zp", "NAME", "ALL_NAMES", "DO_NOT_AUTO_FILL_EXTENT", "DO_NOT_OVERRIDE_CONSTRAINTS")

CreateTerritories example 2 (stand-alone script)

The following stand-alone script demonstrates how to use the tool.

# Import system modules
import arcgisscripting
gp = arcgisscripting.create()

# Set local variables
solution = "new layer"
level = "Territories[1]"
removeTerritories = "REMOVE_TERRITORIES"
numberOption = "USER_DEFINED"
territoriesNumber = 40
additionalTerritoriesOption = "CREATE_FROM_CENTERS_OF_DENSITY"
summaryAttribute = "TOTPOP_CY"
densityInfluence = 50
seedPoints = "Points20.lyr"
nameTable = "ZIPCodes_zp"
nameField = "NAME"
uniqueNames = "ALL_NAMES"
autoFillExtent = "DO_NOT_AUTO_FILL_EXTENT"
overrideConstraints = "DO_NOT_OVERRIDE_CONSTRAINTS"

# Execute tool
gp.CreateTerritories_TD(solution, level, removeTerritories, numberOption, territoriesNumber, additionalTerritoriesOption, summaryAttribute, densityInfluence, seedPoints, nameTable, nameField, uniqueNames, autoFillExtent, overrideConstraints)

Environments

This tool does not use any geoprocessing environments.

Licensing information

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