Review application A.2.9
Permalinks
On this page
Every page with a map or a list keeps what it shows in the address bar. The address bar is therefore always a permalink: a link that opens the page as it is now, ready to bookmark, send to someone or post on the OpenStreetMap community forum. This page lists the link format of each page, explains what happens when a link is opened, and names the code. Read it when you write links to the app from elsewhere, or when you add state to a page.
Link formats
| Page | Query parameters | Hash | Example |
|---|---|---|---|
Map / |
sloid or osm, gtfs_variant and/or osm_variant, plus every map filter |
#map= |
/?osm=way/167395649#map=16/46.45493/6.33747 |
Problems /problems |
problem_type, priority, atlas_operator, bbox, sloid, osm |
none | /problems?problem_type=distance&sloid=ch:1:sloid:7000:6:32&osm=node/3251097659 |
Routes /routes |
page, per_page, matched, atlas_operator, osm_operator, q, gtfs_variant, osm_variant |
none | /routes?osm_variant=2169538 |
Non-GTFS routes /routes/non-gtfs |
page, per_page, osm_variant |
none | /routes/non-gtfs?osm_variant=12345 |
GTFS identity map /routes/gtfs-stop-id-sloid |
sloid or gtfs_stop_id |
#map= |
/routes/gtfs-stop-id-sloid?gtfs_stop_id=8507000:0:1 |
The identifiers are the stable ones of each source, never the database's row numbers, which change with every import:
| Parameter | Value | Example |
|---|---|---|
sloid |
An ATLAS SLOID | ch:1:sloid:7000:6:32 |
osm |
The OSM element, written as on openstreetmap.org | node/3251097659, way/167395649 |
gtfs_stop_id |
A GTFS stop_id |
8507000:0:1 |
gtfs_variant |
The GTFS itinerary id: GTFS route, direction and headsign. | 91-10-A-j26-1:0:Zürich Selnau |
osm_variant |
The OSM route relation id | 2169538 |
OSM ways are stored as way_<id> and nodes as the bare number. Links always use the openstreetmap.org form; the pages convert it.
Scripts and AI agents use the same identifiers with the public lookup: /?osm=node/3251097659 becomes /api/lookup?osm=node/3251097659, which returns the stop's matches as JSON (A2.10).
Shared behaviour
The address bar follows what the user opens, and a link opens the same item for the recipient.
- The map view uses the openstreetmap.org convention
#map=<zoom>/<lat>/<lon>, with the coordinates rounded to 5 decimals. It is rewritten 0.3 s after the map stops moving. When a page loads, a hash whose zoom lies between the review configuration's minimum (map_min_zoom) and the map's maximum, 20, and whose point lies inside the configuration's map bounds (map_bounds), sets the starting view; any other hash is ignored. Other parts after&are ignored, so links copied from openstreetmap.org (#map=15/46.95/7.44&layers=T) work. - Editing only the hash of an open page moves the map. Browsers do not reload a page when only the hash changes, so a pasted link that differs only there would otherwise do nothing.
- The selected item (stop popup, Problems entry, route variant) is in the query string. Popups and variant panels can stay open side by side; the address bar names the most recently opened one that is still open, and closing it brings back the previous one.
- Rewriting never reloads and never adds history. Every change uses
history.replaceState, which fires no map orhashchangeevent, so keeping the address bar current loads no data, and Back leaves the page instead of stepping through popups. - Other parameters are kept as they are. A rewrite replaces only its own parameters and leaves the others unchanged, character for character. The Operators page's filter links keep working.
- Values are encoded like the server's canonical URLs.
/,:and,stay readable, spaces become+. The route lists are the exception: their server writes only,unencoded, so angtfs_variantreads91-10-A-j26-1%3A0%3AZ%C3%BCrich+Selnauthere. - Copy link copies the item's link to the clipboard and shows Copied for 1.5 s. On a plain-HTTP deployment, where browsers offer no clipboard API, it falls back to a text selection. If copying is impossible, a message shows the link so it can be copied by hand.
- A link that cannot be opened shows a short message, keeps the rest of the page as linked, and removes the parameter from the address bar.
- A stop link describes itself. On the map and the Problems page, the server names the linked stop and its matches in the page's title and description and links to its lookup, so link previews and clients that run no JavaScript see the stop (A2.10).
Map
The map at / keeps its view in #map= and the stop whose popup is open in sloid or osm. A matched stop has both identifiers; the link uses the side its popup was opened from, so the recipient sees the same popup.
On load, a stop parameter is looked up with a single /api/stop_by_id request. The stop's position decides the view, even when the link also has a hash. When the stop is not found, the map keeps the hash's view or the default view.
Copy link sits next to Edit in OSM iD Editor in each stop popup, including each card of the See Matches view. The copied link contains the stop and the current view.
Filters. The address bar keeps every map filter, so a link opens the same filtered view. Copy link in the summary panel copies it with the current view. The parameters have the names /api/data uses (A2.2); lists are comma-separated:
| Parameter | Filter | Example |
|---|---|---|
stop_filter |
The scope checkboxes: matched, atlas_unmatched, osm_unmatched, osm_disused |
stop_filter=atlas_unmatched |
match_method |
Matching rules and unmatched reasons chosen without their parent | match_method=reference,no_nearby_counterpart |
transport_types, osm_entity_types |
OSM transport types and entity types | transport_types=platform,tram_stop |
osm_group_types |
all, or the chosen OSM group types |
osm_group_types=ptv2_two_sided_stop |
show_duplicates_only |
Duplicate ATLAS | show_duplicates_only=true |
atlas_operator, osm_operator, osm_operator_wikidata, missing_osm_operator, missing_osm_operator_wikidata |
The operator filters | atlas_operator=PAG |
problem_type, priority |
The Problems dropdown: all or problem types, and priorities 1 to 3; the Problems page's names |
problem_type=distance&priority=1 |
top_n |
Top N distances; kept only with a matched scope | top_n=15 |
search |
One per search filter: uic:<number>, source:<stop ID>, node/<id>, way/<id>, route:<id>, optionally followed by dir:0 or dir:1 |
search=uic:8503000&search=route:91-10-A-j26-1+dir:0 |
A parent checkbox stands for its children: stop_filter=matched selects every matching rule and stop_filter=atlas_unmatched both unmatched reasons, and match_method lists matching rules and unmatched reasons only when their parent is not ticked. On load, unknown values are ignored and the address bar is rewritten with the filters that apply. The chips of search stop filters are named from /api/lookup. Example: /?stop_filter=atlas_unmatched&atlas_operator=PAG#map=12/46.85/9.53 shows PostAuto's ATLAS stops without an OSM match around Chur.
Route variants. gtfs_variant and/or osm_variant, with the values the route lists use, add a route filter narrowed to those variants (A2.2). On load, one /api/routes/variants request finds the variants and their line. Without a #map= hash or a stop link, the map fits their stops. The address bar then follows the filter: choosing another variant in the route chip rewrites the parameters, and choosing a direction or removing the chip drops them. With several narrowed route filters, it names the last one. The other route filters are search values, without their variants. A GTFS variant is found with the timetable year ignored, and the address bar is rewritten with the current id. When neither variant exists, a message says so and the parameters are removed.
Example: /?gtfs_variant=91-10-A-j26-1:0:Z%C3%BCrich+Selnau&osm_variant=1561015 shows the S10's Uetliberg → Zürich Selnau variant and OSM relation 1561015, with every stop match of their stops.
Problems
The Problems page (A2.4) keeps its filters and the entry on screen in the query string. It has no hash: its map always follows the entry.
| Parameter | Value |
|---|---|
problem_type |
Comma-separated problem types; absent means all types |
priority |
Comma-separated priorities 1, 2, 3; absent means all |
atlas_operator |
Comma-separated ATLAS operator abbreviations |
bbox |
The drawn area, west,south,east,north (A2.4) |
sloid, osm |
The stop of the entry on screen |
An entry is named by its stop:
| Entry | Named by |
|---|---|
| Matched pair | Both sloid and osm, which identify the pair even when a SLOID is matched to several OSM elements |
| Unmatched ATLAS or OSM stop | Its own identifier |
| ATLAS duplicate group | The group's representative SLOID (the first in sort order) |
| OSM duplicate group | The first member's osm |
Opening an entry deep in the list
The list holds tens of thousands of entries and loads them 100 stops at a time, in priority order. A linked entry can therefore be on any page. The page asks the server for it directly:
- The first
/api/problemsrequest carriesfocus_sloidand/orfocus_osm_node_id(stored form,way_<id>for ways) with the link's filters. - The server ranks the stops in the same order as the list and answers with the page that holds the stop's first entry, and
focus_found: true. In the duplicates-only view it ranks the duplicate groups and looks for the stop among their members. - The page shows that entry. The list then starts on that page: Next loads the following pages as usual, and Prev at the start loads the page before.
If no entry of that stop matches the filters, the server answers with page 1 and focus_found: false. The page shows a message and the first entry. When a stop has several entries (in the all-types view, a stop's duplicate problem forms its own entry), the link opens the first of them.
Entry numbers
Entry N of Total counts from the page where the list was opened: a list opened on page p numbers its first entry (p − 1) × 100 + 1. The total counts stops, but some stops have two entries, so numbers far from page 1 are approximate. A number never changes while it is on screen. Once Prev reaches page 1, the list is numbered from its first entry.
Copy link sits next to the entry and priority chips above the problem details. It copies the address bar.
Routes and non-GTFS routes
The route lists (A2.6) are rendered by the server and keep their filters and page number in the query string. A permalink adds the open variant: gtfs_variant and/or osm_variant. A matched variant names both.
When a request names a variant, the server finds the card that shows it:
- It looks up the variant's line family from
itineraries.sourceandsource_itinerary_id. - It ranks the cards of the filtered list with the list's own
ORDER BYand takes the first card of that family (for a matched variant, the card of both families). - It renders the page that holds the card. The canonical redirect writes that page number into the address bar, so the link opens the right page even after an import has moved the card.
In the browser, the variant panel opens and scrolls to the top, below the sticky tabs. When the variant is not on the page (it does not match the link's filters, or a newer import removed it), a message says so and the parameter is removed.
Copy link sits at the top of each opened variant. The candidate chosen in the comparison panel is not part of the link.
The variant map does not keep its own view in the address bar. It links to the main map instead: a stop popup's Open in main map is the main map's stop link (?sloid= or ?osm=). The card's Main map button opens the main map on the variants the map shows, gtfs_variant and/or osm_variant (the candidate chosen in the comparison panel included), at the variant map's current #map= view. Both open in a new tab.
GTFS identity map
The /routes/gtfs-stop-id-sloid map keeps its view in #map= and the stop whose popup is open in sloid (ATLAS marker) or gtfs_stop_id (GTFS marker).
On load, a stop parameter runs the map's identifier search, as if sloid:… or stop_id:… had been typed into the search box. The search centres the map on the stop and shows it as an active filter; then the stop's popup opens. If the search finds nothing, its usual message appears under the search box and the parameter is removed.
Copy link sits in each ATLAS and GTFS card of a popup. The match-method and unmatched filters are not part of the link.
Limits
- Links name data of the published snapshot. SLOIDs, OSM ids and GTFS
stop_ids are stable, but GTFS itinerary ids contain the timetable year (j26), so a route list's variant link stops working when a new timetable is imported. The main map ignores the year ingtfs_variant, so its links keep working as long as the route keeps its number, letter, direction and headsign. - A Problems link opens the entry only while the stop still has a problem matching the link's filters.
Code
| File | Role |
|---|---|
static/js/shared/permalinks.js |
Shared rules: #map= hash, query rewriting, the open-item tracker, Copy link, the main map's stop parameters (stopParams) |
static/js/components/popup-renderer.js |
The Copy link buttons in stop popups (option permalinks) and Open in main map links (option mainMapUrl) |
static/js/pages/main.js |
Map: stop parameters and /api/stop_by_id on load; route variant parameters and /api/routes/variants on load |
static/js/pages/filters.js |
Map: the route chip's variants and the route variant parameters it keeps in the address bar |
static/js/pages/problems-permalink.js |
Problems: reading and writing filters and the entry |
static/js/pages/problems-data.js |
Problems: loading the linked page and earlier pages |
backend/blueprints/problems.py |
focus_sloid and focus_osm_node_id on /api/problems |
static/js/pages/routes.js |
Route lists: opening and naming variants; links from variant maps to the main map |
backend/pages/routes.py, backend/services/route_listing.py |
Route lists: canonical parameters of the three tabs; finding a variant's page |
static/js/pages/routes-gtfs-stop-id-sloid.js |
GTFS identity map: view, stop parameters and the linked search |
backend/services/url_query.py |
canonical_query_redirect(), with the characters each page leaves unencoded |
The tests are tests/js/permalinks.test.js, tests/js/map-permalinks.test.js, tests/js/route-variant-filter.test.js, tests/js/problems-permalink.test.js, tests/js/routes-permalinks.test.js, the permalink cases in tests/js/routes-gtfs-stop-id-sloid.test.js, tests/test_problems_permalinks.py and tests/test_routes_permalinks.py.