openstreetmap-tools/README.md

# openstreetmap-tools

A collection of tools for working with OpenStreetMap public transport data.

## Tools

### osm-pt-geojson

Fetch an OSM public transport route relation and list its stops, or export the
route as GeoJSON.

#### CLI usage

```
osm-pt-geojson list-stations <relation_id>
osm-pt-geojson route-between <relation_id> <from_station> <to_station> [-o FILE]
osm-pt-geojson full-route <relation_id> [-o FILE]
```

**List stops on a route:**
```
$ osm-pt-geojson list-stations 18892969
Route: Bus A1: Bristol Airport → Bristol Bus Station
Stops (21):
   1. Airport Terminal
   2. Airport Tavern
   ...
  21. Bus Station
```

**Export a segment between two stops as GeoJSON:**
```
$ osm-pt-geojson route-between 18892969 "Airport Terminal" "East Street" -o segment.geojson
```

**Export the full route as GeoJSON:**
```
$ osm-pt-geojson full-route 18892969 -o route.geojson
```

**Omit stop points from GeoJSON output:**
```
$ osm-pt-geojson full-route 18892969 --no-stops -o route.geojson
```

GeoJSON is written to stdout if `-o` is not given.

#### Output format

A GeoJSON `FeatureCollection` containing:

- A `LineString` feature for the route geometry, with `name`, `ref`, `from`,
  `to`, and `route` properties from the OSM relation tags.
- A `Point` feature for each stop, with a `name` property (omitted with
  `--no-stops`).

#### Installation

```
pip install osm-geojson
```

Or from source:
```
git clone https://git.4angle.com/edward/openstreetmap-tools
cd openstreetmap-tools
pip install -e .
```

---

### Web frontend

An interactive map interface for browsing and downloading public transport
routes as GeoJSON.

#### Features

- Enter a relation ID or OSM URL to load a route onto the map.
- Click stops in the sidebar list or on the map to set start and end points.
- Preview the selected segment highlighted on the map.
- Toggle stop points in/out of the GeoJSON before downloading.
- Download a segment or the full route as a `.geojson` file.
- Entering a `route_master` ID shows all directions on the map with links to
  each individual route.
- Bookmarkable URLs: `/<relation_id>` loads that route directly.

#### Running the dev server

```
pip install -e ".[web]"
flask --app web/app.py run
```

Open `http://127.0.0.1:5000`.

#### API

The web frontend exposes a JSON API. Full documentation is available at `/docs`
when the server is running.

| Endpoint | Description |
|---|---|
| `GET /api/route/<id>` | Full route GeoJSON, stop list, and sibling routes |
| `GET /api/segment/<id>?from=NAME&to=NAME` | Segment between two named stops |
| `GET /api/route_master/<id>` | All member routes of a route_master |

---

### UK Bus Stop Finder

A mobile-friendly map for finding ATCO codes using the Department for Transport's
[NaPTAN dataset](https://beta-naptan.dft.gov.uk/download). It covers active public
transport stops in England, Scotland and Wales, including bus, rail, tram,
ferry and airport access points; Northern Ireland is not included.

Search by postcode, street, place, exact ATCO code, coordinates or browser
location. Place searches use Nominatim, with the visible map as a ranking bias.
The map loads stops at zoom level 15 or closer. Selecting a stop shows its
NaPTAN fields and looks up bus routes in OpenStreetMap by matching its ATCO code.
OSM route coverage may be incomplete; NaPTAN itself does not contain routes or
live departures. An Overpass outage does not prevent NaPTAN stop searches.

Searches have shareable `?q=...` and `?lat=...&lon=...` URLs; a selected NaPTAN
stop uses `?naptan=010000056`. Existing `?node=...`, `?way=...` and
`?relation=...` OSM links still work.

Download the national CSV from NaPTAN, then import it and start the app:

```sh
python3 -m venv .venv
.venv/bin/pip install -e ".[web]"
.venv/bin/uk-bus-stops-import-naptan Stops.csv
.venv/bin/flask --app uk_bus_stops.app run
```

The importer uses SQLite's built-in R-tree spatial index; no database server or
SpatiaLite extension is required. It preserves leading zeros in ATCO codes,
converts British National Grid coordinates when latitude/longitude are absent,
and reports imported, inactive/pending, invalid and converted row counts.
Only active records with usable positions are included. The original CSV fields
remain available in the detail panel. XML is not needed.

The default database is `data/naptan.sqlite3` in the project directory. Set
`NAPTAN_DATABASE=/absolute/path/naptan.sqlite3` for both import and serving, or
use `--database PATH` for the importer. The serving process needs read access.
To refresh, download a new CSV and rerun the same command. It builds a temporary
database alongside the destination and replaces the old snapshot atomically;
a failed import leaves the old snapshot intact. Downloads and databases are
excluded from git. The app returns a JSON 503 with import instructions if its
database is missing or unreadable.

NaPTAN is the default stop source. Set `UK_BUS_STOPS_SOURCE=osm` to retain
Overpass stop searches instead. OSM route queries use `overpass.atownsend.org.uk`,
with `overpass.private.coffee` as a fallback.

The production URL is `https://openstreetmap.tools/uk-bus-stops/`.
The app's `/about` page documents shareable URL parameters, map behaviour,
data sources, privacy considerations, and JSON endpoints.

Browser tests use Python Playwright. After installing the development extras,
install Chromium once and run the suite:

```
playwright install chromium
pytest tests/
```

---

## Licence

MIT License. Copyright (c) 2026 Edward Betts.