Nominatim Geocoding

Relevant source files

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

• src/app/api/geocode/route.ts
• src/lib/client.ts
• src/components/Planner.tsx
• README.md
• src/lib/types.ts

Nominatim Geocoding serves as the primary mechanism for converting free-text location queries into geographic coordinates (latitude and longitude) within the P4n Map application. It utilizes the open-source Nominatim service powered by OpenStreetMap data to facilitate the addition of trip waypoints by name, enabling users to plan multi-stop routes across different cities and landmarks.

The system is integrated as a server-side proxy route to comply with Nominatim's usage policies, such as providing descriptive User-Agents and handling API limits, while providing a clean internal interface for the frontend components.

Architecture and Data Flow

The geocoding process follows a standard client-server-external provider flow. The frontend Planner component triggers a search, which is proxied through a Next.js API route to the external Nominatim API.

Geocoding Sequence

The following diagram illustrates the interaction between the user interface, the internal API, and the OpenStreetMap Nominatim service:

API Implementation

Internal Endpoint: GET /api/geocode

The system exposes a dynamic API route that accepts a search query and returns a normalized list of geographic results.

Request Parameters:

Parameter	Type	Required	Description
q	string	Yes	The free-text location query (e.g., "Paris", "Berlin Hauptbahnhof").

Response Format:
The endpoint returns a JSON object containing an array of results with labels and coordinates.

{
  ok: true,
  results: [
    { label: string, lat: number, lng: number }
  ]
}

Sources: src/app/api/geocode/route.ts:10-39, src/lib/client.ts:117-121

External Provider Integration

The application specifically targets the jsonv2 format from Nominatim and enforces specific headers to meet the service's requirements.

• Endpoint: https://nominatim.openstreetmap.org/search
• User-Agent: p4n-map/0.1 (personal trip planner)
• Parameters:
  • format=jsonv2: Ensures a modern, consistent JSON response.
  • limit=5: Restricts results to the top 5 matches to optimize performance.
  • addressdetails=1: Requests detailed address information in the payload.

Sources: src/app/api/geocode/route.ts:15-24, README.md:21

Logic and Error Handling

The geocoding logic includes basic validation and error trapping to ensure system stability:

1. Input Validation: The API route checks for the presence of the q parameter and trims whitespace. If missing, it returns a 400 Bad Request.
2. External Request Management: The request includes an Accept-Language: en header to standardize result labels in English.
3. Data Transformation: The raw string coordinates (lat, lon) returned by Nominatim are explicitly converted to Number types before being sent to the client.
4. Error Propagation: Upstream failures (e.g., Nominatim downtime or rate limiting) are caught in a try...catch block and returned as a 502 Bad Gateway error with the specific message.

Sources: src/app/api/geocode/route.ts:11-38

Integration with Trip Planning

The results from the geocoding service are primarily used by the StopEditor within the Planner component. When a user selects a geocoded result, a new Stop object is created and added to the trip.

Data Structure: Stop

export interface Stop {
  id: string;
  label: string;
  lat: number;
  lng: number;
}

Sources: src/lib/types.ts:117-122, src/components/Planner.tsx:288-297

Summary

Nominatim Geocoding provides the entry point for trip creation in P4n Map by leveraging OpenStreetMap's global location database. By encapsulating the external API calls within a Next.js route, the project ensures reliable header management and data normalization, allowing the frontend to interact with a simple, typed interface for location searching.