Matching engine E.3.1
Route data flow
On this page
This page follows route data from the input files to the tables in the result bundle: what each stage produces and which module produces it. E3 explains the model; E3.2 the matching rules.
Source products
The two sides start from different structures.
Source side. Every adapter delivers routes, itineraries and ordered stop calls built from a GTFS feed. ATLAS itself has no line or itinerary records, so the Swiss integration rebuilds them from the Swiss GTFS (E1.2); the generic adapter reads any feed (E1):
| GTFS file | Role |
|---|---|
stops.txt |
Stop identifiers, names and positions |
stop_times.txt |
The ordered stops of each trip |
trips.txt |
Each trip's route, direction and headsign |
routes.txt |
Line metadata: short and long name, mode |
Each GTFS route_id becomes a route; trips are grouped into itineraries; each itinerary keeps one representative stop sequence; each stop call keeps its resolved source stop key when one exists. The products are source_routes, source_itineraries and source_stop_calls.
OSM side. OSM's PTv2 scheme already has the structure: stop elements, type=route relations (the itineraries) and optional type=route_master relations above them (the families). The OSM adapter keeps it in seven frames: osm_route_masters, osm_route_master_tags, osm_route_master_members, osm_route_relations, osm_route_relation_tags, osm_route_relation_members and osm_route_relation_stops (E1.3).
Normalized tables
src/osm_public_transport_matcher/routes.py converts both sides into one model:
| Table | Source side | OSM side |
|---|---|---|
line_families |
One per route_id |
One per group of route relations (grouping order) |
itineraries |
One per source_itineraries row |
One per route relation |
stop_calls |
The source_stop_calls of the itinerary |
The stop members of the relation, one call per stop visit |
Each OSM stop call is resolved to a source stop where possible, which lets the two sides be compared stop by stop; E3.2 gives the order in which the identity is looked up.
The raw route tables source_routes and osm_route_relations travel in the bundle as well, as the records behind the normalized rows. The bundle's routes section lists the fields of every table.
Match tables
Matching adds line_family_matches, which links a source family to an OSM family, and itinerary_matches, which links one source itinerary to one OSM itinerary inside such a match, with its scores. A family can have several matches: the timetable splits one line into several routes, and OSM can hold one line twice (E3.2).
Code
| Module | Role |
|---|---|
src/osm_public_transport_matcher/adapters/gtfs_columnar.py |
Reduces the national feed to trip patterns |
src/osm_public_transport_matcher/adapters/gtfs.py |
The source products of any GTFS feed |
src/osm_public_transport_matcher/adapters/get_atlas_gtfs.py |
Resolves Swiss GTFS stops to ATLAS SLOIDs |
src/osm_public_transport_matcher/adapters/get_atlas_data.py |
ATLAS selection and the Swiss source route products |
src/osm_public_transport_matcher/adapters/acquisition.py |
The separately cached ATLAS, GTFS and mapping stages |
src/osm_public_transport_matcher/adapters/osm_routes.py |
The OSM route frames, and optional diagnostic CSV files |
src/osm_public_transport_matcher/routes.py |
Normalization and matching, without file access |
The review application stores these tables when it imports a bundle; see A1 Database. E5.2 covers the candidate indexes and the score-only sequence alignment that keep route comparison fast.
Related pages
- E3.2 Route-route matching: the rules that fill the match tables
- E1.2 GTFS and ATLAS and E1.3 OSM data: the source and OSM route products
- Result bundle format: how the tables are written
- A1 Database & bundle import: where the review application stores them