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 · 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.
• Ready for AI agents. An MCP server and an agent skill.

Install

pip install roadstyle              # core
pip install "roadstyle[all]"       # + studio, numeric ramps, vector tiles, lonboard, 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="dark_matter", view_3d=True)            # dark, 3D bridge decks
rs.render_edges(edges, palette="carto", basemap="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=True)                                     # 100k+ edges
rs.render_dashboard(edges).save("dashboard.html")                      # map + query sidebar
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 dark_matter, or click through it in the workbench: pip install "roadstyle[studio]" && roadstyle studio.

Gallery

The defaults rs.render_edges(edges)	Dark basemap="dark_matter"	3D bridges view_3d=True
Colour by your data color_by="maxspeed_kmh", cmap="plasma"	Satellite basemap="satellite"	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 --from "roadstyle[mcp]" roadstyle-mcp

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

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

Both keys are optional. roadstyle works without them, just with less.

• CARTO, for the default base map. Without a key its tiles are stamped API KEY REQUIRED; set CARTO_API_KEY, or use a keyless base map (esri_street, esri_dark_gray, osm, blank).
• 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.

export CARTO_API_KEY="…"                                          # environment variable

{ "config": { "api_keys": { "carto": "…" } } }

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.

License

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