roadstyle

Beautiful, interactive road maps from Python.
One offline HTML file with real road cartography, Google Street View and a JavaScript API.

Install · Quickstart · Gallery · Live map · AI agents · Documentation

Why roadstyle

• Real road cartography. Casing and fill, widths that change with zoom, street names, one-way arrows, tunnels drawn under and bridges over, and optional 3D bridge decks.
• One offline file. Map, data and styling in a single HTML page: open it without a server, email it, or put it on any website.
• Street View built in. Click any road to see it in Google Street View, facing the way it runs.
• Any road data. A GeoDataFrame, a file, DuckDB, Arrow, osmnx or duckOSM.
• Colour by your data. Speed, traffic or any column, with a legend and a menu of colourings.
• Scriptable. A window.rs* JavaScript API and events for your own dashboard, and shared parts for its panel.
• Ready for AI agents. An MCP server and an agent skill.

What is new in 0.26.3

• A dashboard manual. Three pages with maps that run: an overview, the Python SDK and the JavaScript API. Each example has a Run button.
• The two directions of a two-way road are two halves of the road at every zoom. A colour on one direction does not hide the other.
• Fewer arrows on a tiled page, and correct arrows on a page with a vector base map. Monaco, zoom 16.5: 9 arrows, not 85.
• Street View: the coverage shows on any road, and the header of the window keeps the name of the road. duckosm.page draws the base map's textures and icons, and dashboard=False gives the dashboard without a panel.

What is new in 0.26.1

• One accent colour. The dashboard uses the Sonocount teal in the light and the dark theme, defined once. The corner box has the shape of the bar, a button with a text shows no tooltip box, and every tool of a phone's one-row bar can be reached.
• Street View docked, and a dashboard with no panel. street_view="dock" puts Street View beside the map with a divider that you drag. dashboard={"panel": None} gives a map with the toolbox only.
• Help and folding in the panel. rs.help.button adds a "?" button with its own words to a card or a label, all of them open one window. A Collapse all / Expand all control folds the panel's sections. The level editor has a "?" help window with two links to the levels guide.
• Fix: a page that starts in the dark theme no longer shows the error "Style is not done loading".

What is new in 0.26.0

• A standard dashboard and toolbox. rs.render_dashboard(edges) makes a map with one panel and one bar of tools: navigate (zoom, turn and tilt in one box), road filter, base maps, colour and legend, settings and credits. A tool that the page cannot use is grey, and its tooltip says why. The toolbox is at the right edge and the panel at the left. On a phone the bar is one row that you move sideways, and the panel is a bottom sheet.
• Seven base maps, no key. OpenFreeMap Liberty and Positron (the default), OpenStreetMap, Esri Gray, Esri Streets, Esri Satellite and Blank, each with its dark twin when it has one. The CARTO maps are gone, so no base map needs a key. The theme switch also turns the style's own layers dark.
• Tiles by default, one rule. Every page keeps its roads as MLT vector tiles to zoom 16, with one road layer for every zoom. The page, the browser worker, export_style and roadstyle tiles all use the same tiling rule. tiles=False gives GeoJSON roads, and tile_format="mvt" gives MVT.
• The level editor is in the panel. roadstyle levels edit AREA_DIR opens it from the Rust program. It uses the page's standard panel, with an apply bar, red and blue picks, the area boundary (levels make --boundary) and edits.csv in the History tab.
• Shared dashboard parts. Help window, hover box, tabs, number tiles, tables, charts and chips are in the panel's own look, in both themes. rs.classify makes colour classes for roads.

More: What is new in 0.26.3 · Dashboard layout · Dashboard parts · Big networks · Move a script from 0.25 · Documentation.

Install

pip install roadstyle              # core
pip install "roadstyle[all]"       # + studio, DuckDB, …

Python ≥ 3.10. Individual extras and the dev setup: Install.

Quickstart

From OpenStreetMap, no data needed. Any place, with osmnx (pip install osmnx):

import osmnx as ox
import roadstyle as rs

G = ox.graph_from_place("Tartu, Estonia", network_type="drive", simplify=False)
G = ox.simplify_graph(G, edge_attrs_differ=["bridge", "tunnel"])   # keep tunnels and bridges apart
rs.render_edges(ox.graph_to_gdfs(G, nodes=False)).save("tartu.html")

From your own data. Any file or GeoDataFrame with line geometry and a highway column:

import geopandas as gpd
import roadstyle as rs

edges = gpd.read_file("edges.gpkg")        # LineStrings + a `highway` column, any CRS
rs.render_edges(edges).save("map.html")    # open map.html: no server (Street View needs one)

More looks:

rs.render_edges(edges, basemap="ofm_dark", view_3d=True)                # dark, 3D bridge decks
rs.render_edges(edges, palette="carto", basemap="ofm_positron")        # the classic OSM look
rs.render_edges(edges, color_by="aadt", cmap="viridis")                # colour by your data
rs.render_edges(edges, palette="mono", color_options={                 # several colourings,
    "Traffic": {"color_by": "aadt", "cmap": "viridis"},                #   switched in the browser
    "Speed":   {"color_by": "maxspeed_kmh", "cmap": "magma"}})
rs.render_edges(edges, tiles=False)                                    # GeoJSON roads (MLT tiles are the default)
rs.render_dashboard(edges).save("dashboard.html")                      # map + panel + the standard toolbox
rs.render_street_view(edges).save("street_view.html")                  # map and Street View side by side

No Python? roadstyle edges.gpkg -o map.html --basemap ofm_dark, or click through it in the workbench: pip install "roadstyle[studio]" && roadstyle studio.

Gallery

The road map look rs.render_edges(edges)	Bridges and tunnels rs.render_edges(edges)	Colour by your data color_by="maxspeed_kmh"
3D bridges view_3d=True	Street View click a road	Dashboard rs.render_dashboard(edges)

Every look with its code: the gallery.

What goes in

Only geometry and highway are required. Other columns switch features on:

duckOSM (duckosm export-gis) exports exactly this, and osmnx edges work as they are: rs.render_edges(ox.graph_to_gdfs(G, nodes=False)).

Drive it from JavaScript

The saved page exposes window.rs* functions and rs:* events:

const ids = rsQuery(p => p.maxspeed_kmh > 30); // feature ids whose properties match
rsColor(ids, "#ff00aa");  rsFocus(ids);       // paint them, fit the camera
document.addEventListener("rs:select", e => console.log(e.detail.properties));

Every function and event: JavaScript API.

For AI agents

MCP server. Lets any MCP-capable AI app (Claude Code, Claude Desktop, Cursor, …) draw road maps without writing code: render_place("Tartu, Estonia"), render_file("roads.gpkg") and snapshot. Each saves an HTML map and returns its path plus a PNG preview the agent can look at.

claude mcp add roadstyle -- uvx roadstyle-mcp

{"mcpServers": {"roadstyle": {"command": "uvx", "args": ["roadstyle-mcp"]}}}

Claude Code plugin. The MCP server and the skill below in one install:

/plugin marketplace add Khoshkhah/roadstyle
/plugin install roadstyle@roadstyle

For agents that write code:

• skills/roadstyle/SKILL.md: a skill for agents that use roadstyle (the one call, the data contract, the JS API, the traps). Install it for Claude Code:

  mkdir -p ~/.claude/skills/roadstyle && curl -fsSL -o ~/.claude/skills/roadstyle/SKILL.md \
    https://raw.githubusercontent.com/Khoshkhah/roadstyle/main/skills/roadstyle/SKILL.md
  

• AGENTS.md: for agents working on this repo.
• llms.txt: the docs site as a link list for LLMs.

API keys

The key is optional. roadstyle works without it, just with less. The base maps need no key.

• Google Maps, for Street View. Street View works with no key. A key adds a Linked mode: a real panorama, with the map marker walking and turning with you.

rs.render_edges(edges, street_view_key="AIza…")         # the floating Street View window
rs.render_street_view(edges, street_view_key="AIza…")   # the side-by-side page

More: settings & base maps · Google Street View.

Documentation

khoshkhah.github.io/roadstyle, with live maps on every page.

Built on

• MapLibre GL JS (BSD-3-Clause) draws every web map: roadstyle writes its style and data, and a copy of MapLibre is inlined in each saved page so it opens offline.
• OpenStreetMap data (© OpenStreetMap contributors, ODbL) and the openstreetmap-carto style, whose road classes, colours and widths roadstyle follows.
• HiGHS, through SciPy, is the optional Python solver of which road is drawn on top. The default solver is in Rust.
• GeoPandas and Shapely for the geometry.

License

MIT. Base-map tiles come from third-party services (OpenFreeMap, OSM, Esri) with their own attribution and terms.