Matching engine E.2.3
GTFS route matching
On this page
The GTFS route rule (gtfs_route, one of the matching rules) matches a source stop to a nearby OSM element when both are served by the same GTFS route in the same direction (gtfs_shared_route), or else share a GTFS direction name (gtfs_shared_direction). It runs before the purely distance-based rules, so that route evidence can separate stops that are close together, for example the two platforms on opposite sides of a road.
This is still stop-to-stop matching: routes are evidence that two nearby points are the same stop. Comparing whole routes is a separate step, described in E3.2 Route-route matching.
The evidence
The rule reads route evidence that the adapters prepared; it performs no file access.
| Side | Evidence | Source |
|---|---|---|
| Source stop | Its routes with direction: (route_id, direction_id) and the normalized (route_id_normalized, direction_id); also each itinerary's direction label, such as Zürich HB → Bern |
GTFS itineraries, through ctx.source.get_route_evidence(key) |
| OSM element | The OSM route relations it belongs to: (gtfs:route_id, direction) and its normalized form, plus the source route that RouteState maps the relation to |
OSM XML, through ctx.osm.get_node_routes(node_id) |
| OSM element | The direction names of those relations: the name of the first member, an arrow and the name of the last member | ctx.osm.name_dirs |
OSM directions come from the relation's ref_trips tag: a trip id ending in .H means direction 0, .R means 1. A relation without either suffix contributes tokens for both directions, so that the route identifier alone can still match.
Route identifiers are scoped and normalized by the adapters: the Swiss adapter replaces the timetable-year code (-j25) with -jXX, so an OSM tag entered in an earlier year still matches; a generic GTFS adapter prefixes identifiers with its feed namespace. When either side has no route evidence at all, the engine records a route_evidence_unavailable diagnostic and the rule matches nothing.
How the rule decides
Instead of deciding stop by stop, the rule first collects every candidate pair, then commits only unambiguous ones:
- Collect edges. For every unmatched source stop with route evidence, look at each unmatched, non-station OSM element within 50 m (
max_distance), except elements labelled with another platform. If they share route tokens, add a token edge whose score is the number of shared tokens. Otherwise, if they share a direction name, add a direction edge. - Keep mutual best token edges. An edge is kept when it is the single best-scoring edge of its source stop and of its OSM element. A tie for the best score keeps neither.
- Commit the kept edges as
gtfs_shared_route, strongest first. - Repeat with direction edges for the stops and elements still free, committing them as
gtfs_shared_direction. A direction name is weaker evidence than a route identifier, so it only decides what the token edges left open.
Everything else stays unmatched for the distance rules. Requiring the best choice from both sides prevents a greedy outcome in which the first stop processed takes an element that another stop has stronger evidence for.
Platform labels
A line can call at several platforms of one station. At Zürich HB, Löwenstrasse, the S-Bahn lines use tracks 31 to 34 depending on the time of day, so the platform with code 32 can share more routes with the stop position labelled local_ref=31 than with its own. There the routes say nothing about the platform, and the labels do.
When a candidate's local_ref equals the stop's platform code, ignoring case, the rule therefore leaves out the candidates whose local_ref has another value; candidates without local_ref stay. A local_ref with values separated by ;, such as F;G;H, carries each of them. Platform 32 then has no route edge, and the local_ref distance rule matches it to the element labelled 32.
Without a candidate that carries the code, labels are not compared: they may follow another scheme, such as platforms A and B against Nord and Süd, or be a stop number taken from ref. Stops without a platform code, such as the two M1 platforms at EPFL, which only the direction tells apart, are not affected.
When the rule helps
- An OSM platform has no
uic_ref, but its route relations tie it to the official stop. - Several OSM elements are equally close; only one serves the stop's routes.
The same evidence is checked again after matching: a match whose routes contradict each other becomes a contradicts_route_matching problem.
Code
| Element | Location |
|---|---|
| The rule | GtfsRoutePredicate in src/osm_public_transport_matcher/core/predicates/gtfs_route_matching.py |
| Token construction and contradiction check | src/osm_public_transport_matcher/core/utils/route_matching.py |
| Relation-to-route mapping | RouteState in src/osm_public_transport_matcher/core/route_state.py |
| OSM evidence parsing | read_osm() in src/osm_public_transport_matcher/adapters/osm.py |
Related pages
- E1.2 GTFS and ATLAS: how GTFS itineraries are built
- E1.3 OSM data: how route relations are read
- E3.2 Route-route matching: matching whole routes