Geocoding Addresses in CARTO Workflows

Converts street addresses or place names into geographic coordinates (point geometries). This is an essential first step when working with tabular data that has an address column but no spatial column.

Prerequisites: Load carto-create-workflow for the development process, JSON structure, and validation commands.

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 contains WGS84 (EPSG:4326) point geometries, ready for visualization in CARTO Builder or further spatial analysis.

Success: Validated workflow that can be uploaded via 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

• Geocoding consumes LDS quota. Each row geocoded counts against the account’s Location Data Services quota. Check quota availability before bulk operations, especially on large tables.
• Two output handles: match and unmatch. Don’t connect to the wrong one – match has geometries, unmatch has NULLs. If you connect the unmatch handle to a spatial operation, it 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.
• Output geometry is always WGS84 points. The geom column contains EPSG:4326 point geometries regardless of the input address format or country.
• 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