duckosm 0.3.0

OpenStreetMap → a routable road network in one DuckDB file,
with edge IDs that survive every rebuild, clip and export.

Documentation · Your first network · Guides · Database schema · Query the database

Why duckOSM

Most OSM-to-network tools number their edges 0, 1, 2, …, so the numbers change whenever you rebuild, cut out an area or export, and every table keyed on them has to be matched again. duckOSM's edge_id is a content hash of three ids that OpenStreetMap already gives the road segment: the OSM way it comes from (osm_id) and the OSM nodes where it starts and ends (source, target):

edge_id = hash(osm_id, source, target)

The order of source and target is the direction, so the two directions of a two-way street get different ids. None of the three is a number duckOSM makes up, so the id stays the same across rebuilds, clips and exports (details).

Quick start

pip install "duckosm[routing]"

curl -LO https://download.geofabrik.de/europe/monaco-latest.osm.pbf
duckosm build --pbf monaco-latest.osm.pbf --output monaco.duckdb --modes driving

import duckdb
from duckosm import route

con = duckdb.connect("monaco.duckdb", read_only=True)
q = "SELECT min(edge_id) FROM driving.edges WHERE name = ?"
a = con.execute(q, ["Boulevard du Larvotto"]).fetchone()[0]
b = con.execute(q, ["Avenue Princesse Grace"]).fetchone()[0]

r = route(con, a, b)                     # fastest path; weight="length" for distance
r["time_s"], r["length_m"], r["edges"]   # ~114 s, ~1.5 km, the ordered edge_ids

What you get

• A driving, a walking and a cycling network in one file, one schema each, split at the same junctions so a road has the same edge_id in every mode. OSM access tags are respected: private roads are kept for the map but never routed (details).
• The graph of legal turns (edge_graph), with OSM turn restrictions, for routing in SQL, Python or networkx.
• Base-map layers (features.*: water, land use, buildings, POIs) in the same file.
• Maps in one offline HTML page: duckosm viz draws the network and the base map from the database; duckosm route-map is a route planner (drive, walk, cycle, walk + drive) where you drag a start and an end and get turn-by-turn directions (try it). The pages are drawn by mapstyle.
• The drawing order of the roads: duckosm levels stores which road is painted over which (casing and fill numbers) in the file (how).
• Any area: a GeoJSON boundary, a place name, a box or an H3 cell; duckosm boundary finds an area's border by name, and duckosm extract cuts a city out of a country build in seconds.
• Your own fixes for OSM errors, applied on every build (how).

Exports

Experimental: OpenDRIVE, Lanelet2, railML, lane-level routing, GMNS meso/micro, intermodal routing, elevation, admin boundaries, base-map layers. See the documentation.

For AI agents

• To use duckOSM: the agent skill skills/duckosm/SKILL.md (also a Claude Code plugin: /plugin marketplace add Khoshkhah/duckOSM), and the whole documentation as one text file: llms-full.txt (llms.txt is its index).
• duckosm info DB --json says what a database holds; way, route-lanes and gis-debug also take --json.
• To change duckOSM: the rules are in AGENTS.md.

License

MIT. duckOSM is built on DuckDB and its spatial extension; it is an independent project, not affiliated with or endorsed by the DuckDB Foundation.