roadstyle

Road maps for Python: styled, interactive, offline HTML maps of road networks, with Google Street View.

Turn a GeoDataFrame of road edges into one styled, interactive, offline HTML map, with real road cartography (casing and fill, per-zoom widths, street names, one-way arrows, tunnels and bridges, optional 3D) and a JavaScript API for your own dashboard. Every map has a Street View button: click any road to see it in Google Street View, looking the way it runs.

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

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)

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.

API keys

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

CARTO, for the base map. The default base map (voyager) and positron and dark_matter come from CARTO. Without a key, their tiles are stamped API KEY REQUIRED. Get a free key at carto.com/basemaps/apikey, then use any one of these:

export CARTO_API_KEY="…"                                          # environment variable

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

Save that JSON as ~/.config/roadstyle/roadstyle.json, or as roadstyle.json in the folder you run from. In Python you can pass rs.render_edges(edges, api_key="…") instead. With no key at all, use a keyless base map: esri_street, esri_dark_gray, osm or blank.

Google Maps, for Street View. Street View works with no key: the keyless Google embed. With a Google Maps JavaScript API key, the Street View panel and window get a Linked / Classic switch. Linked is a real panorama: the map marker walks and turns with you, and only Google's own street photos are shown. Classic is the keyless embed. To get a key:

1. In the Google Cloud console, create a project and enable Maps JavaScript API (Google asks for a billing account on the project).
2. Under APIs & Services > Credentials, create an API key.
3. Restrict it: Application restrictions = Websites, listing your site's addresses (e.g. https://example.com/*); API restrictions = Maps JavaScript API only.

Then pass it in:

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

The key is written into the page, as every browser key is, so the site restriction in step 3 is what protects it. It also means Linked works only on the addresses you listed: to try it on localhost, add http://localhost:*/* to the list. Keep the key out of git, for example in an environment variable.

More: settings & base maps · Google Street View.

What goes in

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

duckOSM (duckosm export-gis) exports exactly this.

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 coding agents

• 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.

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.