Territory Planning (Territory Balancing + Location Allocation)

Builds CARTO Workflows that solve two related spatial optimization problems: dividing areas into balanced territories (e.g. sales regions, service zones) and finding optimal facility locations that maximize coverage or minimize cost.

Prerequisites: Load

carto-create-workflow

for the development process, JSON structure, and validation commands. Both components require the Territory Planning Extension Package installed on the connection.

Territory Balancing

Divides a study area into spatially contiguous territories that are balanced by a demand variable (e.g. workload, population, revenue).

Pipeline

Source Data (points) -> Spatial Indexing -> Aggregate per Cell -> Territory Balancing -> Save

Step 1: Load Source Data

Use

native.gettablebyname

. Input is typically point data with one or more numeric metrics to balance.

Success: Node outputs a table with a geometry column and numeric metric columns.

Step 2: Convert to Spatial Index

Use

native.h3frompoint

(or

native.quadbinfromgeopoint

) to assign each point to a grid cell.

Resolution guidance: Higher resolution = smaller cells = finer-grained territories, but more computation. H3 resolution 8-9 is typical for city-level analysis.

Success: Output has a spatial index column (e.g.

h3

Step 3: Aggregate per Cell

Use

native.groupby

to produce one row per cell with the metrics to balance:

Group by: the spatial index column (
```
h3
```
)
Aggregation: e.g.
```
geom,count,revenue,sum,population,avg
```

Success: One row per cell with numeric columns for demand and optional similarity features.

Step 4: Run Territory Balancing

Use

native.territorybalancing

with:

Input	Description	Example
`input_table`	Table input (from previous step)
`index_column`	H3 or Quadbin column	`h3`
`demand_column`	Numeric column to balance across territories	`geom_count`
`similarity_feats`	Optional numeric columns for within-territory similarity	`["sentiment_avg", "popularity_avg"]`
`npartitions`	Number of territories to create	`9`
`keep_input_columns`	Include all input columns in output	`true`

Success: Output contains all input rows with an additional territory assignment column. Each cell is assigned to exactly one territory.

Step 5: Save

Use

native.saveastable

to persist results. The spatial index column is directly visualizable in CARTO Builder, colored by territory ID.

Success: Validated workflow uploadable via

carto workflows create

Location Allocation

Finds the optimal subset of candidate facility locations that either maximize demand coverage or minimize total cost/distance.

Pipeline

Demand Data (grid/points) -> Candidate Locations -> Location Allocation -> Save

Step 1: Load Demand Data

Use

native.gettablebyname

to load a grid or point dataset representing demand (e.g. population per H3 cell, customer locations).

Success: Table with a spatial index column and a numeric demand column.

Step 2: Load Candidate Locations

Use a second

native.gettablebyname

for potential facility locations (e.g. existing infrastructure, candidate sites).

If candidates need filtering, use

native.wheresimplified

native.limit

to reduce the set -- fewer candidates = faster computation.

Success: Table with a spatial index column representing candidate sites.

Step 3: Run Location Allocation

Choose the variant based on the objective:

Maximize Coverage

Use

native.locallocallocation_maximizecoverage

Input	Description	Example
`demand`	Table with demand values
`demand_index_column`	Spatial index column in demand table	`h3`
`demand_column`	Numeric demand variable	`population`
`candidates`	Table with candidate locations
`candidates_index_column`	Spatial index column in candidates table	`h3`
`nfacilities`	Number of facilities to open	`5`
`coverageradius`	Maximum service distance (meters for geography)	`5000`

Success: Output identifies which facilities to open and which demand cells each facility serves, maximizing total covered demand within the radius.

Minimize Total Cost

Use

native.locallocallocation_minimizetotalcost

Input	Description	Example
`demand`	Table with demand values
`demand_index_column`	Spatial index column in demand table	`h3`
`demand_column`	Numeric demand variable	`population`
`candidates`	Table with candidate locations
`candidates_index_column`	Spatial index column in candidates table	`h3`
`nfacilities`	Number of facilities to open	`5`

Success: Output identifies which facilities to open, minimizing total weighted travel distance between demand and assigned facilities.

Step 4: Save

Use

native.saveastable

to persist results.

Success: Validated workflow uploadable via

carto workflows create

Gotchas

Provider casing & SQL dialect. This skill uses lowercase column names (
```
h3
```
,
```
geom_count
```
,
```
population
```
,
```
sentiment_avg
```
, etc.) — BigQuery / Databricks / Postgres / Redshift convention. On Snowflake, unquoted identifiers surface UPPERCASE — reference them as
```
H3
```
,
```
GEOM_COUNT
```
,
```
POPULATION
```
,
```
SENTIMENT_AVG
```
. See
```
carto-create-workflow/references/providers/<provider>.md
```
for casing rules and SQL dialect equivalents.
Extension package required: Both territory balancing and location allocation require the Territory Planning Extension Package installed on the specific connection being used. This is NOT available by default -- the user must have it installed. Validation will fail if the package is missing.
Location allocation is computationally expensive with many candidates. Pre-filter candidates (by geography, capacity, or other criteria) to keep the candidate set small. Hundreds of candidates can be slow; thousands may time out.
Coverage radius units depend on the spatial reference system -- typically meters when using geography types. Verify the unit matches your intent.
Territory balancing optimizes a trade-off between spatial contiguity and balance. Perfect balance is not guaranteed -- territories will be approximately equal in the demand variable, not exactly equal.
Grid resolution sensitivity: Results change significantly with the input grid resolution. Finer grids give more precise boundaries but increase computation. Start with H3 resolution 8 for city-scale and adjust.

The component names use

native.territorybalancing

(no dot separator in "territory balancing") and

native.locallocallocation_maximizecoverage

native.locallocallocation_minimizetotalcost

(note the double "local" prefix).

Demand data must cover the study area. Gaps in the demand grid mean those areas are invisible to the optimizer. Use polyfill + COALESCE(value, 0) if you need full coverage.

Reference Templates

Academy Tutorials

Territory Balancing tutorial -- step-by-step walkthrough of the Milan POS use case
Location Allocation tutorial -- telco network management with location allocation
AI Agent + Location Allocation -- using AI agents with location allocation for emergency response hub placement

Common Variations

Variant	How
Sales territory balancing	Points -> H3 -> aggregate revenue per cell -> territory balancing with revenue as demand
Service zone design	Grid with population -> territory balancing to create equal-population zones
Warehouse/depot placement	Population grid as demand + existing warehouses as candidates -> minimize total cost
Emergency response hubs	Population grid as demand + candidate sites -> maximize coverage with a response-time radius
Retail network expansion	Customer density grid as demand + potential store locations -> maximize coverage
Combined territory + allocation	First run location allocation to pick hub locations, then run territory balancing to assign areas to each hub

carto-territory-planning

NPX Install

Tags

SKILL.md Content

Territory Planning (Territory Balancing + Location Allocation)

Territory Balancing

Pipeline

Step 1: Load Source Data

Step 2: Convert to Spatial Index

Step 3: Aggregate per Cell

Step 4: Run Territory Balancing

Step 5: Save

Location Allocation

Pipeline

Step 1: Load Demand Data

Step 2: Load Candidate Locations

Step 3: Run Location Allocation

Maximize Coverage

Minimize Total Cost

Step 4: Save

Gotchas

Reference Templates

Academy Tutorials

Common Variations