Metadata-Version: 2.4
Name: commute-estimate-hirewire
Version: 0.1.0
Summary: Straight-line distance + road drive-time estimates in one call, with a heuristic fallback.
Author: Kat
License: MIT
License-File: LICENSE
Keywords: commute,distance,drive-time,geocoding,openrouteservice,routing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: httpx>=0.28; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: routingpy>=1.3.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: geocode
Requires-Dist: httpx>=0.28; extra == 'geocode'
Provides-Extra: ors
Requires-Dist: routingpy>=1.3.0; extra == 'ors'
Description-Content-Type: text/markdown

# 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`**.

```python
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

```bash
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:

```python
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:

```python
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
