Routes

At a high level, the route pipeline has three stages:

1. Source-specific route artifacts are produced in data/processed/.
2. route_loader.py normalizes those artifacts into shared line_families, itineraries, and stop_calls rows during import preparation.
3. The same preparation step builds line_family_matches and itinerary_matches, which the importer then persists.

This chapter explains the route model itself. Source extraction details remain in the preprocessing chapter, and stop-to-stop route-assisted matching remains in the matching chapter.

Route Layers

The implemented route pipeline has three conceptual layers:

Main Inputs

• GTFS route-family and itinerary artifacts built by matching_and_import_db/downloader/get_atlas_gtfs.py
• OSM route-master and route-relation artifacts built by matching_and_import_db/downloader/get_osm_data.py
• base stop-matching output used by matching_and_import_db/database/route_loader.py to resolve physical stop identity across both sides

Main Responsibilities

The route subsystem inside matching_and_import_db/ is responsible for:

• reconstructing ATLAS-side line families and itineraries from GTFS
• extracting OSM route-master, route-relation, tag, member, and stop artifacts into processed CSVs
• resolving route stops onto shared stop identities where possible, preferring matched ATLAS sloid values and falling back to UIC or raw canonical keys when necessary
• matching ATLAS and OSM line families
• scoring and pairing ATLAS and OSM itineraries only within already matched families

Persistence Boundary

Not every route artifact generated in data/processed/ is persisted as a raw database table.

• route_loader.py still consumes the full source artifact set, including ATLAS itinerary CSVs and OSM tag/member/stop CSVs, to build normalized route rows.
• The active import schema only keeps atlas_line_families and osm_route_relations as route-source anchor tables.
• The web app reads normalized route data from line_families, itineraries, stop_calls, line_family_matches, and itinerary_matches.

It also supports two different consumers:

• stop matching runtime: AtlasState, OsmState, RouteState, and RouteMatchPredicate
• route import/runtime: database/route_loader.py and the /routes page queries

Subpages

• 3.1 Route Pipeline Data Flow
• 3.2 Route-Route Matching

Related Documentation

• 1.2 GTFS ATLAS data
• 1.3 OSM data
• 2.3 Stop-stop matching using routes
• 5.1 Import Process
• 6.6 Routes Pages