77 lines
2.5 KiB
Markdown
77 lines
2.5 KiB
Markdown
# API Service
|
|
|
|
Purpose: trip planning, route/stage/POI/rule/offline/export endpoints.
|
|
|
|
MVP implementation should first work with mock providers and fixtures.
|
|
|
|
Provider interfaces:
|
|
|
|
- RoutingProvider.
|
|
- PoiProvider.
|
|
- ElevationProvider.
|
|
- WeatherProvider.
|
|
- RulesProvider.
|
|
- DeviceExportProvider.
|
|
|
|
Recommended backend:
|
|
|
|
- FastAPI or equivalent.
|
|
- PostgreSQL + PostGIS.
|
|
- Redis/worker for long-running imports/offline pack jobs.
|
|
|
|
See `schemas/openapi.yaml` and `schemas/database.sql`.
|
|
|
|
## Implemented MVP
|
|
|
|
This package currently uses an Express TypeScript API with mock providers, BRouter bikepacking routing, optional OSRM fallback, and optional Overpass POIs. It implements:
|
|
|
|
- `POST /v1/trips`
|
|
- `POST /v1/routes/plan`
|
|
- `POST /v1/stages/plan`
|
|
- `GET /v1/routes/:routeId/pois`
|
|
- `GET /v1/routes/:routeId/gaps`
|
|
- `GET /v1/rules`
|
|
- `POST /v1/offline-packs`
|
|
- `GET /v1/routes/:routeId/export?format=gpx`
|
|
- `POST /v1/reports`
|
|
|
|
Run locally:
|
|
|
|
```bash
|
|
npm -w @pikebacker/api run dev
|
|
```
|
|
|
|
The default provider mode is `mock`; it uses deterministic fixtures from `packages/shared` aligned with `examples/sample_trip_request.json`. A request can pass `provider: "brouter"` to use BRouter candidate selection or `provider: "osrm"` to use the configured OSRM endpoint. External routing/POI/rules providers return clear setup errors until their adapters and credentials are added.
|
|
|
|
For `provider: "brouter"`, the API maps Pikebacker profiles to candidate BRouter profiles and selects by Pikebacker suitability score:
|
|
|
|
- `loaded_gravel`: `gravel`, `safety`, `trekking`
|
|
- `beginner_safe`: `safety`, `trekking`, `gravel`
|
|
- `hardtail_bikepacking`: `gravel`, `mtb`, `trekking`
|
|
- `road_touring`: `trekking`, `fastbike-lowtraffic`, `safety`
|
|
- `ebikepacking`: `trekking`, `safety`, `gravel`
|
|
|
|
## Environment
|
|
|
|
```bash
|
|
PORT=8000
|
|
ROUTING_PROVIDER=mock
|
|
POI_PROVIDER=mock
|
|
RULES_PROVIDER=mock
|
|
OSRM_BASE_URL=https://router.project-osrm.org
|
|
OSRM_PROFILE=bike
|
|
BROUTER_BASE_URL=https://brouter.de/brouter
|
|
BROUTER_PROFILE=
|
|
OVERPASS_BASE_URL=https://overpass-api.de/api/interpreter
|
|
```
|
|
|
|
No API keys are required for mock mode, BRouter public routing, OSRM demo routing, or Overpass public POI lookup. Keep external provider keys in environment variables only. Public routing/POI endpoints are not production dependencies.
|
|
|
|
To try live OSM POIs:
|
|
|
|
```bash
|
|
POI_PROVIDER=overpass npm -w @pikebacker/api run dev
|
|
```
|
|
|
|
Public Overpass instances can time out or reject broad queries. The route planner degrades by returning the route with a warning if POI lookup fails.
|