# 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.