Geocodio CLI: Geocode, Reverse Geocode, and Calculate Distances from the Command Line

Quick Summary

The Geocodio CLI is a free, open-source command-line tool for geocoding addresses, reverse geocoding coordinates, calculating distances, and batch processing spreadsheets. It runs on Linux, macOS, and Windows. All Geocodio features are available, including data appends like Census tracts, Congressional districts, and timezones.

What Is the Geocodio CLI?

The Geocodio CLI gives you direct access to the Geocodio API from your terminal. Instead of writing code or uploading spreadsheets through the dashboard, you can geocode addresses, look up coordinates, calculate driving distances, and process large CSV files with a single command.

It is built for developers, data engineers, and analysts who want to work with location data without leaving the command line.

The CLI is open source and written in Go. The source code is available on GitHub.

Installation

Quick Install (Recommended)

Run the install script to download the latest release for your platform:

Install a Specific Version

Install with Go

Download Manually

Pre-built binaries for Linux, macOS, and Windows are available on the GitHub releases page.

Setup

All commands require a Geocodio API key. Generate one for free from the Geocodio Dashboard.

Set your API key as an environment variable:

Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) so it persists across sessions.

You can also pass the key directly with --api-key on any command.

What the CLI Can Do

The Geocodio CLI supports all major Geocodio features:

• Geocode addresses to get coordinates, formatted addresses, and data appends
• Reverse geocode coordinates to get addresses
• Calculate distances between locations (driving or straight-line)
• Build distance matrices between multiple origins and destinations
• Run async distance jobs for large-scale calculations
• Process spreadsheets (CSV and Excel) in batch

All of the data append fields available through the API work with the CLI, including Census data, Congressional districts, timezones, school districts, and more.

Commands

Geocode an Address

Add data appends with the --fields flag:

Batch Geocode from a File

Create a text file with one address per line, then:

The batch endpoint accepts up to 10,000 addresses per request.

Reverse Geocode Coordinates

Batch reverse geocoding works the same way. Create a file with one lat,lng pair per line:

Calculate Distances

From one origin to one or more destinations:

Use --mode driving for driving distance and duration, or --mode straightline for straight-line distance. Use --units km for kilometers.

Distance Matrix

Calculate distances between multiple origins and multiple destinations:

Async Distance Jobs

For large distance calculations, create a background job and check on it later:

The --watch flag shows a progress bar until the job completes. List, check status, download results, or delete jobs with the distance-jobs subcommands.

Process Spreadsheets

Upload a CSV or Excel file for batch geocoding:

The --format flag maps your columns to address components. {{A}} is the first column, {{B}} is the second, and so on.

Watch progress, then download results:

Output Formats

The CLI supports three output formats:

• Human-readable (default): Colored, formatted output for your terminal
• JSON (--json): Full API response for scripting and piping to tools like jq
• Agent (--agent): Clean markdown tables for AI coding assistants and LLMs

Use the CLI in Your Workflows

The Geocodio CLI fits naturally into automated pipelines:

• ETL jobs: Geocode address data as part of a data pipeline
• Cron jobs: Schedule regular batch processing of new addresses
• CI/CD: Validate address data during builds or deployments
• Shell scripts: Chain commands together with pipes and file redirects

AI Coding Assistant Integration

The Geocodio CLI includes a skill file that teaches AI coding assistants how to use it. Once installed, assistants like Claude Code, Cursor, Amp, and Codex can geocode addresses, calculate distances, and process spreadsheets on your behalf.

Install the skill:

The skill activates automatically when you ask your assistant to work with addresses or location data.

Migrating from v1.x

If you used the previous version of the CLI, here are the key changes in v2.0:

• Spreadsheet commands are now grouped under geocodio lists (e.g., lists upload, lists status, lists download)
• The --direction flag (forward or reverse) is now required when uploading spreadsheets
• The --follow flag has been renamed to --watch
• The --apikey flag has been renamed to --api-key
• New commands: geocode, reverse, distance, distance-matrix, and distance-jobs

See the full migration guide on GitHub.

Troubleshooting

"API key required": Set GEOCODIO_API_KEY as an environment variable or pass --api-key on the command.

"batch size exceeds maximum of 10,000": Split your file into smaller chunks. The batch endpoints accept up to 10,000 items per request.

"invalid coordinate format": Reverse geocoding expects lat,lng format. Latitude comes first.

Debugging: Use --debug to see full HTTP request and response details.

Open Source

The Geocodio CLI is open source under the MIT license. Contributions, issues, and feature requests are welcome on GitHub.