mapstyle

A whole OpenStreetMap map in one offline HTML page:
the roads for driving, walking and cycling over a full base map, from one duckOSM database.

Documentation · Live map · Get started · Gallery · JavaScript API

Quick start

pip install "duckosm @ git+https://github.com/Khoshkhah/duckOSM" \
            "mapstyle @ git+https://github.com/Khoshkhah/mapstyle"

curl -LO https://download.geofabrik.de/europe/monaco-latest.osm.pbf
duckosm build --pbf monaco-latest.osm.pbf -o monaco.duckdb \
              -m driving -m walking -m cycling
mapstyle monaco.duckdb          # -> monaco_all.html: one file, opens offline

import mapstyle as ms

ms.render_map("monaco.duckdb").save("monaco.html")                    # the whole map
ms.render_map("monaco.duckdb", mode="walking", paths="komoot")        # paths in front
ms.render_map("monaco.duckdb", planner=True).save("planner.html")     # + a route planner
ms.render_map("monaco.duckdb", dashboard=True).save("dashboard.html") # a dashboard

What you get

• Every travel mode on one map, or one brought to the front: all, driving, walking, cycling; and four looks for paths (google, osm, komoot, cyclosm).
• A full base map from the same database: the sea, land use with openstreetmap.org's textures, water, buildings, railways, parking, transit, traffic lights and crossings. No tile server, no API key.
• Roads drawn right at junctions: two-way roads as two lanes, bridges over, tunnels under only where they really pass under a road, raised walkways, crossings over their street.
• A route planner in the page: drive, walk, cycle or walk + drive, fastest or shortest, with turn-by-turn directions.
• A dashboard: filter by mode, road class and layer, colour by mode, inspect what you click.
• A JavaScript API: every page is a roadstyle page (rsQuery, rsFilter, rsColor, …) plus rsSetModes, rsSetKinds and rsSetInteraction; 3D, Street View and vector tiles for large areas come with it.

Walking: paths in front	A raised walkway over a roundabout
The route planner	The dashboard

How it fits together

The look is data: four YAML files in src/mapstyle/styles/ (travel modes, path styles, colours, layers). See Styles.

Command line

mapstyle DB [-o OUT] [--mode {all,driving,walking,cycling}] [--paths {google,osm,komoot,cyclosm}]
            [--no-layers] [--planner] [--dashboard] [--tiles] [--basemap BASEMAP]

For AI agents

• Using mapstyle: the agent skill skills/mapstyle/SKILL.md has the install, the one call, the options, the JavaScript API and the traps in one page. In Claude Code: /plugin marketplace add Khoshkhah/mapstyle, then /plugin install mapstyle@mapstyle.
• The docs as text: llms.txt and llms-full.txt (every page, one file).
• Changing mapstyle: AGENTS.md has the commands and the project's rules.

More: AI agents.

Development

git clone https://github.com/Khoshkhah/mapstyle && cd mapstyle
python -m venv .venv && .venv/bin/pip install -e ".[dev,tiles]"
.venv/bin/pytest          # builds a Monaco database with a duckOSM checkout next to this one

Tests look for duckOSM in ../duckOSM (with its .venv), or wherever DUCKOSM_DIR / DUCKOSM_EXE point; MAPSTYLE_TEST_DB reuses a database you already built. Design notes are in docs/design/.

License

MIT. Map data © OpenStreetMap contributors (ODbL); the sea from Overture Maps, built from OpenStreetMap's coastline.