add-ideas/pikebacker
1
0
Fork 0
Code Issues 16 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
pikebacker/services/api/README.md
Albrecht Degering abed21be21 Alpha stage commit
2026-07-02 21:04:05 +02:00

2.5 KiB
Raw Permalink Blame History

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.