Skip to content

Geocodio/geocodio-cli

BranchesTags

Repository files navigation

geocodio-cli

A command-line interface for the Geocodio API that lets you geocode addresses, reverse geocode coordinates, calculate distances, and process spreadsheets—all from your terminal.

Whether you're geocoding a single address or processing thousands in batch, this CLI gives you quick access to Geocodio's powerful geocoding capabilities without writing any code.

Table of Contents

Getting Started

Prerequisites

Installation

Quick install (recommended):

curl -fsSL https://raw.githubusercontent.com/geocodio/geocodio-cli/main/install.sh | sh

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/geocodio/geocodio-cli/main/install.sh | sh -s -- --version v1.0.0

With Go:

go install github.com/geocodio/geocodio-cli/cmd/geocodio@latest

Your First Geocode

Once installed, set your API key and try geocoding an address:

export GEOCODIO_API_KEY=your-api-key
geocodio geocode "1600 Pennsylvania Ave NW, Washington DC"

You'll see the latitude, longitude, and formatted address returned by the API.

Configuration

API Key

You can provide your API key in two ways:

Environment variable (recommended):

export GEOCODIO_API_KEY=your-api-key

Command-line flag:

geocodio geocode "1600 Pennsylvania Ave NW, Washington DC" --api-key your-api-key

Tip

Add the export command to your shell profile (~/.bashrc, ~/.zshrc, etc.) so you don't have to set it every session.

Commands

Geocoding

Convert addresses into geographic coordinates.

Single address:

geocodio geocode "1600 Pennsylvania Ave NW, Washington DC"

With data appends:

Geocodio can return additional data like timezone, congressional district, census data, and more. Specify fields with the --fields flag:

geocodio geocode "30 Rockefeller Plaza, New York NY" --fields timezone,cd

Note

Data append fields may incur additional API costs. See Geocodio's documentation for available fields and pricing.

Batch geocoding from a file:

For processing many addresses at once, create a file with one address per line and use the --batch flag:

geocodio geocode --batch addresses.txt

When running in a terminal, you'll see a spinner while the batch processes.

With inline distance calculations:

Geocode an address and calculate distances to one or more destinations in a single request:

geocodio geocode "1600 Pennsylvania Ave NW, Washington DC" --destinations "New York" --destinations "Boston"

With driving mode for actual driving distance and duration:

geocodio geocode "1600 Pennsylvania Ave NW, Washington DC" --destinations "New York" --distance-mode driving

With stable address key:

Show the stable address key for a result, which can be used in future requests instead of an address:

geocodio geocode "1600 Pennsylvania Ave NW, Washington DC" --show-address-key

JSON output:

geocodio geocode "1600 Pennsylvania Ave NW, Washington DC" --json

All geocode flags:

Flag Alias Description
--batch -b File containing addresses (one per line)
--fields -f Data append fields (comma-separated)
--limit -l Maximum number of results per address
--country -c Country hint (US or CA)
--destinations -d Destination addresses or coordinates for distance calculation (repeatable)
--distance-mode -m Distance mode: driving or straightline
--distance-units -u Distance units: miles or km
--show-address-key Show stable address key in output

Reverse Geocoding

Convert coordinates back into addresses.

Single coordinate pair:

geocodio reverse "38.8976,-77.0365"

Batch reverse geocoding:

geocodio reverse --batch coordinates.txt

The coordinates file should have one lat,lng pair per line:

38.8976,-77.0365
40.7128,-74.0060
34.0522,-118.2437

Skip geocoding (fields only):

Get only field appends (timezone, census data, etc.) for coordinates without reverse geocoding an address:

geocodio reverse "40.7588,-73.9788" --skip-geocoding --fields timezone,cd

With inline distance calculations:

geocodio reverse "38.8976,-77.0365" --destinations "New York" --distance-mode driving

All reverse flags:

Flag Alias Description
--batch -b File containing coordinates (one per line)
--fields -f Data append fields (comma-separated)
--limit -l Maximum number of results per coordinate
--skip-geocoding Skip reverse geocoding, only return field appends
--destinations -d Destination addresses or coordinates for distance calculation (repeatable)
--distance-mode -m Distance mode: driving or straightline
--distance-units -u Distance units: miles or km
--show-address-key Show stable address key in output

Distance Calculation

Calculate distances from one origin to one or more destinations.

Basic usage:

geocodio distance "Washington DC" "New York"

Multiple destinations:

geocodio distance "Washington DC" "New York" "Boston" "Philadelphia"

With options:

geocodio distance "Washington DC" "New York" --mode driving --units km

Distance flags:

Flag Alias Default Description
--mode -m driving Routing mode: driving or straightline
--units -u miles Distance units: miles or km

Tip

Use straightline mode for quick "as the crow flies" distances when you don't need actual driving routes.

Distance Matrix

Calculate distances between multiple origins and multiple destinations. This is useful for logistics, delivery routing, or finding the closest locations.

geocodio distance-matrix --origins origins.txt --destinations destinations.txt

Both files should contain one location per line (addresses or coordinates).

Distance matrix flags:

Flag Alias Required Default Description
--origins -o Yes — File containing origin locations
--destinations -d Yes — File containing destination locations
--mode -m No driving Routing mode: driving or straightline
--units -u No miles Distance units: miles or km

Async Distance Jobs

For large distance calculations, use async jobs. These run in the background and you can check their status or download results later.

Create a job:

geocodio distance-jobs create --name "My Job" --origins origins.txt --destinations destinations.txt

Create and watch progress:

geocodio distance-jobs create --name "My Job" --origins origins.txt --destinations destinations.txt --watch

When running in a terminal, you'll see an animated progress bar showing the job's completion status.

List all jobs:

geocodio distance-jobs list

Check job status:

geocodio distance-jobs status 12345

# Watch until completion
geocodio distance-jobs status 12345 --watch

Download results:

# Output to stdout
geocodio distance-jobs download 12345

# Save to file
geocodio distance-jobs download 12345 --output results.csv

Delete a job:

geocodio distance-jobs delete 12345

Distance jobs create flags:

Flag Alias Required Default Description
--name -n Yes — Job name for identification
--origins -o Yes — File containing origin locations
--destinations -d Yes — File containing destination locations
--mode -m No driving Routing mode: driving or straightline
--units -u No miles Distance units: miles or km
--watch -w No false Watch progress until completion

Spreadsheet Processing

Upload CSV or Excel files for batch geocoding. Geocodio processes the file asynchronously and returns results with coordinates appended to your data.

Upload a file:

geocodio lists upload data.csv --direction forward --format "{{A}} {{B}}, {{C}}"

The --format flag tells Geocodio which columns contain address components. Use {{A}}, {{B}}, {{C}}, etc. to reference columns:

  • {{A}} = Column A (first column)
  • {{B}} = Column B (second column)
  • And so on...

Example: If your CSV has street in column A, city in column B, and state in column C:

geocodio lists upload addresses.csv --direction forward --format "{{A}}, {{B}}, {{C}}"

Upload and watch progress:

geocodio lists upload data.csv --direction forward --format "{{A}}" --watch

List all uploaded spreadsheets:

geocodio lists list

Check status:

geocodio lists status 12345

# Watch until completion
geocodio lists status 12345 --watch

Download results:

# Output to stdout
geocodio lists download 12345

# Save to file
geocodio lists download 12345 --output geocoded.csv

Delete a spreadsheet:

geocodio lists delete 12345

Lists upload flags:

Flag Alias Required Description
--direction -d Yes forward (address→coords) or reverse (coords→address)
--format -f Yes Column format template (e.g., {{A}} {{B}}, {{C}})
--watch -w No Watch progress until completion
--callback — No URL to receive a POST request when processing completes
--fields -F No Data append fields (comma-separated, e.g., cd,timezone)

Warning

Large spreadsheets can take time to process. Use the --watch flag or check status periodically rather than waiting for immediate results.

Output Formats

The CLI supports multiple output formats to fit different workflows.

Human-Readable (Default)

The default output is formatted for easy reading in your terminal. When connected to a terminal, you'll see:

  • Colored output with status indicators (green for completed, yellow for processing, red for failed)
  • Styled labels for better visual hierarchy
  • Progress indicators during batch operations and watch mode

JSON Output

For scripting and programmatic use, get raw JSON with the --json flag:

geocodio geocode "1600 Pennsylvania Ave NW, Washington DC" --json

This returns the complete API response, perfect for piping to jq or processing in scripts.

Agent Output (Markdown)

For AI assistants and LLMs, use the --agent flag to get clean markdown tables:

geocodio geocode "1600 Pennsylvania Ave NW, Washington DC" --agent

This outputs structured markdown that's easy for language models to parse:

## Geocode Result

| Field | Value |
|-------|-------|
| Matched Address | 1600 Pennsylvania Ave NW, Washington, DC 20500 |
| Coordinates | 38.8976763, -77.0365298 |
| Accuracy | rooftop (1.00) |

Disabling Colors

Colors are automatically disabled when output is piped or redirected. To explicitly disable colors:

# Using the flag
geocodio geocode "1600 Pennsylvania Ave NW, Washington DC" --no-color

# Using the environment variable
NO_COLOR=1 geocodio geocode "1600 Pennsylvania Ave NW, Washington DC"

Tip

The NO_COLOR environment variable follows the no-color.org standard and works across many CLI tools.

Global Flags

These flags work with all commands:

Flag Description
--api-key Geocodio API key (or use GEOCODIO_API_KEY env var)
--json Output results as JSON
--agent Output results as markdown (for LLM consumption)
--no-color Disable colored output (also respects NO_COLOR env var)
--base-url Override API base URL (useful for testing or enterprise endpoints)
--debug Show HTTP request/response details
--version Show version information
--help Show help for any command

AI Coding Assistant Skill

The Geocodio CLI includes a skill that teaches AI coding assistants how to use it. Once installed, your assistant can geocode addresses, reverse geocode coordinates, calculate distances, and process spreadsheets on your behalf.

Compatibility

Works with any AI coding assistant that supports skills, including Claude Code, Cursor, Amp, and Codex.

Installation

npx skills add geocodio/geocodio-cli

What's Included

The skill teaches your assistant:

  • All CLI commands (geocode, reverse, distance, distance-matrix, distance-jobs, lists)
  • Output format flags (--json, --agent) and when to use each
  • Batch processing workflows and file size limits
  • Data append fields (timezone, congressional district, census, etc.)
  • Common multi-step workflows like geocoding a CSV and downloading results

Usage

Once installed, the skill activates automatically when you ask your assistant to geocode, look up an address, calculate distances, or process a spreadsheet. No special syntax needed.

Example prompts:

  • "Geocode this list of addresses and save the results as JSON"
  • "What congressional district is 1600 Pennsylvania Ave in?"
  • "Calculate driving distances from our warehouse to these 50 customers"
  • "Upload this CSV and geocode the addresses in columns B and C"

Skill Source

The skill definition is in skills/geocodio/SKILL.md.

Development

Building

# Build binary to ./bin/geocodio
make build

# Install to your $GOPATH/bin
make install

Testing

Tests use go-vcr to record and replay HTTP interactions. This lets tests run without hitting the live API.

Run tests:

make test

Run tests with coverage:

make cover

This generates a coverage report at coverage.html.

VCR Cassettes

Tests replay recorded API responses from "cassette" files stored in internal/api/testdata/. This approach:

  • Makes tests fast and deterministic
  • Avoids API rate limits and costs during development
  • Allows tests to run without an API key

Recording new cassettes:

When adding new tests or updating existing ones, you'll need to record fresh API interactions:

GEOCODIO_API_KEY=your-real-key make record-cassettes

Important

API keys are automatically redacted from recorded cassettes, so they're safe to commit.

How VCR works in this project:

  1. When VCR_MODE=record is set, tests make real API calls and save responses to YAML cassette files
  2. During normal test runs, requests are matched against recorded cassettes and replayed
  3. The matcher ignores API keys, so cassettes work regardless of which key was used during recording
  4. If a cassette doesn't exist and VCR_MODE isn't set to record, the test is skipped

Adding a new test with VCR:

func TestNewEndpoint(t *testing.T) {
    client := newTestClient(t, "new_endpoint")

    // Make your API call
    resp, err := client.SomeMethod(ctx, req)

    // Assert results
    require.NoError(t, err)
    assert.Equal(t, expected, resp)
}

Then record the cassette:

GEOCODIO_API_KEY=your-key VCR_MODE=record go test -v -run TestNewEndpoint ./internal/api/...

Smoke Testing

The unit tests use recorded VCR cassettes and don't hit the live API. To verify that the CLI works end-to-end against the real Geocodio API, run the smoke test:

GEOCODIO_API_KEY=your-real-key ./scripts/smoke-test.sh

This exercises every command (geocode, reverse, distance, distance-matrix, distance-jobs, lists) with various flag combinations, output formats, and error cases. It also runs lifecycle tests that create and delete distance jobs and spreadsheet uploads.

Note

The smoke test makes real API calls, which may count against your usage. It creates temporary resources (distance jobs, spreadsheet uploads) that are automatically deleted during the test run.

Linting

make lint

Requires golangci-lint.

Cleaning Up

make clean

Troubleshooting

"API key required"

You haven't set your API key. Either:

export GEOCODIO_API_KEY=your-api-key

Or pass it directly:

geocodio geocode "address" --api-key your-api-key

"batch size exceeds maximum of 10,000"

Geocodio's batch endpoints accept a maximum of 10,000 items per request. Split your file into smaller chunks:

split -l 10000 large_file.txt chunk_
for f in chunk_*; do geocodio geocode --batch "$f"; done

"invalid coordinate format"

Reverse geocoding expects coordinates in lat,lng format:

# Correct
geocodio reverse "38.8976,-77.0365"

# Incorrect
geocodio reverse "38.8976 -77.0365"  # Missing comma
geocodio reverse "-77.0365,38.8976"  # Longitude first (should be latitude)

Debugging API Issues

Use the --debug flag to see the full HTTP request and response:

geocodio geocode "1600 Pennsylvania Ave" --debug

Colors Not Displaying

If you're not seeing colored output:

  1. Make sure you're running in a terminal (not piping output)
  2. Check that NO_COLOR isn't set in your environment
  3. Try using FORCE_COLOR=1 to force color output

Migrating from v1.x

If you're upgrading from the previous Geocodio CLI (v1.x), here are the breaking changes:

v1.x v2.x Notes
geocodio create file.csv "{{A}}" geocodio lists upload file.csv --direction forward --format "{{A}}" --direction is now required (forward or reverse)
geocodio status 123 geocodio lists status 123 Commands are grouped under lists
geocodio download 123 > out.csv geocodio lists download 123 --output out.csv Use --output flag instead of shell redirect (stdout still works too)
geocodio remove 123 geocodio lists delete 123 Renamed for consistency
geocodio list geocodio lists list Grouped under lists
--follow --watch Flag renamed
--apikey / -k --api-key Flag renamed (env var GEOCODIO_API_KEY unchanged)
--hostname / -n --base-url Flag renamed

License

MIT

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

Geocodio CLI v2.0.0 Latest
Apr 7, 2026

Packages

 
 
 

Contributors

Languages