Extending Place Filters

Relevant source files

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

• src/lib/types.ts
• src/lib/planner.ts
• src/app/settings/page.tsx
• src/components/SpecsControls.tsx
• src/lib/p4n.ts
• src/components/Planner.tsx

Extending place filters in the P4N Map system involves modifying how the application evaluates and ranks Park4Night (P4N) locations and OpenStreetMap (OSM) amenities. The system distinguishes between "hard" filters—which unconditionally exclude results—and "soft" preferences, which influence the ranking score and UI badging without hiding the results.

The filtering logic is centralized in the planning engine, which processes a trip polyline against fetched places. This architecture allows for a flexible extension of the Specs and CorridorSettings data structures to support new van-life requirements, such as specific services (e.g., water, electricity) or proximity to external amenities like dog parks.
Sources: src/lib/planner.ts:1-12, src/lib/types.ts:109-130

Filtering Architecture

The filtering system operates through a multi-stage process where places are first fetched from the P4N API and then passed through a deterministic engine that applies user-defined specifications.

The diagram shows the logical flow from raw data ingestion to the final ranked list displayed in the UI.
Sources: src/lib/planner.ts:25-83, src/components/Planner.tsx:950-1010

Hard vs. Soft Filters

The system uses a specific logic to differentiate between strict requirements and user preferences.

Hard Filters

Hard filters are implemented in the matchesSpecs function. Currently, these are limited to the most critical exclusion criteria to ensure the map remains useful.

• Excluded Categories: Private and off-road places are always rejected as they are deemed not useful for van navigation.
• Minimum Rating: If specs.minRating is greater than 0, any place with a rating below this threshold is discarded.

Sources: src/lib/planner.ts:25-36, src/app/settings/page.tsx:216-224

Soft Preferences and Scoring

Preferences like requiredServices (e.g., showers, wifi) or nearDogPark do not reject places. Instead, they are used to calculate a composite score where a lower score is better.

Factor	Scoring Weight	Implementation Detail
Detour	+1.0 per km	Base cost is the km distance from the road.
Rating	Up to -1.5	A 5-star rating subtracts 1.5 km-equivalent from the cost.
Services	-0.4 per match	Each matched service from requiredServices improves the rank.
Dog Park	Up to -1.2	Proximity to an OSM dog park provides a bonus.

Sources: src/lib/planner.ts:85-117

Core Data Structures

To extend filters, developers must update the following interfaces defined in the domain types.

Specs Interface

The Specs object contains the criteria applied to P4N results.

export interface Specs {
  requiredServices: string[]; // Codes like 'point_eau', 'electricite'
  minRating: number;         // 0 to 5
  nearDogPark: boolean;      // Toggle for dog park proximity scoring
  dogParksEnRoute: boolean;  // Toggle for standalone OSM waypoints
}

Sources: src/lib/types.ts:109-118

CorridorSettings Interface

These settings define the physical boundaries of the search.

export interface CorridorSettings {
  maxKmFromRoad: number;         // Max perpendicular distance
  dogParkMaxKm: number;          // Search radius for dog parks near a spot
  dogParkMinKmFromStart: number; // Offset for en-route amenity display
}

Sources: src/lib/types.ts:120-126

UI Implementation of Filters

Filters are exposed to the user in two primary locations:

1. Settings Page: For persistent "must-have" defaults (e.g., black water disposal, showers).
2. SpecsControls Component: For trip-specific toggles (e.g., "I need water today").

Key Components

• SettingsPage: Normalizes P4N service dictionaries and allows users to toggle default requiredServices.
• SpecsControls: Provides range sliders for maxKmFromRoad and dogParkMaxKm, and "Quick Toggles" for immediate needs like water and electricity.

Sources: src/app/settings/page.tsx:15-50, src/components/SpecsControls.tsx:38-65

API and Service Integration

The filtering system relies on external data provided by the P4N API and OpenStreetMap via Overpass.

The sequence diagram illustrates how specifications are passed from the client to the server-side planning engine to fetch and filter data.
Sources: src/lib/p4n.ts:275-300, src/app/api/plan/route.ts:32-55, src/lib/client.ts:120-140

Extending the Filter Set

To add a new filter (e.g., "Laundry Services"):

1. Type Update: Add the relevant code to the MUST_HAVE_SERVICES list in src/app/settings/page.tsx.
2. Engine Update: Ensure the score function in src/lib/planner.ts accounts for the new service if it requires a specific weight.
3. UI Update: Add a corresponding icon to SERVICE_ICONS to ensure the badge renders correctly in the ResultList.

Sources: src/app/settings/page.tsx:18-28, src/lib/planner.ts:105-115, src/components/Planner.tsx:1145-1165

Conclusion

The place filtering system is a hybrid engine that combines strict spatial constraints (corridor width) with a flexible weighted scoring model for user preferences. By modifying the Specs structure and the score function, developers can easily introduce new criteria that help travelers find the most relevant spots without over-filtering the map data.