carto-trade-area-analysis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Trade Area Analysis

商圈分析

Builds CARTO Workflows that define catchment areas around candidate locations, enrich them with data, and score/rank locations for site selection, billboard placement, or coverage analysis.

Prerequisites: Load

carto-create-workflow

for the development process, JSON structure, and validation commands.

构建CARTO工作流，用于定义候选地点周边的客群覆盖区域，为其补充数据，并针对选址、广告牌投放或覆盖分析对地点进行评分/排名。

前提条件：加载

carto-create-workflow

以获取开发流程、JSON结构和验证命令。

Instructions

操作步骤

A trade area workflow always follows this pipeline:

Candidate Locations → (Filter) → Catchment Areas → Spatial Index → Enrich → Aggregate → Score/Rank → Save

商圈分析工作流始终遵循以下流程：

候选地点 → (过滤) → 客群覆盖区域 → 空间索引 → 数据补充 → 聚合 → 评分/排名 → 保存

Step 1: Load Candidate Locations

步骤1：加载候选地点

Use

native.gettablebyname

to load stores, billboards, POIs, or any point dataset representing candidate locations.

Success: Node outputs a table with a geometry column (e.g.

geom

) and a unique location identifier.

使用

native.gettablebyname

加载门店、广告牌、POI或任何代表候选地点的点数据集。

成功标志：节点输出包含几何列（如

geom

）和唯一地点标识符的表格。

Step 2: Filter/Limit Candidates (optional)

步骤2：过滤/筛选候选地点（可选）

Use

native.wheresimplified

to narrow candidates (e.g. specific city, category). Use

native.orderby

native.limit

for top-N by a metric (e.g. top 50 by revenue).

Success: Output contains only the candidate subset relevant to the analysis. Reducing candidates early prevents combinatorial explosion downstream.

使用

native.wheresimplified

缩小候选范围（如特定城市、类别）。使用

native.orderby

native.limit

筛选按指标排名的前N个候选（如按收入排名前50）。

成功标志：输出仅包含与分析相关的候选子集。尽早筛选候选可避免后续流程出现组合爆炸问题。

Step 3: Generate Catchment Areas

步骤3：生成客群覆盖区域

Choose the catchment method based on the use case:

Method	Component	When to use	Key params
Isochrones	`native.isolines`	Site selection, retail — realistic road-network areas	`mode` : car/walk; `type` : time/distance; `range` : seconds or meters
Buffers	`native.buffer`	Billboard coverage, proximity — simple geometric circles	`distance` : meters

Isochrones vs Buffers: Isochrones follow the road network and produce realistic catchment shapes but require a CARTO LDS API call. Buffers are purely geometric circles — simpler and faster, suitable for proximity analysis or billboard coverage.

Success: Each candidate location has an associated polygon representing its catchment area.

根据使用场景选择合适的覆盖区域生成方法：

方法	组件	适用场景	关键参数
等时线(Isochrones)	`native.isolines`	选址、零售——贴合实际路网的区域	`mode` : 驾车/步行; `type` : 时间/距离; `range` : 秒或米
缓冲区(Buffers)	`native.buffer`	广告牌覆盖、邻近分析——简单几何圆形	`distance` : 米

等时线 vs 缓冲区：等时线遵循路网，生成贴合实际的覆盖区域形状，但需要调用CARTO LDS API。缓冲区为纯几何圆形——更简单快速，适用于邻近分析或广告牌覆盖分析。

成功标志：每个候选地点都有对应的多边形代表其客群覆盖区域。

Step 4: Convert Catchment to Spatial Index

步骤4：将覆盖区域转换为空间索引

Use

native.h3polyfill

native.quadbinpolyfill

to tessellate catchment polygons into grid cells. The resolution must match the enrichment dataset you plan to use.

Success: Output contains one row per grid cell per location, with both the spatial index column and the location identifier preserved.

使用

native.h3polyfill

或

native.quadbinpolyfill

将覆盖多边形细分为网格单元。分辨率必须与计划使用的补充数据集匹配。

成功标志：输出包含每个地点对应的每个网格单元的行，同时保留空间索引列和地点标识符。

Step 5: Enrich with Data

步骤5：补充数据

Join grid cells with a spatial features dataset or use

native.h3enrich

JOIN approach:
```
native.joinv2
```
or
```
native.spatialjoin
```
with a pre-indexed enrichment table
Enrich approach:
```
native.h3enrich
```
to pull variables from CARTO's Data Observatory

Success: Each grid cell row has enrichment variables (e.g. population, income, foot traffic) attached.

将网格单元与空间特征数据集关联，或使用

native.h3enrich

：

关联方式：使用
```
native.joinv2
```
或
```
native.spatialjoin
```
与预索引的补充表格关联
补充方式：使用
```
native.h3enrich
```
从CARTO数据观测站提取变量

成功标志：每个网格单元行都附加了补充变量（如人口、收入、人流量）。

Step 6: Aggregate Back to Locations

步骤6：聚合回地点维度

Use

native.groupby

to collapse grid-cell rows back to one row per location:

Group by: the location identifier column
Aggregation:
```
population,sum,income,avg
```
(comma-separated column,method pairs)

Success: Output has one row per candidate location with aggregated enrichment metrics.

使用

native.groupby

将网格单元行合并为每个地点一行：

分组依据：地点标识符列
聚合规则：
```
population,sum,income,avg
```
（逗号分隔的列名与方法对）

成功标志：输出每个候选地点一行，包含聚合后的补充指标。

Step 7: Score and Rank

步骤7：评分与排名

Three-part scoring pattern:

Normalize each variable to [0,1] using
```
native.normalize
```
(one call per variable, or chain multiple)

Composite score via

native.selectexpression

: weighted addition of normalized variables, e.g.

normalized_population * 0.4 + normalized_income * 0.3 + normalized_traffic * 0.3

Rank using
```
native.orderby
```
(descending by composite score) +
```
native.limit
```
(top N)

Success: Output is a ranked list of candidate locations with a composite score and the contributing normalized variables.

三步评分模式：

标准化：使用
```
native.normalize
```
将每个变量标准化至[0,1]（每个变量调用一次，或链式调用多个）

综合评分：通过

native.selectexpression

计算加权和，例如

normalized_population * 0.4 + normalized_income * 0.3 + normalized_traffic * 0.3

排名：使用
```
native.orderby
```
（按综合评分降序） +
```
native.limit
```
（取前N个）

成功标志：输出按综合评分排序的候选地点列表，包含综合评分及各标准化变量。

Step 8: Save

步骤8：保存

Use

native.saveastable

to persist the ranked results.

Success: Validated workflow that can be uploaded via

carto workflows create

使用

native.saveastable

保存排名结果。

成功标志：验证通过的工作流可通过

carto workflows create

上传。

Gotchas

注意事项

Provider casing & SQL dialect. This skill uses lowercase column names (
```
geom
```
,
```
population
```
,
```
income
```
,
```
normalized_population
```
, etc.) — BigQuery / Databricks / Postgres / Redshift convention. On Snowflake, unquoted identifiers surface UPPERCASE — reference them as
```
GEOM
```
,
```
POPULATION
```
,
```
INCOME
```
,
```
NORMALIZED_POPULATION
```
. See
```
carto-create-workflow/references/providers/<provider>.md
```
for casing rules and SQL dialect equivalents.
Isochrone and route components call CARTO's LDS API — they require a valid connection with API access enabled. Buffers do not.
Cross Join for distance matrices can explode with many locations x many grid cells. Filter and limit candidates first (Step 2) to keep the pipeline manageable.
H3 resolution must match the enrichment dataset resolution. Check the enrichment table's index column before choosing resolution.
Buffer distance is in meters. Isoline range is in seconds (for
```
type=time
```
) or meters (for
```
type=distance
```
).
The
```
native.commercialhotspots
```
component expects
```
variablecolumns
```
as a Python-style list string (
```
['col1', 'col2']
```
) and
```
weights
```
as comma-separated values — inconsistent with other components.
When aggregating enrichment back to locations (Step 6), ensure the GROUP BY uses the location identifier, not the grid cell index. Grouping by the grid cell produces per-cell results instead of per-location.
When using
```
native.h3distance
```
for competitor proximity, the output is grid-based. Join it back to the location table to get per-location distance metrics.

提供商大小写与SQL方言：本技能使用小写列名（
```
geom
```
、
```
population
```
、
```
income
```
、
```
normalized_population
```
等）——符合BigQuery / Databricks / Postgres / Redshift的约定。在Snowflake中，未加引号的标识符会显示为大写——需引用为
```
GEOM
```
、
```
POPULATION
```
、
```
INCOME
```
、
```
NORMALIZED_POPULATION
```
。请查看
```
carto-create-workflow/references/providers/<provider>.md
```
获取大小写规则和SQL方言对应关系。
等时线和路线组件会调用CARTO的LDS API——需要启用API访问权限的有效连接。缓冲区无需调用该API。
距离矩阵的交叉连接会因大量地点×大量网格单元而导致数据爆炸。请先筛选候选地点（步骤2）以保持流程可控。
H3分辨率必须与补充数据集的分辨率匹配。选择分辨率前请检查补充表格的索引列。
缓冲区距离单位为米。等时线范围单位为秒（当
```
type=time
```
时）或米（当
```
type=distance
```
时）。
```
native.commercialhotspots
```
组件要求
```
variablecolumns
```
为Python风格的列表字符串（
```
['col1', 'col2']
```
），
```
weights
```
为逗号分隔值——与其他组件的格式不一致。
在将补充数据聚合回地点维度时（步骤6），确保分组依据为地点标识符，而非网格单元索引。按网格单元分组会得到每个单元的结果，而非每个地点的结果。
使用
```
native.h3distance
```
分析竞品邻近度时，输出为网格维度。需将其关联回地点表格以获取每个地点的距离指标。

Reference Templates

参考模板

These files are working examples in this skill directory:

File	Description
`isochrones_from_points.json`	Retail stores in Boston — 5-min walk-time isochrones via LDS API
`identify_best_billboards.json`	Billboard site scoring — buffer, enrich, normalize, weighted composite score, top-N
`commercial_hotspots.json`	Commercial hotspot detection — H3 distance to competitors, weighted hotspot analysis

本技能目录中的以下文件为可运行示例：

文件	描述
`isochrones_from_points.json`	波士顿零售门店——通过LDS API生成5分钟步行等时线
`identify_best_billboards.json`	广告牌场地评分——缓冲区、数据补充、标准化、加权综合评分、取前N个
`commercial_hotspots.json`	商业热点检测——使用H3距离分析竞品邻近度、加权热点分析

Common Variations

常见变体

Variant	How
Retail site selection	Isochrones (walk/drive) -> H3 polyfill -> enrich with demographics -> score by population + income
Billboard/OOH placement	Buffers -> H3 polyfill -> enrich with audience/traffic -> normalize + weighted score -> top-N
Commercial hotspot detection	H3 grid -> `native.h3distance` for competitor proximity -> `native.commercialhotspots` with weights and p-value threshold
Drive-time coverage analysis	Isochrones (car, multiple ranges) -> union -> dissolve to find total coverage area
Walk-time catchment comparison	Isochrones (walk, 5/10/15 min) -> enrich each band -> compare population captured per band
Franchise territory planning	Isochrones per candidate -> check overlap -> filter non-overlapping set -> score remaining

变体	实现方式
零售选址	等时线（步行/驾车）-> H3多边形填充 -> 补充人口统计数据 -> 按人口+收入评分
广告牌/OOH投放	缓冲区 -> H3多边形填充 -> 补充受众/流量数据 -> 标准化+加权评分 -> 取前N个
商业热点检测	H3网格 -> 使用 `native.h3distance` 分析竞品邻近度 -> 使用 `native.commercialhotspots` 并设置权重和p值阈值
驾车时长覆盖分析	等时线（驾车，多范围）-> 合并 -> 融合以获取总覆盖区域
步行时长覆盖对比	等时线（步行，5/10/15分钟）-> 为每个时段补充数据 -> 对比各时段覆盖的人口
特许经营区域规划	为每个候选地点生成等时线 -> 检查重叠 -> 筛选非重叠集合 -> 对剩余地点评分