distance-calculation-cli

Compute drive distance and drive time between US addresses, one pair at a time or in bulk from a CSV of origin/destination pairs.

• Geocoding: US Census Geocoder (free, keyless, TIGER-based), with OpenStreetMap Nominatim as a fallback for addresses Census can't match.
• Routing: OSRM — the public demo server by default (politely throttled), or a self-hosted local containerized OSRM instance for large batch jobs.

Quickstart

uvx distance-calculation-cli "1 Campus Martius, Detroit, MI" "300 Ottawa Ave NW, Grand Rapids, MI"

Routing via: https://router.project-osrm.org (public demo server, throttled)
Origin matched: 1 CAMPUS MARTIUS, DETROIT, MI, 48226
Destination matched: 300 OTTAWA AVE NW, GRAND RAPIDS, MI, 49503
Distance: 157.5 miles
Drive time: 2h 56m

Batch mode:

uvx distance-calculation-cli --csv addresses.csv -o results.csv

Installation

uv tool install distance-calculation-cli
# or, one-off:
uvx distance-calculation-cli ...

CSV format

Input CSV must have (at minimum) an origin and destination address column, named origin_address / destination_address by default (override with --origin-col / --destination-col):

Any other input columns are preserved as-is. The output CSV adds:

Rows are written incrementally as they complete (crash-safe, bounded memory), with a progress bar when running in a terminal. Failed rows are flagged, never dropped.

Status reference

Options

Routing server resolution order

1. --osrm-url flag
2. DISTANCE_CLI_OSRM_URL environment variable
3. Probe http://localhost:5000 for a running local OSRM instance
4. Fall back to the public router.project-osrm.org demo server

A loopback server is used unthrottled; the public server is capped at 1 request/second; any other custom URL is throttled by default (use --no-throttle if you know it can take more). The CLI prints which server it's using at startup, e.g. Routing via: http://localhost:5000 (local OSRM, unthrottled).

Rate-limit etiquette

The Census geocoder and the public OSRM demo server are free, shared, keyless services — please be a good citizen. For a few one-off lookups the defaults are fine. For tens of thousands of pairs, run a local OSRM instance (see below) and consider a --cache-dir for geocoding.

Nominatim's usage policy requires a descriptive User-Agent identifying your application; without one (--nominatim-user-agent or DISTANCE_CLI_NOMINATIM_UA), the Nominatim fallback is disabled and a warning is printed — Census-only results still work, just with a lower match rate.

Local OSRM (for large batches)

For workloads of tens of thousands of pairs, run OSRM locally instead of hammering the public server:

distance-calculation-cli osrm setup us/michigan   # download + process (one-time)
distance-calculation-cli osrm start us/michigan   # runs osrm-routed in a container
distance-calculation-cli "..." "..."              # auto-detects localhost:5000
distance-calculation-cli osrm status
distance-calculation-cli osrm stop

REGION is a Geofabrik path fragment, e.g. us/michigan. Michigan is a good first example — small, fast to process. us-latest (the whole US) needs 64GB+ of RAM to process and requires --yes to proceed. Requires a container engine — Podman is preferred if installed, otherwise Docker (override with --engine or DISTANCE_CLI_CONTAINER_ENGINE). Data is stored under ~/.local/share/distance-calculation-cli/osrm/.

Once a local OSRM instance is running, it's auto-detected via a health probe of localhost:5000 — no extra flags needed.