Matching engine E.2.3

GTFS route matching

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.

flowchart TB A["Unmatched source stop<br/>with route evidence"] --> C["Unmatched OSM candidates<br/>within 50 m, without stations"] C --> L["Without elements labelled with another platform<br/>when one carries the platform code"] L --> P1{"Shared route and<br/>direction tokens?"} P1 -->|"yes"| E1["Token edge,<br/>score = shared tokens"] P1 -->|"no"| P2{"Same direction<br/>name?"} P2 -->|"yes"| E2["Direction edge"] P2 -->|"no"| X["No edge"] E1 --> S["Commit edges that are the unique<br/>best for both of their stops"] E2 --> S

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:

  1. 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.
  2. 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.
  3. Commit the kept edges as gtfs_shared_route, strongest first.
  4. 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