Matching engine E.1.2

Swiss GTFS and ATLAS

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:

erDiagram ATLAS_PLATFORM ||--o{ GTFS_STOP : "resolved to" GTFS_STOP ||--o{ GTFS_STOP_TIME : "visited by" GTFS_TRIP ||--o{ GTFS_STOP_TIME : "calls at" GTFS_ROUTE ||--o{ GTFS_TRIP : "runs" ATLAS_PLATFORM { string sloid PK string number string designation } GTFS_STOP { string stop_id PK string stop_name float stop_lat float stop_lon } GTFS_STOP_TIME { string trip_id FK string stop_id FK int stop_sequence } GTFS_TRIP { string trip_id PK string route_id FK int direction_id } GTFS_ROUTE { string route_id PK string route_short_name string route_long_name }

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:

flowchart LR Stops["Stops and the<br/>explicit boundary"] --> Selected["Selected stop IDs"] Times["stop_times.txt"] --> Native["Typed scan in DuckDB"] Selected --> Native Trips["trips.txt"] --> Native Native --> Ends["First and last stops,<br/>including foreign ones"] Native --> Patterns["Distinct ordered<br/>trip patterns"] Patterns --> Identity["Resolve stop_ids<br/>to SLOIDs"] Ends --> Directions["Direction labels"] Identity --> Calls["Itineraries and<br/>stop calls"] Directions --> Calls

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:

  1. Route: one row per GTFS route_id.
  2. Itinerary: one direction or variant of a route.
  3. 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) and atlas.coverage_percent.
  • GTFS coverage: gtfs_stop_ids.total, matched_to_atlas, unmatched and coverage_percent.
  • Assignments per strategy: assignments.original_stop_id, strict, coordinate_proximity and unique_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