A2.2 Filter and search logic

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 Stops is selected (or all rule children are selected, rolling up to all), the branch selects stop_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: selecting two_sided_stop also includes stop_type = 'effectively_matched' (the middle elements of two-sided stops whose sides are matched, which have no direct match_type of 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_COLUMN in backend/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 unmatched is selected (or both sub-reasons are selected), the branch selects stop_type = 'atlas_unmatched'.
  • When narrowed to one sub-reason (unmatched_reason), No OSM < 50m selects match_type = 'no_nearby_counterpart' and OSM < 50m selects match_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:1 does not keep ch: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: 8500819 keeps Saanenwald, tagged uic_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:

  1. The name or number is the text.
  2. The name or number starts with the text.
  3. Every word of the text starts a word of the name, in any order: bahnhof bern finds Bern, Bahnhof.
  4. 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

  1. User submits input via Enter key, or picks a suggestion
  2. parseSmartSearchInput() classifies the value into a token kind or returns a validation error; a name takes the first suggestion's token
  3. addSearchToken() adds the token to activeFilters.station and calls fetchAndCenterSpecificStop()
  4. fetchAndCenterSpecificStop() calls /api/stop_by_id with the identifier and type
  5. 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)
  6. 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](https://github.com/openTdataCH/stop_sync_osm_atlas/blob/main/backend/services/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_type on OsmNode.osm_transport_type): ferry_terminal, tram_stop, station, platform, stop_position, aerialway_station.
  • Entity predicate (entity_type): way selects OSM entries derived from ways, identified by osm_node_id LIKE 'way_%'.
  • OSM operator predicate: osm_operator matches OsmNode.osm_operator, osm_operator_wikidata matches OsmNode.osm_operator_wikidata, and missing_osm_operator=true and missing_osm_operator_wikidata=true select rows whose OSM side has no operator or no operator:wikidata tag (null or empty). The Operators page's Map link on a Not tagged row combines one of them with atlas_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 only ptv2_two_sided_stop excludes 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_matches returns the limit matched rows with the largest distance_m among the filtered rows, ordered by descending distance_m
  • /api/random_stop and /api/global_stats narrow to the top_n matched rows with the largest distance_m
  • the main map skips normal /api/data viewport loading while Top N is active
  • loadTopNMatches() issues the /api/top_matches overlay request only when the matched parent scope (All Matched Stops) is checked, whereas /api/random_stop and /api/global_stats apply top_n under both All Matched Stops and 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_types and route_directions: one entry per token, in the same order; route_directions keeps its empty entries ("" is both directions)
  • route_variants, for a route token narrowed to variants: a JSON list with one entry per token, null or {"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

Data update in progress
Elapsed: -- ETA: -- Phase: idle