Edward Betts
3223d4b063
- 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>
125 lines
3.7 KiB
Markdown
125 lines
3.7 KiB
Markdown
# 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](https://click.palletsprojects.com/)
|
|
- HTTP via [Requests](https://requests.readthedocs.io/)
|
|
- Web frontend via [Flask](https://flask.palletsprojects.com/) 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]"
|
|
```
|