traffic-cli

A small command-line tool that calculates the driving (or cycling/walking) travel time between two locations using a routing API of your choice.

$ traffic "las vegas" "los angeles"
From: las vegas (Las Vegas, Clark County, Nevada, United States)
To:   los angeles (Los Angeles, Los Angeles County, California, United States)
Travel time: 3 hours, 58 mins

Locations can be place names, addresses, or postcodes. Geocoding is done via OpenStreetMap's Nominatim; routing is delegated to a provider you configure (OpenRouteService, GraphHopper, Mapbox, Google Maps, or TomTom).

Installation

Requires Python 3.10+.

pipx install traffic-cli      # recommended (isolated install)
# or
pip install traffic-cli
# or, with uv
uv tool install traffic-cli

Setup

You need a free/paid API key from one of the supported routing providers, then run init once:

traffic init <provider> <api_key> [profile]
# e.g.
traffic init ors YOUR_API_KEY car

If you run traffic before initialising, it will prompt you interactively.

Configuration is stored at ~/.traffic/config.json.

Supported providers

Travel profiles

Each provider supports three generic profiles: car (default), bike, and walk. Set your default with:

traffic set profile bike

Usage

traffic <origin> <destination>
traffic <origin> to <destination>

Examples:

traffic california nevada
traffic "las vegas" california
traffic las vegas to california
traffic home work                  # using saved variables (see below)
traffic --country gb b46 cv7       # bias geocoding to a country
traffic --home London --destination Paris

Saved variables

Save frequently used locations as named shortcuts:

traffic set home "10 Downing Street, London"
traffic set work "Buckingham Palace, London"
traffic home work

Country bias

If a place name is ambiguous, bias geocoding to a country with --country (alias --cc), or set a default. You can pass an ISO code (gb), a country name (france), or a common alias (uk, england, usa):

traffic --country gb birmingham coventry
traffic --country england b46 b9
traffic set country gb

Tip: short, bare UK outward codes like b9 are ambiguous even within a country (they also match B-roads). Use a full postcode (B9 4AA) or add a town ("B9, Birmingham") for a precise result.

Output formats

Routing options:

Waybar

The --json output is designed to drop straight into a Waybar custom module:

"custom/traffic": {
    "exec": "traffic --json home work",
    "return-type": "json",
    "interval": 300
}

Commands

Notes

• Geocoding uses OpenStreetMap's public Nominatim service. Requests are rate-limited to ~1/second and cached per invocation to respect its usage policy.
• API usage (and any billing) is governed by whichever routing provider you configure.