Review application A.2.6
Routes pages
On this page
The Routes section exposes three views through a shared server-rendered shell:
/routes: the route browser for comparing GTFS and OSM route definitions/routes/non-gtfs: OSM public transport routes that do not appear in the OpenTransportData GTFS dataset and are excluded from route matching/routes/gtfs-stop-id-sloid: a diagnostic map for the canonical GTFSstop_id↔ ATLASsloidmapping
All three views are rendered through templates/pages/routes.html with an active_view switch, so the page keeps one shared tab layout while loading view-specific data and JavaScript.
Shared shell and routing
The pages and their data are split three ways: backend/pages/routes.py renders the HTML tabs, backend/services/route_listing.py queries the route lists, and backend/blueprints/routes.py answers the JSON endpoints the tabs call.
backend/pages/routes.py provides:
routes_page()for the route list tabnon_gtfs_routes_page()for the non-GTFS route tabroutes_gtfs_stop_id_sloid_page()for the GTFS diagnostic map tab_render_routes_template()to pass the active tab (active_view) and its listing endpoint into the template
The template renders page tabs at the top and then chooses between:
- the filterable route-card UI
- the non-GTFS route-card UI
- the GTFS map shell with summary overlay, banner, and full-size Leaflet map container
Route browser tab
The default /routes tab provides these filters and controls:
- ATLAS Operator (searchable multi-select dropdown)
- OSM Route Operator (searchable multi-select dropdown)
- Status (
all,matched,unmatched,unmatched_gtfs,unmatched_osm) - results per page (5, 10, 20, 50, or 100)
- free-text route search
Names
The page compares two sides. The GTFS side is the timetable: its routes, variants and stop lists are built from the GTFS feed. The OSM side is the route relations. The stops of both are matched to ATLAS platforms, so stop-level labels, such as the ATLAS operator filter and the marker colours, keep the name of the stop registry. route_source_label in the review configuration sets the name of the timetable side (GTFS by default), next to source_label for the registry.
In the code, the timetable side is called gtfs: in table columns (gtfs_line_family_id), line_families.source = 'gtfs', JSON fields (gtfs_route_id, routes_gtfs), CSS classes (route-card--gtfs_only) and the comparison API (gtfs_itinerary_id, source=gtfs). A GTFS variant calls at ATLAS stops, so its markers, popups and stop matches keep atlas, as does the atlas_operator filter. The URL parameters are gtfs_variant and matched=unmatched_gtfs.
Lines with several matches
A line can be matched to several lines of the other side (E3.2):
- Several GTFS routes, one OSM line. The timetable splits one line into several routes, such as one per operator.
- Several OSM lines, one GTFS route. OSM holds the line twice, or in two parts.
Each match is a card of its own, with its own paired variants: a variant paired in one match can be unpaired in the other. Under its badge, a card names the other matches of its two lines, for example This OSM line is also matched to GTFS route IR26 · 91-26-D-j26-1. Each name links to the route search that shows that card. _attach_other_matches() in route_listing.py reads them for the cards of the page in two queries.
What supports a match
Next to Matched, a second badge says what links the two lines, from the match_method and stop_score of the line_family_matches row (E3.2):
| Badge | Route ID | Stops agree |
|---|---|---|
| Route ID and stops | yes | yes |
| Stops | no | yes |
| Route ID alone | yes | no |
The stops agree when stop_score is at least 0.8, the ratio of itinerary pairing: an itinerary of each line shares at least 80% of the longer one's stops, in order. A route ID is present when match_method is not line_number_and_stops, so the OSM gtfs:route_id or display identifier names the GTFS route. A match by the route ID alone is the one to check first: the mapper's tag links the lines, but their stops do not show it. match_support() in route_listing.py reads the badge; a row imported without a stop_score shows none.
End-to-end flow
- User submits filters using the top toolbar.
- Flask route
backend/pages/routes.py::routes_pagenormalises query params. - Backend builds a combined route query and applies matched-state filters, optional ATLAS and OSM operator constraints, and optional search on route IDs and names.
- Each matched pair of lines is one row, then unmatched GTFS-only and OSM-only rows are appended into the same paginated result set. A line with several matches has one row for each (below).
- Results are expanded with route-stop details, itinerary matches, route metadata, and the stored highest overlap of each unmatched variant.
- Template
templates/pages/routes.htmlrenders compact route cards. - Each card starts collapsed. Expanding a variant row shows its stop comparison and a map of its stops. Each variant row shows a stop-overlap figure.
Expanded variant layout
Stops are loaded from normalised stop_calls joined back to atlas_stops, osm_nodes, and stops_matched. Direction groups are sorted numeric-first.
An expanded variant has two parts:
- Stop comparison. The two variants' stops aligned in route order (how overlap is measured). The Non-GTFS tab has no GTFS side and lists the OSM stops grouped by
uic_refinstead. - Map. On screens at least 1200px wide, it sits to the right of the stops and takes 42% of the card; from 1600px the page widens to 1760px and the map takes 45%. Wider below 1600px, the stop rows (SLOID and UIC on each side) get cramped. It is as tall as the stop list, at most the viewport below the page tabs, and stays in view while the list scrolls. On narrower screens it follows the stops.
The page never nests scroll areas: stop lists grow with the page, and the column headers (GTFS, OpenStreetMap) stay below the sticky page tabs. Only the candidate list in the comparison picker scrolls on its own.
The map reuses the shared main-map stack (MapCore, MapEntityAdapters, MapRenderer) and fits the variant's stops with pixel padding. It reacts to the comparison:
- The mouse wheel scrolls the page, not the map. Clicking the map turns wheel zoom on until the pointer leaves it; a wheel over the map before that shows a hint.
- Marker colours are those of stop matching, as on the main map: blue and green for matched ATLAS and OSM stops, red and grey for unmatched ones. The comparison never recolours a stop. It adds its own marks instead: a solid line joins the same stop in both variants, a dashed amber line joins the same station at another platform, and a dashed amber ring circles a stop the other variant does not have. A collapsed Legend in the map's corner lists them.
- Each stop also shows its own stop matches: a thin line to every stop it is matched to, unless the solid line already joins them, and that stop, faded, when neither variant calls at it. When the two variants call at different platforms of a station, the thin lines show which stop of the other source each platform is matched to. The server gives each compared stop its status and its matches (
stop_typeandpartners, fromstops_matched), with one query per page or comparison (attach_stop_matches()inroute_comparison.py). - Hovering a stop row rings its ATLAS and OSM positions on the map. Clicking the row zooms to them.
See other markersadds surrounding stops from/api/data, subdued, except the ones already drawn.- Clicking a stop opens the main map's popup for it. Route stops carry their source id, so the popup is loaded with
/api/stop_popup?sloid=or?osm_node_id=; stops from/api/datause their row id. The map is a card, so it keeps one popup open at a time, pans it clear of the zoom control and the card's buttons, stacks a pair's bubbles in one column and scrolls a popup taller than the map. A popup stays open when the markers are redrawn, e.g. at the zoom where they gain labels. - The lines and rings are drawn above the stops and ignore clicks, so a click on a stop reaches its popup.
- Each popup has Open in main map, a stop link in a new tab. The card's Main map button opens the main map on the variants this map shows, including a candidate chosen in the comparison, at this map's view (
?gtfs_variant=…&osm_variant=…#map=). The main map narrows its route filter to them (A2.2) and shows every stop match of their stops.
Links to a variant
The address bar names the filters, the page and the open variant, and Copy link at the top of an open variant copies it; A2.9 Permalinks gives the parameters and how a link finds the page that shows the variant.
Variant stop overlap
Every variant row on /routes shows a stop-overlap figure next to its status badge. The figure answers one question: how much of this variant's stop sequence does a variant from the other source also serve, in the same order?
| Row | Figure | Meaning | Source of the value |
|---|---|---|---|
| Matched variant | 88.9% stop overlap (green) |
Overlap between the GTFS and OSM variants the engine paired | Computed while the page renders, from the two stop lists already loaded for the card |
| Unmatched GTFS or OSM variant | Highest overlap: 66.7% (blue) |
The best overlap this variant reaches with any variant of the other source | Read from the itinerary_best_overlaps table, which the importer fills |
| Unmatched, nothing in common | No shared stops (grey) |
No variant of the other source serves any of its stops | Same table, a row whose best_itinerary_id is empty |
Hovering the blue figure names the best counterpart and how many stops it shares in order. Opening the row shows the comparison panel.
How overlap is measured
The green figure, the blue figure and the comparison panel all use one definition.
Stop identity. A stop call has a set of resolved ATLAS identities (
source_sloidplus anysource_sloid_variants) and an optionaluic_ref. Two calls are the same stop when:- their resolved identities share at least one value (the same platform), or
- they have the same
uic_ref(the same station).
A call at another platform of the station still serves the stop, as in the engine (E3.2): which platform a train or bus uses is a question for stop matching. The stop list marks such a pair Same station, other platform, and the summary counts these rows as at another platform. Opaque source stop IDs and
canonical_stop_keyfallbacks are never treated as proof of identity.Shared stops in order. The matched-stop count is the longest run of stops that both variants serve in the same order (a longest common subsequence). Stops may be skipped on either side, but the order cannot go backwards and each call is used at most once. A variant that serves the same stops in reverse therefore scores low.
Percentage.
overlap = shared stops in order ÷ max(GTFS stop count, OSM stop count)
Dividing by the longer variant keeps a short variant that sits inside a long one from reaching 100%. The stop counts are counts of stop visits: an OSM relation lists a stop's stop position and platform one after the other, and the engine turns the two into one call (E3.2), so both variants count each stop once.
Example: GTFS A B C D and OSM A X C D Y share A C D in order, so the overlap is 3 / max(4, 5) = 60%.
This is the formula behind the engine's itinerary stop_score (E3.2 Route-route matching). The highest overlap uses it without the engine's pairing restrictions.
What "Highest overlap" searches
For an unmatched variant, the best counterpart is chosen from every variant of the other source that the route browser can show:
- GTFS or OSM itineraries whose line family has the same source and is not marked non-GTFS
- in any line family, not only the family the engine paired with this route
- including variants that already have a saved match
- with no threshold and no direction check (the engine requires at least 80% and, where both directions are known, the same direction before pairing two variants)
Candidates are ranked by overlap ratio, highest first, compared before rounding to a percentage. Between equal ratios, the candidate with more shared stops in order comes first, then the one with the lower itinerary ID. The comparison panel ranks candidates in that same order.
The figure is a review aid, not an engine result. It never creates, changes or proposes a saved match in itinerary_matches.
Why the value is stored
Finding the best counterpart means comparing one variant with every variant of the other source, which is too slow to repeat for each unmatched variant while a page loads. The answer only changes when a new dataset is published. The importer therefore computes it once per snapshot, and the route page reads one stored row per variant and renders the figure with the page. It makes no follow-up requests.
How the import computes it
compute_best_overlaps() in backend/services/route_comparison.py runs inside build_fast_insert_payloads() in backend/importing/importer.py. It works only on the bundle's projected line_families, itineraries and stop_calls rows that are about to be published, before anything is written, and reads neither the database nor raw files:
- Filter and order. Keep the GTFS and OSM itineraries that are not marked non-GTFS and build each one's stop identities, ordered by
stop_sequence. - Index each source. For GTFS and OSM separately, map every resolved identity and
uic_refto the itineraries that serve it. - Collect candidates. For each itinerary, look up its stops in the other source's index. Only itineraries that share at least one stop become candidates. For each candidate, count how many of this itinerary's stops it serves in any order, capped at the candidate's own length. The ordered count can never exceed this number, so it is an upper bound.
- Score exactly, best bound first. Sort the candidates by their upper bound and compute the exact ordered score one candidate at a time. As soon as the next upper bound falls below the best exact score found so far, no remaining candidate can win and the search stops.
- Write one row per itinerary. This includes itineraries that already have a saved match and itineraries without any candidate.
The import log reports the step as the import.itinerary_best_overlaps timing stage, inside the "Prepare application records" pipeline step.
The rows are staged and published together with the other route tables, in the same atomic switch. A stored figure therefore always refers to itineraries of the same snapshot.
Stored table
itinerary_best_overlaps holds one row per comparable itinerary:
| Column | Meaning |
|---|---|
itinerary_id |
The itinerary the row describes (primary key) |
best_itinerary_id |
Its best counterpart in the other source, or empty when no itinerary shares a stop |
matched_stop_count |
Shared stops in order with that counterpart (0 when there is none) |
stop_ratio |
matched_stop_count / max(both stop counts), from 0 to 1, or empty when there is no counterpart |
When the page renders, routes_page() calls attach_best_overlaps() (route_listing.py), which collects the unmatched variants on the current page and calls load_best_overlaps() once. That query also joins the counterpart's itinerary and line family to build the hover label. The counterpart's ID lets the comparison panel compare it without waiting for the ranking.
Comparison panel
Every expanded variant on /routes shows a comparison panel (templates/components/routes-comparison.html, static/js/pages/routes-comparison.js). It renders nothing until the variant is opened.
Alignment. Each row pairs a GTFS stop with an OSM stop, or shows a stop that only one side serves:
- The GTFS cell is mirrored (number on its inner edge), so both stops of a pair sit next to the centre link: a solid link with a dot for the same resolved stop, a dashed
UIClink for the same UIC only. - Rows with a stop on one side only are tinted, and the other side reads
Not in GTFSorNot in OSM. - Stop numbers are positions in the variant, 1 to n. OSM
stop_sequencevalues follow relation member positions and skip platforms, so they appear only in the number's tooltip. - A run of matching stops keeps two rows at each end and folds the rest behind
Show N matching stopswhen that hides at least five stops.
Above the rows, the score strip shows the overlap, the shared and one-sided stop counts, whether the directions agree, and a link to the OSM itinerary relation.
Matched variant. The alignment of the saved pair is computed while the page renders (stop_comparison in the variant's JSON) and shown without a request, with a Saved match badge.
Unmatched variant. The panel compares the variant (fixed) with a candidate of the other source:
- On opening, it shows the variant's own stops at once:
stop_comparisonholds a one-sided alignment for unmatched variants. - When the import stored a best counterpart, the panel compares it right away (
data-best-id) while it loads the ranking. - The picker lists candidates by overlap. Without a search it lists only variants sharing at least one stop (
shared_only=1) and says how many there are. A search reaches every route of the other source, still ranked by overlap. Arrow keys move through the list, Enter compares, Escape closes, and the previous and next buttons step through the ranking, loading further pages as needed. - A candidate that is already the saved match of another variant is flagged
Already matchedin the list, with the variants it is matched to in the flag's tooltip. The score strip names them (Already matched to GTFS S10 · Uetliberg -> Zürich HB). When that saved pair is a variant row on the same route card (found by the row'sdata-atlas-itinerary-idanddata-osm-itinerary-id), hovering the badge highlights the row, and clicking the name opens it and scrolls to it.
The data stays live because it depends on what the reviewer searches and pages through:
/api/routes/comparison/optionsranks the candidates of the other source by overlap, with search and paging. Withshared_only=1it lists and counts only candidates sharing a stop; otherwise every candidate is listed, zero overlaps last. Without a search, its first entry is the stored best counterpart whenever any candidate shares a stop./api/routes/comparisonreturns the stop-by-stop alignment for the chosen pair, with each side's metadata, includingsource_itinerary_id(the OSM relation) andmatched_with, the variants of the other source it is the saved match of. Options carrymatched_withtoo.
While the next comparison loads, the current one stays visible, dimmed. If it fails, the panel returns to the variant's own stops and offers a retry. The panel never changes the overlap figure on the row, and comparing never changes saved matches.
Keeping stored and live values consistent
The import-time search and the live ranking share the identity rules and the ordered scoring in backend/services/route_comparison.py. tests/test_route_comparison.py checks that:
- for every fixture itinerary, the stored best counterpart equals the first candidate of the live ranking
- on random stop sequences (repeated stops, conflicting identities, UIC-only stops, variant identities), the import-time search finds exactly what aligning every possible pair would find
When you change the identity rules or the formula, change them in that module and run those tests. Stored figures update with the next import.
Non-GTFS routes tab
The /routes/non-gtfs tab lists OSM route families marked is_non_gtfs. These routes are retained for inspection but are not included in GTFS–OSM route matching. The tab reuses the route cards, stop details, embedded maps, and pagination shell from the main browser, but intentionally omits the main browser's toolbar: search, status, operators and results per page. Its variants link the same way, with osm_variant only.
GTFS stop_id ↔ sloid map tab
The /routes/gtfs-stop-id-sloid tab is a full-page diagnostic Leaflet map backed by the imported gtfs_stops_raw and gtfs_stop_identity_resolution tables.
What it shows
- GTFS stops with at least one imported coordinate source
- ATLAS stops represented in the imported GTFS/ATLAS state table
- visible matched line segments between GTFS and ATLAS points
- a compact summary overlay showing GTFS coverage, ATLAS coverage, and assignment counts
Marker colours are intentionally fixed:
- matched ATLAS: blue
- unmatched ATLAS: red
- matched GTFS: orange (
#F0AD4E) - unmatched GTFS: grey
Backend APIs
The tab reads four dedicated JSON endpoints from backend/blueprints/routes.py:
/api/routes/gtfs-stop-id-sloid/summary/api/routes/gtfs-stop-id-sloid/map/api/routes/gtfs-stop-id-sloid/search/api/routes/gtfs-stop-id-sloid/popup
The query and serialisation logic lives in backend/services/gtfs_stop_id_sloid.py.
That service builds deduplicated coordinate subqueries (GTFS positions from gtfs_stops_raw, one ATLAS position per SLOID from stops_matched), counts each stop's matches in gtfs_stop_identity_resolution, and returns:
gtfs_stopsatlas_stopsmatchesmeta(zoom, cap state, overview/detail mode)
Overview/detail behaviour
The page follows the main map's zoom policy (MapShared.getViewportZoomPolicy()) and always sends a limit:
- below zoom
13(overview): at most1800rows, half GTFS and half ATLAS, without the matched lines (include_matches=0) - at zoom
13and14: at most1800rows, with the lines - from zoom
15: every row in view (limit=all)
The banner asks to zoom in while the view is an overview or a side was capped. Without a limit, the endpoint falls back to 3000 rows per side below zoom 11 and 5000 from zoom 11 (GTFS_STOP_ID_SLOID_OVERVIEW_LIMIT, GTFS_STOP_ID_SLOID_DETAIL_LIMIT and GTFS_STOP_ID_SLOID_DETAIL_ZOOM).
Within each side's budget, rows are fetched in a balanced way so matched and unmatched states do not starve each other inside a dense viewport.
Popup behaviour
The frontend lazy-loads popup payloads per clicked marker.
GTFS popups include:
- stop identifiers and coordinates
- matched SLOID previews
- same-UIC ATLAS candidate previews
ATLAS popups include:
- SLOID and ATLAS metadata
- matched GTFS stop previews
- same-UIC GTFS candidate previews
The map keeps the shared draggable multi-popup behaviour by reusing MapPopupController and the popup lines of MapCore.
Identifier search
The search endpoint accepts exact SLOID, UIC, and GTFS stop_id searches. It returns mappable targets, after which the frontend centres the map and reloads the viewport with the identifier filter applied.
Links
The address bar names the map view and the stop whose popup is open, and each popup card has a Copy link action; A2.9 Permalinks gives the parameters and what a link does on load.
Code
| File | Role |
|---|---|
backend/pages/routes.py |
The three tab pages, their query parameters and canonical redirects; shared routes template rendering and the maintenance page |
backend/pages/pagination.py |
The page and per_page parameters and the page range, shared with the Operators page |
backend/services/route_listing.py |
Main and non-GTFS route-list query construction (query_route_page()); finding the page that holds a linked variant (locate_route_variant_page()); loading line_families, line_family_matches, itineraries, itinerary_matches, stop_calls, and itinerary_best_overlaps for route cards |
backend/blueprints/routes.py |
Four GTFS JSON endpoints; route comparison JSON endpoints (/api/routes/comparison and /api/routes/comparison/options); the variants of a line for the main map's route filter (/api/routes/variants, A2.2) |
backend/services/route_comparison.py |
Stop identity rules and ordered stop alignment; live candidate ranking for the comparison panel; import-time compute_best_overlaps() and page-time load_best_overlaps() |
backend/services/gtfs_stop_id_sloid.py |
GTFS summary payloads; viewport payloads for GTFS/ATLAS markers and line segments; GTFS and ATLAS popup payload builders |
templates/pages/routes.html |
Tab shell shared by the three Routes views; route list toolbar, cards, and pagination; GTFS map shell, banner, and summary overlay host |
static/js/pages/routes.js |
Route browser toolbar behaviour and embedded route preview maps; wheel-zoom guard and highlighting of hovered comparison rows; opening a linked variant and keeping the open variant in the address bar |
templates/components/routes-comparison.html, static/js/pages/routes-comparison.js |
Comparison panel of every variant, rendered only when its row is opened; candidate picker of unmatched variants |
static/js/pages/routes-gtfs-stop-id-sloid.js |
GTFS map initialisation, viewport fetching, marker rendering, summary updates, popup loading, map view and stop links |
Related pages
- E3.2 Route-route matching: how the engine pairs the lines and itineraries shown here
- A1 Database: the route tables the pages read
- A1.1 Bundle import and publication: when the stored overlaps are computed
- A2.2 Filter and search logic: the main map's route filter these pages link to
- A2.9 Permalinks: the parameters each tab keeps in the address bar