Review application A.2.2
Filter and search logic
On this page
This page defines what the map's filters and search mean. The same definition applies to every filtered request: the viewport data (/api/data), the summary statistics (/api/global_stats), the random stop and the Top N overlay, so the markers and the counts always describe the same set of rows. Rows are entries of stops_matched: a matched pair, an unmatched ATLAS platform, an unmatched OSM element or a disused OSM element (A1).
An info icon beside the Matched, OSM Groups and Problems filters opens the engine documentation for the matching rules, OSM grouping and stop problems.
The core rule
Every filtered endpoint (/api/data, /api/global_stats, /api/random_stop and /api/top_matches) starts from filtered_stops_query() in backend/queries/helpers.py, combining apply_common_filters(), resolve_stop_type_match_filters(), build_stop_scope_condition() and the ATLAS duplicate condition. The filter system uses one boolean grammar:
- within a filter group, selected values combine with
OR - across filter groups, active groups combine with
AND(ScopePredicate AND SearchPredicate AND AtlasPredicate AND OsmPredicate AND DuplicatePredicate AND ProblemPredicate)
If a group has no active selection, it adds no restriction.
Scope predicate
The scope predicate (ScopePredicate = MatchedBranch OR AtlasUnmatchedBranch OR OsmUnmatchedBranch OR OsmDisusedBranch) selects which stops_matched.stop_type categories are eligible. With no branch selected, every row is eligible, disused elements included (except in /api/global_stats; see OSM disused branch).
Matched branch
- When
All Matched Stopsis selected (or all rule children are selected, rolling up toall), the branch selectsstop_type IN ('matched', 'effectively_matched'). - When a subset of matching rule sub-filters is selected, the branch selects
stop_type = 'matched' AND match_type IN (...). Special case: selectingtwo_sided_stopalso includesstop_type = 'effectively_matched'(the middle elements of two-sided stops whose sides are matched, which have no directmatch_typeof their own). - Propagated pairs follow their rule. A pair matched by propagation has no rule of its own; it is selected with the rule of the match it was propagated from. An OSM pair partner (
osm_pair_propagation, the other element of a PTv2 platform and stop position pair) follows the other match of its ATLAS stop, and an ATLAS duplicate (source_duplicate_propagation) follows the other match of its OSM element (PROPAGATION_SHARED_COLUMNinbackend/services/matching_rules.py). So UIC reference shows the platforms it matched with their stop positions, and leaving out one rule hides only that rule's pairs.
A match_method value is either a matching rule key, which selects every match type of that rule, or a single match type. backend/services/matching_rules.py lists the rules in run order with their match types; the Matched dropdown sends:
| Group | Value | Selects the match types |
|---|---|---|
| Identifier matching | identifier |
sloid_identifier |
two_sided_stop |
uic_two_sided_stop (plus stop_type = 'effectively_matched') |
|
reference |
uic_reference_one_osm, uic_reference_local_ref, uic_reference_one_source |
|
name |
name_one_osm, name_local_ref |
|
| GTFS route matching | gtfs_shared_route |
gtfs_shared_route |
gtfs_shared_direction |
gtfs_shared_direction |
|
| Distance matching | group_distance |
uic_ref_group_distance, uic_name_group_distance, name_group_distance |
group_long_distance |
the same three with _group_long_distance |
|
local_ref_distance |
local_ref_distance |
|
distance_only_candidate |
distance_only_candidate, distance_only_candidate_second_pass |
|
distance_ratio |
distance_ratio |
The backend turns the selected values into one match_type IN (...) condition. An unknown value selects nothing.
ATLAS unmatched branch
- When
ATLAS unmatchedis selected (or both sub-reasons are selected), the branch selectsstop_type = 'atlas_unmatched'. - When narrowed to one sub-reason (
unmatched_reason),No OSM < 50mselectsmatch_type = 'no_nearby_counterpart'andOSM < 50mselectsmatch_type != 'no_nearby_counterpart' OR match_type IS NULL.
OSM unmatched branch
Explicit only: when OSM unmatched is checked, OsmUnmatchedBranch selects stop_type = 'osm_unmatched'; when unchecked, osm_unmatched rows are never added implicitly by another branch.
OSM disused branch
The OSM disused checkbox in the Unmatched dropdown (#masterDisusedOsmCheckbox) selects disused OSM elements (stop_type = 'osm_disused') and shows the chip "Disused OSM". Like OSM unmatched, it is explicit only when any other scope branch is active. /api/global_stats is stricter: it excludes osm_disused rows unless this branch is explicitly selected (A2.3).
Search predicate
Search tokens are OR-combined within the search group.
SearchPredicate = token_1 OR token_2 OR token_3 ...
Meaning:
- if multiple search tokens are active, a row matches if it matches any of them
- a stop ID or OSM ID token keeps the row with exactly that identifier:
ch:1:sloid:10035:0:1does not keepch:1:sloid:10035:0:1955 - a UIC token keeps the rows whose ATLAS platform has that number, and the rows whose OSM element lists it in
uic_ref, alone or among;-separated values:8500819keeps Saanenwald, taggeduic_ref=8530279;8500819
Accepted formats
The search input (#smartSearchInput) accepts a stop name (Names and suggestions) or one of the following identifiers, parsed by parseSmartSearchInput() in filters.js:
| Format | Example | Token kind | Backend identifier_type |
|---|---|---|---|
| Configured source identifier | source:agency/stop:123 |
atlas |
sloid |
UIC station code (seven digits starting with 85, optionally followed by :<digits>) |
8503000 |
station |
station |
| ATLAS SLOID | ch:1:sloid:3000:501:33 |
atlas |
sloid |
| OSM node ID (digits only) | 123456789 |
osm |
osm_node_id |
Route ID (dash-separated or route: prefixed) |
11-T-j25-1 |
route |
route |
| Route + direction | 11-T-j25-1 dir:0 |
route |
route |
Input that is no identifier is searched as a name. When no stop has that name either, the box says so and shows the accepted formats hint (#smartSearchHint).
source: accepts arbitrary source identifiers, including IDs containing spaces or numeric IDs that would otherwise be interpreted as OSM/UIC identifiers. The token kind atlas and the identifier type sloid serve every configured source; the displayed source and ID labels come from ReviewConfig. The Swiss shortcuts are always accepted, but their hints are only shown for the GTFS identity capability. Route search is rejected when capabilities.routes is false, and route hints/actions are hidden.
OSM node IDs may also be entered as node/123456789. Route input accepts dir:0 or dir:1; the token stores the direction for subsequent filtered requests, while the initial centring lookup validates the route ID itself.
Names and suggestions
From the second character typed, a list under the box suggests stops whose name or number matches the text, from /api/search/suggest?q= (backend/services/stop_suggest.py, drawn by static/js/components/search-suggest.js). Each suggestion shows a name, its number and its source:
- A station of the official dataset: the platforms that share a UIC number, shown with that number and how many platforms it has. A platform without a station number is its own entry, shown with its stop ID.
- An OSM element without a match, shown with its OSM ID and "no match" or "disused". An unmatched element that carries the UIC number of a station is not listed apart: its name is one of that station's names.
A station is also found under the OSM names of its matched elements and of the unmatched elements that carry its number. The suggestion then names the OSM name that matched, for example Zürich HB · OSM name: Zürich Hauptbahnhof.
Names are compared without case, accents or punctuation, so zurich hb finds Zürich HB and saint imier finds St-Imier through its OSM name Saint-Imier. The best eight suggestions are listed in this order:
- The name or number is the text.
- The name or number starts with the text.
- Every word of the text starts a word of the name, in any order:
bahnhof bernfinds Bern, Bahnhof. - The name contains the text (three characters or more).
Within a step, stations come before OSM elements and a station's own name before its other names; then stations found by number are ordered by number, and names by length, so Zürich HB comes before Zürich HB SZU.
Picking a suggestion, with the mouse or with the arrow keys and Enter, adds the same filter as typing its number: a station adds a UIC filter, a platform its stop ID and an OSM element its node or way ID. Enter without a choice picks the first suggestion, unless the text is an identifier: 8503000 and node/123 are searched as typed. A dashed text such as Saint-Imier may be a name or a route ID; it is searched as a name first and as a route ID when no name matches, and route: makes it a route ID.
Chips of these filters show the stop's name before its identifier, for example Zürich HB · UIC: 8503000, whether the stop was picked from the list or typed by its identifier.
The suggestions come from an index of every station and unmatched OSM element of the published snapshot. Each web worker builds it on the first request after an import and keeps it until another snapshot is published.
Search flow
- User submits input via Enter key, or picks a suggestion
parseSmartSearchInput()classifies the value into a token kind or returns a validation error; a name takes the first suggestion's tokenaddSearchToken()adds the token toactiveFilters.stationand callsfetchAndCenterSpecificStop()fetchAndCenterSpecificStop()calls/api/stop_by_idwith the identifier and type- On success: the map moves to the result and filters update. SLOID and OSM node searches open the stop's popup and place the stop two thirds down the map, so the popup fits above it; UIC and route searches open no popup and centre the stop (A2.1)
- On failure: the token is reverted and an error is shown
Not-found feedback
When a correctly formatted input does not match any database entry, /api/stop_by_id returns a 404. The frontend displays an error in the #smartSearchError element, styled via .smart-search-feedback in static/css/components/shared-filters.css.
The error message follows the pattern: No {type} found matching: {identifier}, where {type} is the human-readable token kind (e.g. "OSM node", "UIC station", "ATLAS SLOID").
Route filters and their variants
A route token keeps the rows that have a side among the stops of a line. The line is every GTFS and OSM line family the route ID names, plus the families linked to them (get_stops_for_route() in transport_routes.py). A family can have several links, so the two timetable routes of one public line, linked to the same OSM line, show together. Its stops are those of all their itineraries, or only one direction's.
The route chip's dropdown chooses how much of the line to keep:
- Both directions, or Direction 0 or 1 (all variants): every variant, or one direction's. The chip shows Both, Dir: 0 or Dir: 1.
- A variant: exactly the stops of that variant. The variants come from
/api/routes/variants?route_id=when the dropdown first opens, each listed under its direction. The variants the engine paired come first, as one entry, then those left unpaired. An entry shows the variant's name once, with->drawn as→, and a GTFS and/or OSM tag for the sources it keeps. When a pair's OSM name differs, it appears below in grey. The chip then shows the name, followed by · GTFS only or · OSM only for one source; its tooltip names both sides.
A variant narrows the line to its itineraries' stops, whatever their direction. The kept rows are the stops_matched rows with a side among those stops, so each stop's match appears too, even when no variant of the filter calls at it. The two platforms of Zürich Selnau, for example, appear with the platform each is matched to. A selection whose keys name no itinerary keeps no stop; it never widens to the whole line.
Variants are named with the route lists' keys: the GTFS itinerary id (gtfs_variant) and the OSM route relation id (osm_variant). A GTFS key is looked up exactly, then with the timetable year ignored. A link to the main map can name them (A2.9); the routes page's variant maps link to the main map this way.
ATLAS predicate
ATLAS-side attributes (operator, matched against AtlasStop.atlas_business_org_abbr) are OR-combined within the ATLAS predicate group and require an ATLAS side (sloid IS NOT NULL), so osm_unmatched and osm_disused rows never satisfy an ATLAS predicate.
OSM predicate
The OSM predicate requires an OSM side (osm_node_id IS NOT NULL, excluding atlas_unmatched rows) and AND-combines four subgroups (OsmPredicate = TransportPredicate AND EntityPredicate AND OsmOperatorPredicate AND OsmGroupPredicate), each OR-combined within itself:
- Transport predicate (
transport_typeonOsmNode.osm_transport_type):ferry_terminal,tram_stop,station,platform,stop_position,aerialway_station. - Entity predicate (
entity_type):wayselects OSM entries derived from ways, identified byosm_node_id LIKE 'way_%'. - OSM operator predicate:
osm_operatormatchesOsmNode.osm_operator,osm_operator_wikidatamatchesOsmNode.osm_operator_wikidata, andmissing_osm_operator=trueandmissing_osm_operator_wikidata=trueselect rows whose OSM side has nooperatoror nooperator:wikidatatag (null or empty). The Operators page's Map link on a Not tagged row combines one of them withatlas_operator, so the map shows exactly the stops that row counts. - OSM group predicate (
osm_group_type): selects members of OSM pairs or PTv2 two-sided stops (ptv2_pair_uic_ref,ptv2_pair_uic_ref_equal_count,ptv2_pair_name,ptv2_pair_name_equal_count,tram_stop_pair,tram_stop_pair_equal_count,ptv2_two_sided_stop). Selecting the OSM groups master without subtype refinement selects any group member; selecting onlyptv2_two_sided_stopexcludes pair rows.
Duplicate predicate
Duplicate ATLAS (duplicate_atlas=true) is a server-side AND-filter applied across /api/data, /api/top_matches, /api/random_stop and /api/global_stats. It keeps rows whose ATLAS platform belongs to a duplicate group: either the platform has representative_sloid set (non-representative member) or it is referenced as representative_sloid by at least one sibling in atlas_stops. Whether both sides of a matched row are drawn is a rendering decision, not a filter predicate.
Problem predicate
The Problems dropdown keeps rows that have at least one problem row (EXISTS (SELECT 1 FROM problems p WHERE p.stop_id = stops_matched.id AND ...) in has_problem_condition(), backend/services/problem_filters.py) matching both the selected problem_type (all or comma-separated types) and the selected priority (1, 2, 3), using the same names as the Problems page and permalinks. Selecting no type matches any type; selecting no priority matches any priority; selecting every type rolls up to all.
Top N distances
Top N is a matched-only mode used by /api/top_matches, /api/random_stop and /api/global_stats (via top_distance_matches()). The UI enables the Top N control whenever All Matched Stops or at least one matched sub-filter is selected, and disables it if matched scope is cleared:
/api/top_matchesreturns thelimitmatched rows with the largestdistance_mamong the filtered rows, ordered by descendingdistance_m/api/random_stopand/api/global_statsnarrow to thetop_nmatched rows with the largestdistance_m- the main map skips normal
/api/dataviewport loading while Top N is active loadTopNMatches()issues the/api/top_matchesoverlay request only when the matched parent scope (All Matched Stops) is checked, whereas/api/random_stopand/api/global_statsapplytop_nunder bothAll Matched Stopsand individual matching rule sub-filters
Request serialization rules
The frontend sends the active filters (appendCurrentFilterParams() in static/js/pages/main.js; the Top N overlay in loadTopNMatches() uses it too, so the map and the summary banner see the same filters). The scope, matching rule, OSM, operator, duplicate, problem and Top N filters use the names and values that the map keeps in the address bar, listed in A2.9, including how a parent checkbox stands for its children. The backend treats any matching rule selection as implying matched scope, so match_method=reference works even if stop_filter=matched is omitted.
Search tokens are sent as parameters that the address bar does not use (it repeats search= instead):
station_filter,filter_typesandroute_directions: one entry per token, in the same order;route_directionskeeps its empty entries (""is both directions)route_variants, for a route token narrowed to variants: a JSON list with one entry per token,nullor{"atlas": key, "osm": key}. JSON, because ATLAS headsigns can contain commas. Malformed input narrows to no stop
Code
| File | Role |
|---|---|
static/js/pages/filters.js |
The filter controls and chips; parseSmartSearchInput() for search tokens |
static/js/pages/main.js |
appendCurrentFilterParams() and loadTopNMatches(): the filters each request sends |
backend/queries/helpers.py |
filtered_stops_query(), parse_filter_params(), the scope helpers, the ATLAS duplicate condition and top_distance_matches() |
backend/query_builder.py |
apply_common_filters(): the search, ATLAS, OSM and problem predicates |
backend/services/matching_rules.py |
The matching rules in run order and their match types |
backend/services/problem_filters.py |
has_problem_condition() for the Problems filter |
backend/services/transport_routes.py |
get_stops_for_route() for route tokens |
backend/services/stop_suggest.py, static/js/components/search-suggest.js |
Name and number suggestions under the search box |
Related pages
- A2.1 Map data loading and rendering: the viewport requests that carry these filters
- A2.3 Global statistics: how the summary counts the filtered rows
- A2.9 Permalinks: the parameter names the map keeps in the address bar
- E2 Matching process: the matching rules the Matched filter selects
- E4.1 Stop problems: the problem types the Problems filter selects