edward/openstreetmap-tools
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Make public transport routes discoverable with shareable search

Browse source 
Add one-click examples and route search by number or metadata, with transport type, location and map-area filters. Preserve search filters and bounds in shareable URLs and restore searches on reload and browser navigation.

Validate with 91 passing tests, including desktop and mobile browser coverage, and strict mypy checks.

Closes #2
This commit is contained in:
Edward Betts 2026-09-30 22:23:45 +01:00
parent 29afb4f115
commit a79b0a7098
7 changed files with 919 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

32
web/templates/api.html
View file

@ -28,9 +28,35 @@
<p>All endpoints are read-only and require no authentication. Data is fetched
live from the <a href="https://wiki.openstreetmap.org/wiki/API_v0.6">OSM API v0.6</a>.
Relation IDs can be found on
<a href="https://www.openstreetmap.org">openstreetmap.org</a> — search for a
route and click through to its relation page.</p>
Route search uses <a href="https://wiki.openstreetmap.org/wiki/Overpass_API">Overpass</a>
to find relation IDs by route metadata.</p>
<h2><span class="badge bg-primary me-2">GET</span><code>/api/search?q=TEXT&amp;mode=TYPE</code></h2>
<p>Search worldwide for public transport <code>route</code> and <code>route_master</code>
relations. Required <code>q</code> is 2–100 characters. Route numbers (<code>ref</code>)
match exactly; names, termini, operators and networks match literal substrings,
case-insensitively. Optional <code>mode</code> filters by a supported transport type.</p>
<p>Optional <code>south</code>, <code>west</code>, <code>north</code> and <code>east</code>
coordinates restrict the search to routes with mapped members within a bounding box,
including their parent route masters. All four coordinates are required together.
Routes may extend outside the box. Bounds must be finite and ordered, span at most
20 degrees in either direction, and must not cross the date line.</p>
<p>Returns <code>{"routes": [...], "truncated": false}</code>. Each result has
<code>id</code>, <code>name</code>, <code>ref</code>, <code>from</code>, <code>to</code>,
<code>operator</code>, <code>network</code>, <code>route</code> (transport type) and
<code>type</code> (relation type). At most 50 results are returned; <code>truncated</code>
indicates more matches. No matches returns an empty list. Invalid input returns
400 <code>invalid_query</code>; upstream failures return 502 <code>osm_error</code>.</p>
<pre>GET /api/search?q=M11&amp;mode=subway</pre>
<pre>GET /api/search?q=24&amp;mode=bus&amp;south=51.39&amp;west=-2.73&amp;north=51.55&amp;east=-2.51</pre>
<h2><span class="badge bg-primary me-2">GET</span><code>/api/locations?q=PLACE</code></h2>
<p>Find up to five candidate places using Nominatim. Required <code>q</code> is 2–100
characters. Returns <code>{"locations": [{"label": "...", "bounds": [south, west, north, east]}]}</code>.
An empty list means no matching location. Invalid input returns 400 <code>invalid_query</code>;
upstream failures return 502 <code>osm_error</code>. Location lookups are submitted explicitly,
cached and limited to one upstream request per second per application process.</p>
<pre>GET /api/locations?q=Bristol%2C+UK</pre>
<p>All error responses return JSON with at least <code>error</code> (machine-readable
code) and <code>message</code> (human-readable description) fields.</p>