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:

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

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:

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.