carto-trade-area-analysis

贸易区分析

构建 CARTO Workflows，为候选地点划定集客区，为其添加数据，并对地点评分和排名，用于选址、广告牌布置或覆盖范围分析。

前提条件：加载 carto-create-workflow，了解开发流程、JSON 结构和验证方式。它涵盖两种访问途径——连接 MCP 服务时使用 MCP 服务的工作流工具（create_workflow、validate_workflow、run_workflow），否则使用 carto workflows CLI。路由信号：carto-basics/references/access-paths.md。

临时集客区：如果只需为少量点位生成一次等时圈，请使用 calculate_isolines MCP 工具（可通过 OAuth 使用，或在 Allowed APIs 包含 LDS 的令牌会话中使用）——以下工作流模式适用于表级规模、可重复的分析。

---

说明

贸易区工作流始终遵循以下流程：

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

步骤 1：加载候选地点

使用 native.gettablebyname 加载门店、广告牌、POI 或其他表示候选地点的点数据集。

成功标准：节点输出一个包含几何列（例如 geom）和唯一地点标识符的表。

步骤 2：筛选／限制候选地点（可选）

使用 native.wheresimplified 缩小候选范围（例如，限定特定城市或类别）。使用 native.orderby + native.limit，按某项指标选出排名靠前的 N 个候选地点（例如，按收入选出前 50 个）。

成功标准：输出仅包含与分析相关的候选子集。尽早减少候选数量可避免后续出现组合爆炸。

步骤 3：生成集客区

根据使用场景选择集客区生成方法：

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

等时圈与缓冲区的比较：等时圈遵循路网，生成贴近实际的集客区形状，但需要调用 CARTO LDS API。缓冲区是纯粹的几何圆形区域——更简单、速度更快，适合邻近分析或广告牌覆盖分析。

成功标准：每个候选地点都有一个对应的多边形，表示其集客区。

步骤 4：将集客区转换为空间索引

使用 native.h3polyfill 或 native.quadbinpolyfill 将集客区多边形划分为网格单元。分辨率必须与计划使用的富化数据集相匹配。

成功标准：输出按每个地点的每个网格单元各含一行，并保留空间索引列和地点标识符。

步骤 5：添加数据

将网格单元与空间要素数据集联接，或使用 native.h3enrich：

• 联接方式：使用预先编制索引的富化表，通过 native.joinv2 或 native.spatialjoin 进行联接
• 富化方式：使用 native.h3enrich 从 CARTO 的 Data Observatory 中提取变量

成功标准：每行网格单元都附有富化变量（例如人口、收入、客流量）。

步骤 6：汇总回地点

使用 native.groupby 将网格单元行汇总为每个地点一行：

• 分组依据：地点标识符列
• 聚合方式：population,sum,income,avg（以逗号分隔的列名、方法对）

成功标准：输出中每个候选地点各占一行，并包含已汇总的富化指标。

步骤 7：评分和排名

分三步进行（完整方法请参见 carto-composite-scoring）：使用 native.normalize 将各变量归一化到 [0,1]；通过 native.selectexpression 计算综合得分，例如 normalized_population * 0.4 + normalized_income * 0.3 + normalized_traffic * 0.3；使用 native.orderby（降序）+ native.limit（前 N 个）进行排名。

成功标准：输出候选地点排名列表，包含综合得分和参与计算的归一化变量。

步骤 8：保存

使用 native.saveastable 持久化排序后的结果。

成功标准：工作流通过验证，可通过 create_workflow（MCP）或 carto workflows create（CLI）上传。

---

注意事项

• 提供商的大小写规则与 SQL 方言。 此技能使用小写列名（geom、population、income、normalized_population 等），这符合 BigQuery / Databricks / Postgres / Redshift 的惯例。在 Snowflake 中，未加引号的标识符会显示为大写——请使用 GEOM、POPULATION、INCOME、NORMALIZED_POPULATION 引用它们。有关大小写规则和 SQL 方言对应项，请参阅 carto-create-workflow/references/providers/<provider>.md。
• 等时圈和路线组件会调用 CARTO 的 LDS API——需要具备 API 访问权限的有效连接。缓冲区不需要。
• 用于距离矩阵的交叉连接在位置数量和网格单元数量都很大时，可能导致数据量激增。先筛选并限制候选项（步骤 2），以便管控流水线规模。
• H3 分辨率必须与富化数据集的分辨率一致。选择分辨率之前，请检查富化表的索引列。
• 缓冲区距离的单位是米。等值线范围的单位是秒（type=time）或米（type=distance）。
• native.commercialhotspots 组件要求 variablecolumns 使用 Python 风格的列表字符串（['col1', 'col2']），而 weights 使用逗号分隔的值——这与其他组件不一致。
• 将富化结果聚合回位置时（步骤 6），请确保 GROUP BY 使用位置标识符，而不是网格单元索引。按网格单元分组会得到每个单元的结果，而不是每个位置的结果。
• 使用 native.h3distance 计算竞争对手邻近度时，输出结果以网格为单位。请将其连接回位置表，以获取每个位置的距离指标。

---

参考模板

以下文件是此技能目录中的可用示例：

文件	描述
isochrones_from_points.json	波士顿的零售店——通过 LDS API 创建 5 分钟步行等时圈。native.isolines 使用 v2 版本（mode 列表采用小写线值、customoptions / traveltime_* 输入）。
identify_best_billboards.json	广告牌选址评分——缓冲区、富化、归一化、加权综合评分、前 N 项
commercial_hotspots.json	商业热点检测——计算与竞争对手的 H3 距离，进行加权热点分析

更新组件版本。 模板将每个节点的 data.version 固定为收集模板时的当前版本。原生组件升级版本时（例如，native.isolines 从 v1 升级到 v2，新增交通方式以及 customoptions 和 traveltime_* 输入），旧模板仍可解析，但会显示 verify-remote 警告，并缺少新增输入。要更新模板，请读取实时架构——使用 read_workflow_components（MCP）或 carto workflows components get <component> --connection <conn> --json（CLI）——然后同步更新节点的 data.version 和 inputs。请对照 carto-create-workflow/SKILL.md 检查 Selection 值：options 可能显示的是展示标签，但线值采用小写 / snake_case 形式。

---

常见变体

变体	方法
零售选址	等时圈（步行 / 驾车） -> H3 多边形填充 -> 使用人口统计数据进行富化 -> 按人口 + 收入评分
广告牌 / 户外广告（OOH）布局	缓冲区 -> H3 多边形填充 -> 使用受众 / 交通数据进行富化 -> 归一化 + 加权评分 -> 前 N 项
商业热点检测	H3 网格 -> 使用 native.h3distance 计算与竞争对手的邻近度 -> 使用权重和 p 值阈值运行 native.commercialhotspots
驾车时间覆盖范围分析	等时圈（汽车，多种范围） -> 合并 -> 溶解以查找总覆盖区域
步行时间服务区比较	等时圈（步行，5 / 10 / 15 分钟） -> 富化各范围带 -> 比较每个范围带覆盖的人口
特许经营区域规划	为每个候选项创建等时圈 -> 检查重叠 -> 筛选出不重叠集合 -> 为剩余项评分