OSM Data

OpenStreetMap provides the stop geometry and route-relation side of the comparison pipeline.

The OSM downloader in matching_and_import_db/downloader/get_osm_data.py performs two distinct tasks:

1. fetch Swiss public-transport stop elements from Overpass
2. materialize route-master and route-relation CSVs that preserve the OSM PTv2 structure for later import

The same raw XML is also parsed by matching_and_import_db/state.py into OsmState, which keeps the stop attributes needed by the matching runtime.

Data Source

The downloader is intentionally fail-fast after retry exhaustion. If Overpass still returns a non-200 response, the OSM download step raises and the pipeline stops.

Node Selection Criteria

Way Ingestion Policy (not completed)

In addition to OSM nodes, the pipeline ingests a narrow subset of OSM ways as virtual stop elements.

Included way categories:

1. aerialway=station + public_transport=station
2. ways with uic_ref where no existing node already carries the same uic_ref

Kept ways are converted to virtual IDs (way_<osm_way_id>) and represented as point elements using out center from Overpass. These virtual IDs are treated like node IDs during grouping, stop matching, and route membership export.

Retained Stop Attributes

OsmState.from_xml_file() parses the raw XML into OsmNode entities. The runtime keeps the following stop-level attributes because the matching predicates and route export depend on them.

Route Artifacts Written to data/processed/

The downloader writes entity-first route tables that preserve the OSM PTv2 hierarchy.

osm_route_masters.csv

One row per type=route_master relation.

osm_route_relations.csv

One row per type=route relation. In practice this is the OSM-side itinerary or variant layer.

Tag and Membership Tables

Stop Rows Kept for Route Import

osm_route_relation_stops.csv is the OSM-side stop-call source for the route importer.

Direction Extraction

OSM route relations often carry a ref_trips tag with direction suffixes:

• .H suffix → outbound (direction_id = 0)
• .R suffix → inbound (direction_id = 1)

The downloader copies this value onto relation-member and relation-stop rows as direction_id_derived / direction_id when available.

For stop-level route matching, OsmState also expands route memberships without a detectable direction into both 0 and 1, so the RouteMatchPredicate can still fall back to route ID alone.

Key OSM Tags Used by the Matching Runtime

Overpass Query

The downloader issues a raw Overpass QL POST body with:

• requested timeout: 360 seconds ([timeout:360])
• configurable environment variables: OVERPASS_API_URL, OVERPASS_USER_AGENT, OVERPASS_MAX_RETRIES, OVERPASS_RETRY_BACKOFF_SECONDS

The query fetches:

• selected Swiss public-transport stop nodes
• selected Swiss way-based stop elements
• type=route relations that reference those elements
• parent type=route_master relations and their child route relations

Exact Overpass QL body:

[out:xml][timeout:360];
area["ISO3166-1"="CH"]->.searchArea;

(
  node(area.searchArea)["public_transport"~"platform|stop_position|station|halt|stop"];
  node(area.searchArea)["railway"="tram_stop"];
  node(area.searchArea)["amenity"="ferry_terminal"];
  node(area.searchArea)["amenity"="bus_station"];
  node(area.searchArea)["highway"="bus_stop"];
  node(area.searchArea)["railway"="halt"];
  node(area.searchArea)["railway"="station"];
  node(area.searchArea)["aerialway"="station"];
)->.pt_nodes;

(
  way(area.searchArea)["aerialway"="station"]["public_transport"="station"];
  way(area.searchArea)["uic_ref"];
)->.candidate_ways;

(
  relation(bn.pt_nodes)[type=route][route!=hiking];
  relation(bw.candidate_ways)[type=route][route!=hiking];
)->.seed_routes;

relation(br.seed_routes)[type=route_master]->.route_masters;

(
  .seed_routes;
  relation(r.route_masters)[type=route][route!=hiking];
)->.routes;

.pt_nodes out body qt;
.candidate_ways out body center qt;
.routes out meta;
.route_masters out meta;

Statistics

• OSM Nodes with Route Data: 33,714