carto-geocoding

在 CARTO 工作流中进行地址地理编码

将街道地址或地点名称转换为地理坐标（点几何）——当表格数据包含地址列但没有空间列时，这是必不可少的第一步。根据数据规模，有两种使用方式：

• 单条／临时（MCP 优先）：对于少量地址（或将坐标反向地理编码为地址），CARTO MCP geocode 工具可直接处理——操作包括 geocode、reverse 和 capabilities。无需工作流。它可在任何 MCP 主机上运行，包括无法使用 CLI 的沙盒聊天主机。交互式请求优先使用此方式。
• 整表／可重复使用：若要对整张表进行地理编码或构建可复用的流水线，请使用下方的工作流模式。加载 carto-create-workflow，了解开发流程、JSON 结构和验证方式——它涵盖两种路径（连接时使用 MCP create_workflow / validate_workflow / run_workflow；否则使用 carto workflows CLI；路由信号见 carto-basics/references/access-paths.md）。

在 API 令牌 MCP 会话中，临时处理／创作工具会被隐藏（仅提供读取／发现功能）——请改用 CLI 或通过 OAuth 重新连接。

---

说明

地理编码工作流遵循以下流水线：

Source Table (with address column) -> Geocode -> (Filter successful) -> Save

步骤 1：加载源数据

使用 native.gettablebyname。输入表必须包含一个存有地址字符串的列（例如 address、full_address、location）。

成功条件：节点输出的表中至少有一个文本列包含地址数据。

步骤 2：地理编码

使用 native.geocode，参数如下：

输入	说明	必填
source	包含地址数据的表	是
address	包含地址字符串的列	是
country	用于提高准确度的国家/地区筛选条件（例如 "United States"、"United Kingdom"）	否，但强烈建议提供

地址列可以包含完整地址（"123 Main St, Springfield, IL 60001"），也可以包含由多个列组合而成的值（在之前的 native.selectexpression 步骤中拼接街道、城市和邮政编码）。

两个输出句柄：地理编码组件会生成两个独立输出：

• match：地理编码成功的行——会添加包含点几何的 geom 列，以及包含质量信息（置信度分数、匹配类型）的 CARTO_GEOCODE_METADATA JSON 列。
• unmatch：地理编码失败的行——geom 为 NULL。

根据需要将下游节点连接到相应的句柄。

成功条件：地理编码节点已配置地址列和（理想情况下）国家/地区筛选条件。边已连接到 match 和／或 unmatch 输出句柄。

步骤 3：筛选或检查结果（可选）

对于 match 输出：

• 可选：使用元数据列按置信度进行筛选（例如通过 native.selectexpression 从 CARTO_GEOCODE_METADATA 中提取置信度）。

对于 unmatch 输出：

• 保存到单独的表中，以便检查和手动修正。
• 常见失败原因：拼写错误、地址不完整、邮政信箱、地点名称不明确。

成功条件：高置信度的地理编码行已单独筛出；失败的行已收集，以供检查。

步骤 4：保存结果

使用 native.saveastable 保存地理编码输出——geom 列存储 WGS84（EPSG:4326）点，可直接用于 CARTO Builder 或进一步分析。然后验证并上传工作流（使用 MCP create_workflow / validate_workflow，或 carto workflows create）。

---

地理编码背后的原理

工作流组件封装了 CARTO Analytics Toolbox 函数 GEOCODE_TABLE，该函数会：

• 为每一行添加一个包含点几何的 geom 列
• 添加一个包含质量信息（置信度、匹配类型）的 CARTO_GEOCODE_METADATA JSON 列
• 使用 CARTO Location Data Services (LDS)——每个完成地理编码的行都会消耗 LDS 配额

可通过查询 Analytics Toolbox 函数 LDS_QUOTA_INFO() 检查可用配额。完全限定名称因提供方而异（BigQuery：`carto-un.carto`.LDS_QUOTA_INFO()；Snowflake：CARTO.CARTO.LDS_QUOTA_INFO()；Databricks：专用 AT 架构中的存储过程）。加载 carto-create-workflow，并查阅 references/providers/<provider>.md，了解数据仓库中的 AT 路径。

---

注意事项

• 有两个输出句柄：match 和 unmatch。 请勿连接错误的句柄——match 包含几何，unmatch 包含 NULL。将 unmatch 句柄连接到空间操作会导致失败。
• 强烈建议设置国家/地区筛选条件。 如果不设置，含义模糊的地址可能会被解析到错误的国家/地区（例如，30 多个美国州以及其他国家/地区都有名为 “Springfield” 的地方）。国家/地区参数可以提高准确性和速度。
• 地址格式很重要。 格式良好的地址能得到更好的结果："123 Main St, Springfield, IL 60001" 的效果优于 "123 main street springfield"。在可能的情况下，请包含城市、州/地区和邮政编码。
• 提供方标识符大小写与 SQL 方言。 本技能中的示例使用小写列名（BigQuery / Databricks / Postgres / Redshift 惯例）；在 Snowflake 中，未加引号的标识符会以大写形式显示（例如 CARTO_GEOCODE_METADATA、GEOM）。编写特定方言的 SQL 或引用 AT 路径时，请参阅 carto-create-workflow/references/providers/<provider>.md。
• 对于大型表，请考虑分批处理。 单次运行中对数十万行进行地理编码可能会耗尽配额或超时。必要时请拆分批次。
• 应检查地理编码失败的记录。 unmatch 输出并非无用数据——它通常能揭示数据质量问题（缺少邮政编码、城市名称缩写、格式不规范），这些问题可以修复后重新进行地理编码。

---

参考模板

涵盖地理编码的 Academy 教程和工作流模板：

资源	说明	URL
Geocoding (BigQuery AT)	使用适用于 BigQuery 的 Analytics Toolbox 分步进行地理编码	Academy 链接
Geocoding (Snowflake AT)	使用适用于 Snowflake 的 Analytics Toolbox 分步进行地理编码	Academy 链接
工作流模板：对街道地址进行地理编码	根据地址生成新的空间数据	Academy 链接

---

常见变体

变体	方法
使用多个列构成复合地址	在地理编码前添加一个 native.selectexpression 步骤，将街道、城市、州、邮政编码拼接到一个列中
地理编码 + 空间连接	链接：Geocode -> match -> Spatial Join（例如，通过点在多边形内判断来分配区域）
地理编码 + 丰富数据	链接：Geocode -> match -> Buffer/Isochrone -> Enrich（为每个完成地理编码的点添加周边人口统计数据）
捕获失败记录以便重新处理	将 match 和 unmatch 两个句柄分别连接到独立的 native.saveastable 节点
按置信度筛选	地理编码后，使用 native.selectexpression 从元数据 JSON 中提取置信度，然后进行筛选