geo-connectivity

Turn a location — a lat/lon or a site polygon — into a connectivity profile. It pulls the road and transit network around a site from OpenStreetMap, classifies and de-duplicates it into a clean spec, computes drive-time isochrones and point-to-point drive times via OSRM / OpenRouteService, and ships print-ready map styling. Every result is honest about whether it's a real routed answer or a stamped approximation.

This is the reusable geospatial core extracted from a location-analysis tool — the data layer, no proprietary rendering.

---

Why it's interesting

• A connectivity spec, not just a pile of ways. build_connectivity_spec(lat, lon, radius_m=...) fetches roads + transit from Overpass, classifies each road into a tier (expressway / arterial / local), de-duplicates OSM's fragmented ways (the same road arrives as dozens of segments) via merge_roads, and returns structured main_roads / internal_streets / transit.
• An adaptive "step back to the bounding roads" radius. A fixed radius either misses the arterials that actually define a site's access or drowns it in local streets. The window widens until at least one primary road (rank ≤ 3) is in view in each compass quadrant, so the major arterials that frame a site (which can sit 1.5–2.6 km out) are never clipped.
• Honesty contract on drive times. drivetime.matrix() / route() call OSRM; if routing is unavailable they fall back to a haversine × detour-factor estimate — but the result is stamped approximate rather than silently passed off as routed. Results are cached on disk (sha256 key) so repeated matrices are free.
• Resilient free infrastructure. Overpass calls rotate across public mirrors with a per-query time budget (ConnectivityTimeout); isochrones use OpenRouteService when keyed and fall back to a geometric circle otherwise. No paid API is required to get a usable answer.
• Cartography that survives real basemaps. connectivity_style encodes a three-tier road palette engineered for value-contrast (dark casing under a high-luminance core) so the network stays legible on satellite and near-black imagery, plus adaptive label placement along the longest visible segment of each road.

Modules

geo_connectivity/
├── connectivity.py         OSM roads+transit -> classified, de-duplicated connectivity spec
│     build_connectivity_spec() · parse_roads() · merge_roads() · fetch_overpass() (mirror fallback)
├── drivetime.py            OSRM/ORS drive-time matrix + routes, disk-cached, honest approx fallback
│     matrix() · route() · isochrone()
├── isochrone.py            reachability polygons: true ORS isochrone, or a geometric circle fallback
│     make_isochrone() · isochrone_ors() · isochrone_circle()
└── connectivity_style.py   print-ready cartography: road tiers, basemaps, markers, label placement

Usage

from geo_connectivity import connectivity, drivetime, isochrone

# 1. Connectivity profile around a site
spec = connectivity.build_connectivity_spec(lat=24.7136, lon=46.6753, radius_m=4000)
for road in spec["main_roads"]:
    print(road["name"], road["level"], road["rank"])

# 2. Drive time from the site to a set of destinations (OSRM, cached)
m = drivetime.matrix(origin=(24.7136, 46.6753),
                     dests=[(24.63, 46.72), (24.77, 46.64)])
print(m)   # minutes/km per destination, flagged approximate if routing was unavailable

# 3. A 15-minute drive-time reachability polygon
iso = isochrone.make_isochrone(lat=24.7136, lon=46.6753, minutes=15)

Configuration

All optional — the library works against public endpoints out of the box (see .env.example):

Env var	Purpose	Default
OSRM_BASE	OSRM routing server	public demo server
ORS_BASE / ORS_API_KEY	OpenRouteService (true isochrones)	falls back to circle if unset

Data sources: OpenStreetMap (Overpass), OSRM, OpenRouteService — all public.

Tech stack

Python · requests · OpenStreetMap / Overpass · OSRM · OpenRouteService

License

MIT — see LICENSE.