Matching engine E.1.2
Swiss GTFS and ATLAS
On this page
The Swiss timetable (GTFS) tells the engine which routes serve which platforms, in which order and direction. This page explains how the Swiss integration reads the national feed, resolves each GTFS stop_id to an ATLAS SLOID, and builds the lines and itineraries of the source side from the feed. These products feed route matching, route comparison and the review application's GTFS identity map.
The generic GTFS adapter, adapters.gtfs.read_gtfs(), needs none of this: no SLOIDs, no Swiss identifiers and no boundary. See E1.
The GTFS files
A GTFS feed is a ZIP of CSV files with a .txt extension. Four of them matter here:
| File | Holds | Used for |
|---|---|---|
stops.txt |
Each stop's stop_id, name, position, platform_code, parent_station |
Identity resolution |
routes.txt |
Each line's route_id, route_short_name, route_long_name, route_type |
Line families |
trips.txt |
Each journey's trip_id, route_id, direction_id, trip_headsign, trip_short_name |
Itinerary buckets |
stop_times.txt |
For every trip, its stops in stop_sequence order |
Stop calls |
To know which routes serve a stop, the tables are joined stop_times → trips → routes:
The Swiss path also requires the feed's original_stop_id and didok columns in stops.txt; they are Swiss conventions, not GTFS requirements. The boundary selector (_boundary_selector() in swiss.py) fails with GTFS stops.txt lacks required columns for Swiss stop filtering: [...] when original_stop_id or didok is missing, or when one of them, stop_id, stop_lat or stop_lon is empty in every row. It fails with GTFS Swiss stop filter produced 0 stops when no stop remains. The loader adds an absent optional column as an empty one, which is why an all-empty column counts as missing; it reads stop_lat and stop_lon itself, so a feed without them fails earlier with a KeyError. A feed passed with --gtfs and no boundary is treated as preselected input and skips both checks.
Processing a national feed
stop_times.txt holds one row per stop of every trip, and many trips repeat the same stop sequence. The default processor (gtfs_columnar.load_gtfs_columnar()) therefore reduces the trips to their distinct patterns inside an embedded DuckDB database before any Python object is built:
The parsed feed is cached as its own acquisition stage (E5.1). GTFS_PROCESSING_BACKEND=pandas selects the chunked pandas reference reader, used for comparisons. E5.2 describes the algorithm, the memory settings and the benchmark.
Resolving stop_id to SLOID
Every GTFS stop is resolved independently of matching with OSM. The strategies are tried in order, and the first that succeeds decides:
| # | Strategy (resolution_method) |
Rule |
|---|---|---|
| 1 | original_stop_id |
The feed's original_stop_id is itself an ATLAS SLOID. |
| 2 | uic_platform |
Derive the UIC number from didok, original_stop_id or stop_id, and the platform code from the identifier or platform_code; map the special codes 10000 → 1 and 10001 → 2; then find the ATLAS platform with that (number, designation). |
| 3 | coordinate_proximity |
An ATLAS platform with the same UIC number lies within 0.5 m, and the pairing is one-to-one. |
| 4 | unique_number |
The UIC number belongs to exactly one ATLAS platform. |
Strategy 1 applies when original_stop_id holds a SLOID, such as ch:1:sloid:3000:501:33. Strategy 2 covers UIC-based identifiers such as 8503000:0:33, UIC number 8503000 and platform 33. Strategies 3 and 4 need no platform code. Unresolved stops keep resolution_method = unmatched and still appear on the review application's identity map.
The resolution is computed once (build_gtfs_atlas_payload()) and reused for the route products, the identity rows and the statistics.
From trips to itineraries
The route products do not contain one row per trip. The integration rebuilds a compact model with three levels:
- Route: one row per GTFS
route_id. - Itinerary: one direction or variant of a route.
- Stop call: one ordered stop of an itinerary.
Trips are bucketed conservatively: by route_id and direction_id, then by the representative headsign, else by trip_short_name, else by a hash of the ordered stop pattern at UIC level. When several patterns fall into one bucket, the most frequent one provides the itinerary's stop sequence, the platform-level SLOIDs of patterns with the same UIC-level sequence are kept as source_stop_key_variants, and trip_count records how many trips the itinerary stands for.
Route identifiers and timetable years
Swiss route_ids follow the pattern <branch>-<line>-<project>-<version>, where the project part encodes the timetable year, for example -j26. A line therefore gets a new identifier every year. route_id_normalized replaces the year with -jXX (11-T-j26-1 becomes 11-T-jXX-1), so a gtfs:route_id tag entered in OSM in an earlier year still matches. The normalizer, normalize_route_id(), lives in the Swiss profile.
Outputs
The products are written to data/processed/ in the workspace. The three route products have the same names and columns as those of the generic GTFS adapter, so route comparison treats every source alike; the Swiss integration adds its identity columns. The identity products travel in the result bundle as extensions.
source_routes.csv
| Column | Meaning |
|---|---|
route_id |
The GTFS route_id |
route_id_normalized |
The identifier with its year code replaced by -jXX |
agency_id, route_short_name, route_long_name, route_desc, route_type |
GTFS route fields |
source_itineraries.csv
| Column | Meaning |
|---|---|
itinerary_id |
Deterministic identifier from the route, direction and bucket |
route_id |
The route |
direction_id |
0 or 1 |
representative_headsign |
The headsign used for bucketing and display |
direction_label |
First and last stop of the representative pattern, such as Zürich HB -> Bern; stops outside the selection are not part of the pattern |
trip_count |
Trips represented by the itinerary |
source_stop_calls.csv
| Column | Meaning |
|---|---|
itinerary_id |
The itinerary |
stop_sequence |
Order within the representative trip |
source_stop_id, original_stop_id |
GTFS identifiers |
source_stop_key, mapping_method |
The resolved SLOID and the strategy that resolved it; the runner turns the SLOID into the source key atlas:<sloid> |
source_stop_key_variants |
JSON list of SLOIDs merged from patterns with the same UIC-level sequence |
stop_label, platform_code |
GTFS label and platform |
location_type, parent_station |
GTFS hierarchy |
canonical_stop_key |
The SLOID when resolved, otherwise gtfs:<stop_id> |
station_ref |
The station's UIC number: the numeric prefix of original_stop_id or stop_id (8501075:0:1), else the feed's didok. SLOID stop IDs carry no number, and a call at the station's SLOID (ch:1:sloid:1075, a trip without a planned platform) resolves to no platform, so this column is its only stop identity (E3.2) |
gtfs_stops_raw.csv
One row per GTFS stop, for the identity map: stop_id, stop_code, stop_name, platform_code, original_stop_id, location_type, parent_station, the parsed uic_number, the platform part of the identifier (local_ref) and its normalized form (normalized_local_ref), and stop_lat, stop_lon.
gtfs_stop_identity_resolution.csv
One row per GTFS stop with its resolution:
| Column | Meaning |
|---|---|
stop_id, source_location_type |
The GTFS stop |
identity_level |
platform, station, child_stop or stop |
resolved_sloid, resolution_method |
The SLOID, or empty with method unmatched |
confidence |
A fixed score per strategy |
distance_m |
Distance for coordinate_proximity |
gtfs_stop_lat, gtfs_stop_lon, atlas_lat, atlas_lon |
Both positions |
details_json |
Further GTFS fields, such as original_stop_id, platform_code and parent_station |
ATLAS positions are looked up among all platforms, not only those with the stop's UIC number, because an original_stop_id match can point to another station.
Statistics
The resolution statistics travel in the bundle's gtfs_atlas_stats extension and in the workspace's data/source_metadata.json:
- ATLAS coverage:
atlas.total,atlas.resolved_by_gtfs(the SLOIDs that some GTFS stop resolves to) andatlas.coverage_percent. - GTFS coverage:
gtfs_stop_ids.total,matched_to_atlas,unmatchedandcoverage_percent. - Assignments per strategy:
assignments.original_stop_id,strict,coordinate_proximityandunique_number_fallback. - Diagnostics of the proximity strategy, cardinality and reasons for unresolved stops.
The review application writes these values to data/gtfs_atlas_stats.json and its analytics after import.
Code
| File | Role |
|---|---|
src/osm_public_transport_matcher/adapters/gtfs_columnar.py |
load_gtfs_columnar(): default feed processing in DuckDB |
src/osm_public_transport_matcher/adapters/get_atlas_gtfs.py |
load_gtfs_data_streaming(), the pandas comparison path; build_gtfs_atlas_payload(), identity resolution reused everywhere; match_gtfs_to_atlas(), the four strategies; build_integrated_gtfs_data_streaming(), which joins the resolved stops with routes; build_gtfs_db_payload_rows(), the identity rows |
src/osm_public_transport_matcher/adapters/get_atlas_data.py |
swiss_route_products(): the source route products |
src/osm_public_transport_matcher/adapters/acquisition.py |
refresh_swiss(): writes the products to the workspace cache |
Related pages
- E1.1 ATLAS stops: the platforms GTFS stops are resolved to
- E2.3 GTFS route matching: how stop matching uses the routes of each stop
- E3.1 Route data flow: where the route products go next
- E5.2 Pipeline performance: the DuckDB pattern reduction and its settings