commute-estimate-hirewire 0.1.0

Straight-line distance + road drive-time estimates in one call, with a heuristic fallback.

commute-estimate-hirewire

Straight-line distance and road drive-time in one call — with a pure-Python heuristic fallback so it always returns an answer, even with no API key and no network.

Installed as commute-estimate-hirewire; imported as commute_estimate.

from commute_estimate import estimate_commute

est = estimate_commute((37.14, -122.07), (37.34, -121.89))
est.straight_line_miles   # 16.9  — great-circle, always present
est.drive_minutes         # 38.0  — road minutes (ORS) or heuristic
est.method                # "ors:driving-car" | "heuristic" | "haversine_only"

Coordinates are (lat, lon) tuples throughout.

Install

pip install commute-estimate-hirewire            # core only (heuristic distance/time)
pip install "commute-estimate-hirewire[ors]"     # + real road routing via OpenRouteService
pip install "commute-estimate-hirewire[geocode]" # + address -> coordinates via Nominatim
pip install "commute-estimate-hirewire[ors,geocode]"

Drive time

• With an OpenRouteService key (free at https://openrouteservice.org/dev): set ORS_API_KEY in the environment (or pass api_key=) and install the [ors] extra. method becomes "ors:driving-car" — real road network (traffic-free).
• Without a key: drive time falls back to straight_line_miles × detour_factor ÷ avg_speed (defaults: 1.3 and 35 mph, both tunable). method is "heuristic".
• A routing/network failure silently degrades to the heuristic — estimate_commute never raises.

One origin, many destinations

estimate_matrix resolves a whole one-to-many set in a single ORS request — ideal for building a distance table:

from commute_estimate import estimate_matrix

home = (37.14, -122.07)
sites = [(37.34, -121.89), (37.80, -122.27)]
for est in estimate_matrix(home, sites):
    print(est.straight_line_miles, est.drive_minutes, est.method)

Geocoding (optional)

commute_estimate.geocode.Geocoder turns an address/place string into coordinates via OpenStreetMap Nominatim (no key), with optional on-disk caching and graceful misses:

from commute_estimate.geocode import Geocoder

geo = Geocoder(cache_path="geocode_cache.json")   # caching optional
coord = geo.geocode("San Jose, CA")               # (lat, lon) or None

License

MIT