OSRM Public Routing Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/osrm.ts
• src/app/api/plan/route.ts
• src/lib/planner.ts
• src/components/MapView.tsx
• src/lib/types.ts
• README.md

The OSRM (Open Source Routing Machine) integration provides the foundational planning geometry for the P4N Map application. Its primary purpose is to generate a multi-stop route polyline between coordinates (A → B → C) which is then used to define a search corridor for Park4Night spots and OpenStreetMap amenities.

Importantly, this integration is strictly for planning geometry. Turn-by-turn navigation is handed off to dedicated mobile applications like TomTom or Google Maps. The OSRM polyline serves as the spatial reference for sampling points, calculating perpendicular distances for corridor filtering, and rendering the route on the MapLibre GL canvas.

Sources: README.md:14-16, src/lib/osrm.ts:1-4

Architecture and Data Flow

The integration operates as a stateless utility that communicates with the public OSRM API. When a user adds stops in the UI, the application sends these coordinates to the internal /api/plan endpoint, which invokes the OSRM client to build a continuous route.

Routing Logic Flow

The following diagram illustrates how OSRM data flows from the initial request to the generation of a search corridor.

The application uses the driving profile from OSRM to ensure the planning geometry reflects road-based travel.

Sources: src/app/api/plan/route.ts:16-22, src/lib/osrm.ts:22-26, README.md:46-47

Implementation Details

The core logic resides in src/lib/osrm.ts. It utilizes a single base URL and a structured request pattern to fetch routing data.

Key Data Structures

The system uses specific interfaces to handle the response from OSRM and translate it into domain types used by the planner.

Structure	Purpose	Fields
PlannedRoute	Internal representation of OSRM results	polyline (LngLat[]), distanceKm, durationMin
RouteSummary	Compact summary for saved plans	polyline, distanceKm, durationMin
Stop	Waypoint definition	id, label, lat, lng

Sources: src/lib/osrm.ts:7-11, src/lib/types.ts:145-149, src/lib/types.ts:124-129

API Request Configuration

The integration targets the v1/driving service of OSRM. The coordinates are formatted as a semicolon-separated string of lng,lat pairs.

const OSRM_BASE = "https://router.project-osrm.org";
// ...
const coords = stops.map((s) => `${s.lng},${s.lat}`).join(";");
const url = `${OSRM_BASE}/route/v1/driving/${coords}?overview=full&geometries=geojson`;

Sources: src/lib/osrm.ts:5, src/lib/osrm.ts:25-26

Integration with Planning and Visualization

Once the OSRM polyline is retrieved, it is utilized by several other modules to perform spatial operations and visual rendering.

Corridor Search and Filtering

The polyline is sampled approximately every 20 km to query Park4Night places. The planner.ts module uses the pointToPolyline utility to calculate the perpendicular distance (detour) of potential spots from the OSRM-generated path.

Map Rendering

In MapView.tsx, the OSRM polyline is added to a MapLibre geojson source. A visual "corridor hint" is rendered as a wide, blurred green band around the route line to represent the allowed detour distance.

map.addSource("route", {
  type: "geojson",
  data: emptyLine(),
});
map.addLayer({
  id: "route-line",
  type: "line",
  source: "route",
  paint: { "line-color": "#4ade80", "line-width": 4 },
});

Sources: src/components/MapView.tsx:556-568, src/components/MapView.tsx:570-576

Error Handling and Constraints

The OSRM integration includes basic safety checks and error handling:

• Minimum Stops: A trip must have at least two stops to be valid for routing.
• Request Timeout: A 15-second timeout is enforced via AbortController to prevent hanging requests to the public server.
• Failures: If the OSRM API returns a code other than "Ok" or an empty route list, an error is thrown, which is subsequently handled by the /api/plan route.

Sources: src/lib/osrm.ts:22-24, src/lib/osrm.ts:28-34, src/app/api/plan/route.ts:50-57

Conclusion

The OSRM Public Routing Integration is the geometric backbone of the P4N Map application. By providing a high-fidelity GeoJSON polyline between user-defined stops, it enables complex spatial features such as search corridors, detour calculations, and look-ahead windows, while delegating the complexities of van-specific turn-by-turn navigation to external specialized apps.