Carto Geocoding

Geocoding Addresses in CARTO Workflows

Converts street addresses or place names into geographic coordinates (point geometries) — the essential first step when tabular data has an address column but no spatial column. Two access paths, by scale:

• Single / ad-hoc (MCP-first): for a handful of addresses (or reverse-geocoding coordinates back to addresses), the CARTO MCP geocode tool answers directly — operations geocode, reverse, and capabilities. No workflow needed. It runs on any MCP host, including sandboxed chat hosts where the CLI can't. Prefer it for interactive requests.
• Table-scale / repeatable: to geocode a whole table or build a reusable pipeline, use the Workflow pattern below. Load carto-create-workflow for the development process, JSON structure, and validation — it covers both paths (MCP create_workflow / validate_workflow / run_workflow when attached; the carto workflows CLI otherwise; routing signals in carto-basics/references/access-paths.md).

Over an API-token MCP session the ad-hoc/authoring tools are hidden (read/discovery only) — fall back to the CLI or reconnect over OAuth.

Instructions

A geocoding workflow follows this pipeline:

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

Step 1: Load Source Data

Use native.gettablebyname. The input table must contain a column with address strings (e.g. address, full_address, location).

Success: Node outputs a table with at least one text column containing address data.

Step 2: Geocode

Use native.geocode with:

The address column can contain full addresses ("123 Main St, Springfield, IL 60001") or composite values built from multiple columns (concatenate street + city + postal code in a prior native.selectexpression step).

Two output handles: The geocode component produces two separate outputs:

• match: Rows where geocoding succeeded -- a geom column with point geometry is added, plus a CARTO_GEOCODE_METADATA JSON column with quality info (confidence score, match type).
• unmatch: Rows where geocoding failed -- geom is NULL.

Connect downstream nodes to the correct handle based on your needs.

Success: The geocode node is configured with the address column and (ideally) a country filter. Edges connect to the match and/or unmatch output handles.

Step 3: Filter or Review Results (optional)

For the match output:

• Optionally filter by confidence using the metadata column (e.g. extract confidence from CARTO_GEOCODE_METADATA via native.selectexpression).

For the unmatch output:

• Save to a separate table for review and manual correction.
• Common failure causes: typos, incomplete addresses, PO boxes, ambiguous place names.

Success: High-confidence geocoded rows are isolated; failed rows are captured for review.

Step 4: Save Results

Use native.saveastable to persist the geocoded output — the geom column holds WGS84 (EPSG:4326) points, ready for CARTO Builder or further analysis. Then validate and upload the workflow (MCP create_workflow / validate_workflow, or carto workflows create).

Geocoding Under the Hood

The workflow component wraps the CARTO Analytics Toolbox function GEOCODE_TABLE, which:

• Adds a geom column with point geometry to each row
• Adds a CARTO_GEOCODE_METADATA JSON column with quality information (confidence, match type)
• Uses CARTO Location Data Services (LDS) -- each geocoded row consumes LDS quota

Check available quota by querying the Analytics Toolbox LDS_QUOTA_INFO() function. The fully-qualified name is provider-specific (BigQuery: `carto-un.carto`.LDS_QUOTA_INFO(); Snowflake: CARTO.CARTO.LDS_QUOTA_INFO(); Databricks: stored procedure in the dedicated AT schema). Load carto-create-workflow and consult references/providers/<provider>.md for the AT path on your warehouse.

Gotchas

• Two output handles: match and unmatch. Don't connect to the wrong one -- match has geometries, unmatch has NULLs. Connecting the unmatch handle to a spatial operation will fail.
• Country filter is strongly recommended. Without it, ambiguous addresses may resolve to the wrong country (e.g. "Springfield" exists in 30+ US states and in other countries). The country parameter improves both accuracy and speed.
• Address formatting matters. Well-formatted addresses produce better results: "123 Main St, Springfield, IL 60001" works better than "123 main street springfield". Include city, state/region, and postal code when available.
• Provider casing & SQL dialect. Examples in this skill use lowercase column names (BigQuery / Databricks / Postgres / Redshift convention); on Snowflake unquoted identifiers surface UPPERCASE (e.g. CARTO_GEOCODE_METADATA, GEOM). When writing dialect-specific SQL or referencing the AT path, see carto-create-workflow/references/providers/<provider>.md.
• For large tables, consider batching. Geocoding hundreds of thousands of rows in a single run can exhaust quota or time out. Split into batches if needed.
• Failed geocodes deserve review. The unmatch output is not just noise -- it often reveals data quality issues (missing postal codes, abbreviated city names, non-standard formatting) that can be fixed and re-geocoded.

Reference Templates

Academy tutorials and workflow templates covering geocoding:

Common Variations