About the Bike Map of Madison

Overview

The page is a static site (Mapbox GL JS, hosted on GitHub Pages). The bike network is a Mapbox vector tileset built from an OSM extract; a scheduled GitHub Action re-pulls the data, re-classifies it, and re-publishes the tileset. Nothing is hand-drawn: if a segment looks wrong, the fix belongs in OSM. The pinned segment card has "View on OSM" and "Edit" links for the underlying way, and corrections show up after the next refresh (plus tile cache expiry).

• Scope: everything Overpass places inside the Dane County boundary relation (relation 1799444).
• Unit of data: one feature per OSM way, with its geometry unmodified. Ways are not merged, split, or clipped.
• Classification is derived from tags by the rules below, but the raw tags we use are carried through to every feature so you can verify any call from the hover card.

Extraction query

Overpass QL, run against the area derived from the county relation (3600000000 + 1799444). It selects candidate ways with any tag that could indicate bicycle infrastructure, and the classifier then decides what each one is.

[out:json][timeout:300];
area(3601799444)->.a;
(
  way["highway"="cycleway"](area.a);
  way["highway"~"^(path|footway|pedestrian|bridleway|track)$"]["bicycle"="designated"](area.a);
  way["highway"]["cycleway"~"^(lane|track|shared_lane|share_busway|shoulder|opposite|opposite_lane|opposite_track|opposite_share_busway)$"](area.a);
  way["highway"]["cycleway:both"~"…same regex…"](area.a);
  way["highway"]["cycleway:left"~"…same regex…"](area.a);
  way["highway"]["cycleway:right"~"…same regex…"](area.a);
  way["highway"]["bicycle_road"="yes"](area.a);
  way["highway"]["cyclestreet"="yes"](area.a);
);
out tags geom;

/* curated route relations, from pipeline/signed_routes.txt */
rel(id:3896886,11242307,…)->.sr;
.sr out body;
way(r.sr)(area.a);
out tags geom;

The first block selects ways by tag. The second adds the member ways of a short, hand-picked list of route=bicycle relations (see Signed routes). Nodes and all other relations are not used. Results come from the public Overpass API with fallback endpoints; the job retries and fails rather than publishing a partial pull (see Refresh pipeline).

Classification

Each candidate way receives at most one class. A way never appears twice, even when cycleway:left and cycleway:right differ: the best-protected value wins and the raw per-side tags are kept as properties.

Exclusions

Dropped before classification, regardless of other tags:

Not excluded: access=customers/permissive/destination and similar, bicycle=permissive, and surface type. Unpaved paths are included; surface is shown on the card.

Decision procedure

First match wins. Steps are evaluated in this order:

1. highway=cycleway → permit when fee=yes or access=permit; otherwise path if the way's name is on the curated trail list; otherwise cycleway.
   facility (display label): foot ∈ {yes, designated, permissive} and segregated=yes → "Segregated shared-use path"; foot in that set otherwise → "Shared-use path"; else "Bike path". Any cycleway* tags on a cycleway are ignored.
2. highway ∈ {path, footway, pedestrian, bridleway, track} with bicycle=designated → path if the name is on the curated list, otherwise pathway (facility "Designated path"). No fee/permit distinction is made here.
3. Road-side facilities. Read cycleway, cycleway:both, cycleway:left, cycleway:right, map each value through the table below, and take the lowest-rank (best protected) class found.
4. Signed ways with no other facility. If the way is signed (see below) and steps 1–3 found nothing, it becomes route (facility "Signed route"). A signed way that does have a facility keeps that class: a cyclestreet with cycleway=lane is a lane that is also signed.
5. Otherwise the way is not part of the network.

Signed routes

"Signed or Well-Known Route" is an overlay on top of the classes, not a class you have to be limited to. A way is signed when either of these is true:

• it carries bicycle_road=yes or cyclestreet=yes; or
• it is a member way of a relation listed in pipeline/signed_routes.txt (the Lake Loop and the city's bicycle boulevards at the moment). Relations tagged state=proposed are skipped.

Signed ways get signed=1 and, for relation members, routes with the relation names. A signed way keeps its normal class (shared lane, trail, and so on) and the map adds a glow behind it. Only a signed way with no other bike facility gets class route, drawn as a dotted line. Local trail and greenway relations (Fitchburg, Middleton, the state trails) are intentionally not in the list: those paths are already Bike Trail or Off-Street Bike Lane.

Curated trail list

"Bike Trail or Path" is deliberately narrow: it is for well-known, named trails (the Southwest Path, Capital City State Trail, Cannonball Path, and so on), not for every highway=cycleway. Membership is decided by a hand-maintained allowlist, pipeline/trail_names.txt.

• A way is a path when it qualifies in step 1 or 2 and its name tag equals a list entry (exact match, case-insensitive, whitespace-normalised). Only name is consulted; alt_name, official_name, and route relations are not.
• Every other off-street way falls back to cycleway (a highway=cycleway) or pathway (a designated path/footway/…), which the map draws as "Off-Street Bike Lane".
• Permit-required cycleways are permit regardless of the list.
• The file ships with the included names plus a commented-out candidate list of every other named off-street way found when it was written, with lengths. Add a name, or uncomment one, and run the refresh workflow to apply it. The list is static: new names that appear in OSM won't be picked up on their own.

cycleway=* value mapping

Applies to step 3, for each of the four keys above.

Only the main cycleway* values are read. Subtags such as cycleway:left:lane=exclusive, :separation, :buffer, :segregated, and :width are not used for classification.

Classes and rank

rank orders classes by protection (lower is better). It decides which feature the hover card shows when lines overlap, and the label priority for route names.

Output data model

The tileset has one source layer, bike (LineString features, zoom 8–14), with one feature per OSM way. Route-name labels come from a separate file, described below. Feature properties on bike are the derived fields plus a pass-through of raw OSM tag values. Keys containing a colon are written with an underscore (cycleway:left → cycleway_left). Tag values are not normalised.

Label lines: data/bike-names.geojson

Used only for the route-name text along the lines. It is a small GeoJSON file the page loads directly, not part of the tileset (line labels placed unreliably on the vector tiles at z12–13, and the GeoJSON path doesn't have that problem). OSM often splits one trail into dozens of ways, and a line label needs a long enough continuous line, so the pipeline builds a second set of features:

• Features of the labeled classes (path, permit, cycleway, track, pathway) that have a name are grouped by name alone, so a trail that switches between, say, path and permit stays one line.
• Within a name, ways are joined end to end wherever exactly two ways share an endpoint. At junctions (three or more) the ways stay separate.
• Remaining pieces are then joined across small gaps (road crossings, short unnamed connectors): two line ends are connected when each is the other's nearest end and they are within 60 m. The label line can therefore jump a gap that the real line doesn't have; it only affects where text can sit.
• Each merged line takes the class that covers most of its length. Properties: name, class, rank. There is no osm_id; this layer is not used for hover or click.

A data/manifest.json file is committed on each run with the OSM data timestamp (osm3s.timestamp_osm_base), per-class way counts and lengths, and a content hash.

Map categories and display rules

The map legend follows a print map's symbology, which groups the classes above:

• Below z10.5 only ways with a name tag are drawn; unnamed ways fade in from z10.5, and on-street categories from z11 (each fade spans 0.7 zoom levels).
• Route names are a separate symbol layer (from data/bike-names.geojson) along the line from z12, repeated every 250 px with bends up to 45°. On-street lane and shared categories are not labeled because their name is the street name, which the basemap already labels.
• County lines (dashed gray-blue, from z8) come from the Mapbox Streets admin layer (admin_level 2). They carry no county names, so every county border in view is drawn, not just Dane's. Panning is limited to the county plus a margin of about 5 km, so the minimum zoom depends on the window size (about z10 on a tall window).
• The legend checkboxes filter by class, so toggling a category also hides its labels.
• The mapping from class to legend category is a few lines of configuration in js/app.js (CATEGORIES); the tileset itself keeps all eight classes, so re-grouping needs no data refresh.

Refresh pipeline

1. A GitHub Action runs monthly (the 1st, 09:17 UTC) and can be started manually.
2. fetch_osm.py runs the query above, trying up to three Overpass endpoints with retries, then classifies every way. If fewer than 500 features come out, the run aborts rather than publishing a suspect pull.
3. Features are written as line-delimited GeoJSON, sorted by osm_id, with coordinates rounded to 7 decimals. A SHA-256 of that file is compared with the previous run. The merged label lines are written separately.
4. If the content changed (or the run is forced), the file replaces the tileset source and the Mapbox Tiling Service recipe is updated and published (source layer bike, zoom 8–14). Unchanged data is not re-published.
5. The manifest is committed back to the repository every run.

Known limitations

• "Well-known" is a hand-picked list. Trail membership depends on exact OSM name values, so a renamed or misspelled way, or a trail mapped without a name, falls back to Off-Street Bike Lane. About 150 mi of highway=cycleway in the 2026-10-21 extract had no name tag at all.
• Only listed route relations count. Of the roughly 110 route=bicycle relations in the county, only the few in pipeline/signed_routes.txt are read, and their member ways are used as mapped. A route relation that is incomplete or out of date in OSM shows up that way here.
• Separate sidepaths look like trails. A cycle track mapped as its own highway=cycleway beside a road is classified path; the track class only captures tracks tagged on the road way itself. No attempt is made to detect cycleway=sidepath, footway=sidewalk, or adjacency to a road.
• Subtags are ignored. Lane buffers, physical separation, and segregation subtags do not change classification.
• highway=path needs bicycle=designated. Paths with bicycle=yes or no bicycle tag are not included, and roads with bicycle=designated but no cycleway tags are not included.
• One class per way. Streets with different treatment on each side show the best side; the raw left/right tags are in the card.
• Geometry is not clipped to the county line, and ways are not merged, so long facilities appear as many features.
• Overpass lag. Data is as current as the public Overpass instance, typically minutes behind OSM, then up to a month behind the page.

Attribution

Bike network data © OpenStreetMap contributors, available under the Open Database License. Basemap © Mapbox.

Map and data pipeline by Stephen Kennedy of LATLONG.SHOP.