Overpass API Integration

Relevant source files

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

• src/lib/overpass.ts
• src/app/api/amenities/route.ts
• src/lib/search.ts
• src/lib/types.ts
• src/app/api/assistant/route.ts
• src/components/Planner.tsx

The Overpass API Integration serves as the primary mechanism for fetching OpenStreetMap (OSM) Points of Interest (POIs) within the project. It complements Park4Night data by providing "Along the way" amenities such as dog parks, supermarkets, fuel stations, toilets, and drinking water. These results are dynamically filtered to a corridor surrounding the user's planned trip polyline.

This integration allows the application to perform complex spatial queries, such as finding amenities within a specific radius of sampled points along a route or within a bounding box. It handles the complexities of public Overpass instances, including rate limiting and mirror failover, to ensure reliable data retrieval for van trip planning.

Sources: src/lib/overpass.ts:1-12, README.md, src/app/api/amenities/route.ts:20-22

Core Architecture and Data Flow

The integration is built around a central library that communicates with multiple public Overpass API endpoints. The system uses a rotation strategy to handle aggressive rate-limiting (429) and server timeouts from public infrastructure.

Component Interaction Diagram

The following diagram illustrates how the frontend components and API routes interact with the Overpass integration library to retrieve POI data.

Failover and Backoff Logic

To ensure high availability, the fetchOverpass function implements a retry loop across three major public mirrors. It specifically listens for status codes 429 (Rate Limited), 504 (Gateway Timeout), and 5xx (Server Errors). Between full rounds of mirror checks, the system performs an incremental sleep backoff.

Sources: src/lib/overpass.ts:7-11, src/lib/overpass.ts:77-112

Supported Amenity Kinds

The system maps internal AmenityKind types to specific OSM tag selectors using the Overpass QL nwr (nodes, ways, relations) syntax.

AmenityKind	OSM Selector	Default UI Label
dog_park	nwr["leisure"="dog_park"]	Dog park
supermarket	nwr["shop"="supermarket"]	Supermarket
fuel	nwr["amenity"="fuel"]	Petrol station
toilets	nwr["amenity"="toilets"]	Toilets
drinking_water	nwr["amenity"="drinking_water"]	Drinking water

Sources: src/lib/overpass.ts:31-45, src/lib/overpass.ts:153-167, src/lib/types.ts:114-114

Query Strategies

The integration utilizes two distinct spatial query patterns depending on the density of the amenity and the length of the trip.

Corridor Search (around:)

For dense amenities like fuel or supermarkets, the system avoids large bounding box queries which might return excessive data. Instead, it samples the trip polyline (capped at 35 samples) and generates an around:radius clause for each sample point.

1. Sampling: The polyline is thinned to MAX_AROUND_SAMPLES.
2. Query Generation: A union query is created containing nwr[selector](around:radius, lat, lng) for every point.
3. Deduplication: Since around circles often overlap, results are deduped by their OSM ID (type/id).

Sources: src/lib/overpass.ts:19, src/lib/overpass.ts:133-149, src/lib/search.ts:152-155

Bounding Box Search

Used primarily for sparse amenities like dog parks, this method queries a bounding box derived from the trip polyline, padded by the corridor width.

const query = `[out:json][timeout:25];(${selector(kind)}(${bboxStr}););out center tags;`;

Sources: src/lib/overpass.ts:121-127, src/lib/search.ts:54-57

Data Structures

The system converts raw Overpass Element objects into a flattened OsmPoi structure used throughout the application.

Overpass Element (External)

Field	Type	Description
id	number	OSM element ID
type	string	element type (node, way, relation)
lat / lon	number	Coordinates (nodes)
center	object	Centroid coordinates (ways/relations)
tags	record	OSM tags (e.g., name)

Sources: src/lib/overpass.ts:21-28

OsmPoi (Internal)

Field	Type	Description
id	string	Formatted as ${type}/${id}
kind	AmenityKind	The category of amenity
name	string	Tagged name or default fallback
lat / lng	number	Geographical coordinates
kmFromRoad	number	Perpendicular distance to the route (calculated)
progressKm	number	Distance along the route (calculated)

Sources: src/lib/overpass.ts:57-67, src/lib/types.ts:116-123

AI Assistant Integration

The Overpass integration is exposed to the Gemini AI assistant through the search_amenity action. When a user asks for an amenity via voice (e.g., "find fuel in the next 30km"), the assistant route triggers an amenitySearch.

Implementation Details: Endpoint Configuration

The integration targets three specific mirrors to distribute load and handle local variations in availability:

1. https://overpass-api.de/api/interpreter
2. https://overpass.kumi.systems/api/interpreter
3. https://overpass.osm.ch/api/interpreter

A custom User-Agent (p4n-map/1.0) is used to identify the traffic as per OSM usage policies.

Sources: src/lib/overpass.ts:7-13

Summary

The Overpass API Integration provides a resilient, corridor-aware POI discovery system. By combining polyline sampling, multi-mirror failover, and efficient spatial queries, it enables the "Along the way" feature set essential for planning van travel logistics. It effectively bridges the gap between high-level trip geometry and granular map data.