Matching engine E.3
Routes
On this page
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.
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
- 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).
- Normalisation: after stop matching,
osm_public_transport_matcher.routes.compare_routes()converts both into sharedline_families,itinerariesandstop_calls, resolving each OSM stop call to a source stop where possible. - Matching: it builds
line_family_matchesanditinerary_matchesand returns them, with the products, for the bundle'sroutessection.
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.
Related pages
- E3.1 Route data flow: the tables at each stage
- E3.2 Route-route matching: how families and itineraries are paired
- E1.2 GTFS and ATLAS and E1.3 OSM data: the route inputs
- A1.1 Bundle import and publication and A2.6 Routes pages: how the review application stores and shows routes