Matching engine E.3

Routes

Besides stops, the engine compares whole public transport lines: which lines exist on both sides, and whether their directions serve the same stops in the same order. This chapter explains the route model and how the comparison works. Route evidence is also used earlier, as one of the stop-matching rules (E2.3); this chapter is about comparing the routes themselves.

The route model Both sides are normalized into the same three levels: a line family, its itineraries (one per direction or variant) and each itinerary's ordered stop calls. On the GTFS side these are built from the timetable; on the OSM side they come from route_master and route relations. Families are matched first: two families that carry the same GTFS route id, or have the same mode and line number, are matched when one itinerary of each has the same stops in order, and a family can have several matches. Itineraries are paired inside each match: their directions must not disagree and at least 80 percent of the longer stop list must be shared in order. In the example, four of five stops align, which is exactly 80 percent. GTFS SIDE the timetable OSM SIDE PTv2 relations Line family GTFS route_id 31-B-j26-1 Line family route_master ref=31 Itinerary direction 1 → Bahnhof Itinerary direction 0 → Spital Route relation direction 0 → Spital Route relation direction 1 → Bahnhof A Seeplatz A Seeplatz B Post B Post C Schule X Kirche D Markt D Markt E Spital E Spital Stop calls, in order Stop calls, in order family match itinerary match 1 2 4 of 5 stops in order: 80% 1 Families with the same GTFS route id, or the same mode and line number, match when one itinerary of each has the same stops in order. A family can have several matches. 2 Itineraries pair only inside a match: directions that do not disagree, and at least 80% of the longer stop list shared in order. Stop calls are the same stop when they are at the same platform or, failing that, the same station.

Both sides are brought into the same three levels, so they can be compared level by level:

Level Source side (rebuilt from GTFS) OSM side (PTv2)
Line family: one line A GTFS route_id A group of route relations, such as the members of a route_master (grouping order)
Itinerary: one direction or variant A bucket of trips with the same direction and headsign (Swiss), or with the same direction and stops (generic GTFS adapter) One type=route relation
Stop call: one stop, in order A stop of the bucket's most frequent pattern A stop member of the relation

Families are matched first (1 in the figure). The itineraries of the families that could be the same line, named by a GTFS route identifier or sharing mode and line number, are compared, and the families whose stops agree are matched; the identifier alone matches a family whose relations list too few stops. A family can have several matches, because the timetable splits one line into several routes and OSM can hold a line twice. Itineraries are then paired inside each match (2): their directions must not disagree and enough of their stops must coincide in order. The example pairs two itineraries that share four of five stops, exactly the 80% minimum.

The three stages

  1. Adapters produce source-specific route products: the Swiss products rebuilt from GTFS (E1.2) and the OSM route products built from the current XML (E1.3).
  2. Normalisation: after stop matching, osm_public_transport_matcher.routes.compare_routes() converts both into shared line_families, itineraries and stop_calls, resolving each OSM stop call to a source stop where possible.
  3. Matching: it builds line_family_matches and itinerary_matches and returns them, with the products, for the bundle's routes section.

The comparison reads no files: src/osm_public_transport_matcher/routes.py receives DataFrames from the adapters and returns a complete payload. In the Swiss runner, the source products may come from verified cache files, while the OSM products are always rebuilt from the run's own XML. The review application imports the results; it never compares sequences or chooses links itself.

The comparison produces no problems. A line or itinerary without a counterpart is a family or itinerary without a match row, and stops that differ lower a pair's stop_score; neither appears in the problem list.

Route products appear in two places, for two different jobs:

Consumer Uses Purpose
Stop matching Route memberships per stop, through SourceState, OsmState and RouteState Evidence that two nearby stops are the same (E2.3)
Route comparison Complete families, itineraries and stop calls, in routes.py Which lines and directions correspond (E3.2)

One set of source products

Every source adapter delivers the same three products: source_routes, source_itineraries and source_stop_calls. The generic GTFS adapter keys them by feed namespace and keeps ordered calls and repeated visits of the same stop; the Swiss integration resolves each stop call to its ATLAS platform. Dataset-specific rules stay with the integrations: the Swiss route-year normalisation and the Swiss timetable form of line numbers, for example, come from the Swiss integration, not from routes.py.