# 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 the `naptan:AtcoCode` recorded on UK bus
stops in OpenStreetMap. Search by postcode, street, place, exact ATCO code, or
browser location. Postcode, street, and place searches show up to 20
UK-only Nominatim matches for the user to choose from. Searches are preserved in shareable `?q=...` or
`?lat=...&lon=...` URLs, and `latitude, longitude` can be entered directly in
the search box. Selecting a stop shows its tags and stop-area-aware bus route
relations. Stop results identify their transport mode (such as bus, rail or
tram), and moving the map at zoom level 15 or closer loads stops in the visible
area. Wider map views deliberately do not query Overpass.
Postcode searches with exactly one Nominatim match skip the choice screen.
The current map bounds bias Nominatim's ranking without excluding UK matches
outside the visible area.

Selecting a stop replaces the search parameters with a shareable stop URL such
as `?node=485403163` (or `?way=...` / `?relation=...` for other OSM object
types). Refreshing that URL fetches and reopens the same stop.

UK stop queries use the Britain-and-Ireland Overpass instance at
`overpass.atownsend.org.uk`, with `overpass.private.coffee` as an automatic
fallback when the primary service is unavailable.

Run it locally with:

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

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.