Edward Betts 3223d4b063 Add API docs page and update README/AGENTS

- Add /docs route serving web/templates/api.html: full Bootstrap 5
  documentation page covering all three API endpoints with parameter
  tables, example requests, and example responses
- Add 'API docs' link to the navbar on the main map page
- Update README.md: add web frontend section with feature list, dev
  server instructions, and API endpoint summary table
- Update AGENTS.md: add web/ layout, API endpoint table, Flask run
  instructions, and route_master example relation IDs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-02-27 19:03:37 +00:00

3.7 KiB

Raw Blame History

AGENTS.md

Guidelines for AI coding agents working in this repository.

Project overview

A collection of Python tools for working with OpenStreetMap public transport data. Includes a CLI tool and a Flask web frontend with a JSON API.

Repository layout

pyproject.toml              - Package metadata and build configuration
src/
  osm_geojson/
    __init__.py             - Top-level package marker
    py.typed                - Marker for mypy typed package
    pt/
      __init__.py           - Public transport subpackage
      core.py               - Data fetching and processing functions
      cli.py                - Click CLI commands
web/
  app.py                    - Flask application (routes + API endpoints)
  templates/
    index.html              - Main map UI
    api.html                - API documentation page (served at /docs)
  static/
    app.js                  - Frontend JavaScript
    style.css               - CSS for the map UI
    favicon.svg             - SVG favicon
tests/
  fixtures/                 - Saved OSM API responses for offline testing
  test_osm_pt_geojson.py    - Test suite
README.md                   - User-facing documentation
AGENTS.md                   - This file

osm_geojson is the top-level namespace for all tools in this collection. Each tool lives in its own subpackage (e.g. osm_geojson.pt), with its CLI entry point registered in pyproject.toml under [project.scripts].

Code conventions

Python 3.11+
CLI via Click
HTTP via Requests
Web frontend via Flask 3.x
Parse XML with lxml if needed; prefer the OSM JSON API where possible
Errors go to stderr; data output goes to stdout (CLI)
GeoJSON output uses ensure_ascii=False
All modules, functions, and test functions must have docstrings
Library code (core.py) raises OsmError instead of calling sys.exit(); the CLI and Flask views catch OsmError and handle it appropriately

OSM API

Tools fetch data from the public OSM API:

https://www.openstreetmap.org/api/0.6/

No authentication is required for read-only access. Include a descriptive User-Agent header in all requests.

Web frontend API endpoints

Endpoint	Description
`GET /api/route/<id>`	Full route GeoJSON, stop list, and sibling routes
`GET /api/segment/<id>?from=NAME&to=NAME[&stops=0]`	Segment between two named stops
`GET /api/route_master/<id>`	All member routes of a route_master
`GET /docs`	API documentation page

All API responses are JSON. Errors return {"error": "<code>", "message": "<text>"}.

Running the web frontend

cd web
flask --app app.py run

The web dependencies (Flask) are not in pyproject.toml; install separately:

pip install flask

Type checking

All code uses type hints. Run mypy in strict mode to check:

mypy --strict src/osm_geojson/

Testing

Run the test suite with:

pytest tests/

Tests use the responses library to mock HTTP calls and never hit the live OSM API. Fixture data is stored in tests/fixtures/ as saved API responses.

Example relations used during development

ID	Description
15083963	M11 Istanbul Metro (subway, direction 1)
15083964	M11 Istanbul Metro (subway, direction 2)
15083966	M11 Istanbul Metro (route_master)
18892969	Bus A1: Bristol Airport → Bus Station

Dependencies

Use a virtual environment. Install the package and test dependencies with:

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

3.7 KiB Raw Blame History