INFRASTRUCTURE MODULE — TOOLS
WordPress Route Planning Plugin — OSRM Routing, Live Tracking, and Map Integration
Add route calculation, address geocoding, and real-time location tracking to any WordPress site. Route Intelligence connects to OSRM for turn-by-turn directions, Nominatim for address-to-coordinate conversion, and Leaflet for interactive map rendering. The provider-swappable architecture starts with OSRM and is designed to support additional routing engines without code changes.
The Problem With WordPress Routing and Tracking
Most WordPress sites that need routing or live tracking end up gluing together three or four separate services: a Google Maps API key for directions, a different geocoding provider for address lookups, a JavaScript map library for rendering, and custom AJAX code to push location updates to the browser. Each service has its own authentication, rate limits, pricing tiers, and API format. When one provider changes its terms or raises prices, you rewrite the integration. When you need to swap from Google to Mapbox or from Mapbox to a self-hosted solution, you start over.
Route Intelligence solves this by providing a single WordPress module that handles routing, geocoding, map rendering, and live tracking through a provider-swappable architecture. The module ships with OSRM as its default routing engine and Nominatim for geocoding, both of which are open-source and can be self-hosted for zero API costs. Map tiles default to OpenStreetMap but can be pointed at any tile server. All configuration lives in one settings page, all tracking state flows through two AJAX endpoints, and the frontend shortcode handles the entire map display with a single tag.
Everything You Need for WordPress Route Planning
OSRM Routing Engine
Turn-by-Turn Directions With GeoJSON
The routing service sends origin and destination coordinates to your OSRM server and returns distance in meters, duration in seconds, full GeoJSON geometry for map polylines, and step-by-step maneuver instructions. Configure the OSRM base URL to point at the public demo server (router.project-osrm.org) or your own self-hosted instance. Select from five routing profiles: driving, driving-traffic, car, bike, and foot.
Nominatim Geocoding
Address to Coordinate Conversion
The geocoding service converts street addresses into latitude and longitude coordinates using the Nominatim API. Results are cached as WordPress transients for 7 days so repeated lookups for the same address never hit the API twice. Configure the Nominatim base URL to use the public OpenStreetMap instance or a self-hosted Nominatim server. Geocoding can be disabled entirely if you prefer to supply coordinates directly.
Leaflet Map Rendering
Interactive Maps With Route Polylines
The frontend loads Leaflet 1.9.4 for interactive map rendering. The map displays a technician marker at the current location, a destination marker at the target, and a GeoJSON route polyline connecting them. The map auto-fits bounds with 30-pixel padding so both markers are always visible. Tile source defaults to OpenStreetMap but can be changed to any XYZ tile server from the settings page.
Live Location Tracking
Real-Time Position Updates via AJAX
The tracking system uses two AJAX endpoints: luq_route_state (public, read-only) and luq_route_update (authenticated, write). The update endpoint accepts latitude, longitude, speed, and heading from the browser Geolocation API. The state endpoint returns the current position, destination, route geometry, ETA, and distance. Updates are throttled by a configurable interval (default 15 seconds) and minimum movement threshold (default 30 meters).
Privacy Radius
Location Masking Until the Tech Is Nearby
A configurable privacy radius (default 2 miles) prevents the live map from showing exact positions when the technician is near the origin. The system uses haversine distance calculation to determine whether the tech has traveled far enough from the starting point. While masked, the frontend shows a status message instead of the map. Once the tech moves beyond the privacy radius, the map reveals with full route and position data.
Provider-Swappable Architecture
OSRM First, Others Later
The Routing service delegates to provider classes through a clean interface. The current implementation routes through the Osrm provider class, but the architecture is designed so you can register additional providers without modifying existing code. The provider selection is stored as a single option key (provider) in the module settings. This means swapping from OSRM to a commercial routing API requires adding a new provider class and changing one setting.
Shortcode Display
Frontend Map With One Tag
The [luperiq_route_tracking] shortcode renders a complete tracking widget. Attributes include context_type, context_id, token, show_steps, role, and height. The role attribute switches between viewer (read-only polling) and tech (sends GPS updates via watchPosition). Steps display is an optional ordered list capped at 10 maneuvers. The shortcode only loads Leaflet and the frontend JavaScript on pages where it is actually used.
Self-Hosted OSRM Support
Zero API Costs at Any Scale
The module includes documentation for setting up a local OSRM instance using Docker. Download a regional OSM extract, build the routing graph with osrm-extract, osrm-partition, and osrm-customize, then run osrm-routed on localhost. Point the OSRM base URL at 127.0.0.1:5000 and every route calculation stays on your server with zero external API calls. A monthly refresh cron script keeps map data current.
Destination Resolution
Automatic Route Target Lookup
When a tracking update arrives and no destination is set, the system fires the luperiq_route_intel_resolve_destination filter. Other modules or custom code can hook into this filter to return a destination based on the context type and ID. Once resolved, the destination is stored as post meta and persists across tracking sessions. This allows service-based plugins to automatically pair a technician with their next job location.
Who This Module Is Built For
Any WordPress site that needs to calculate routes, display maps, or track moving entities in real time. Route Intelligence is the foundational infrastructure for service businesses with field workers, delivery platforms, logistics dashboards, or any use case where you need to show a person or vehicle moving toward a destination on a live map.
Service Business Owners
- Show customers a live map with their technician's position and estimated arrival time instead of asking them to wait by the phone.
- Use the privacy radius to mask exact locations near the dispatch origin so customers only see the technician when they are in the neighborhood.
- Embed the tracking widget on any page with a single shortcode and let the module handle all the map rendering and data polling.
WordPress Developers
- Use the Routing service class to calculate routes between any two coordinate pairs and get back distance, duration, geometry, and step-by-step instructions.
- Hook into the luperiq_route_intel_resolve_destination filter to automatically pair tracking sessions with job destinations from your custom post types.
- Swap the routing provider by adding a new provider class and changing one settings value, without touching the tracking, geocoding, or map rendering code.
Self-Hosted Infrastructure Teams
- Run OSRM on your own server using Docker and the included setup guide to eliminate all external routing API costs regardless of query volume.
- Self-host Nominatim for geocoding and point the map tiles at your own tile server for a fully private, zero-dependency mapping stack.
- Use the monthly refresh cron script to keep your local OSRM data current with the latest OpenStreetMap extracts without manual intervention.
How the Tracking System Works
The tracking system operates through two AJAX endpoints. The update endpoint (luq_route_update) is authenticated and nonce-protected. It receives latitude, longitude, speed, and heading from the browser Geolocation API. The state endpoint (luq_route_state) is publicly accessible but gated by a filter (luperiq_route_intel_can_view) and an optional token parameter, so you control who can see tracking data. Administrators can always view any tracking state.
When an update arrives, the system records the current position and checks whether a destination exists. If no destination is set, the luperiq_route_intel_resolve_destination filter fires once, giving other plugins a chance to supply coordinates. Once a destination is known, the system checks two conditions before requesting a new route: whether the current route is older than the max route age (default 45 seconds), or whether the technician has moved more than the minimum movement threshold (default 30 meters) since the last route calculation. If either condition is met, a fresh route is fetched from OSRM.
On the frontend, the JavaScript widget polls the state endpoint at the configured interval (default every 15 seconds). When the technician is within the privacy radius of the origin, the map is hidden and a masked status message is displayed. Once the technician moves beyond the privacy radius, the map appears with real-time position markers, a destination pin, a GeoJSON route polyline, and an ETA calculated from the OSRM response. If the widget is configured with role=tech, it also activates the browser watchPosition API to send GPS updates back to the server.
Configurable Settings
Every aspect of the routing, geocoding, and tracking pipeline is configurable from a single admin page under LuperIQ in the WordPress sidebar. All settings are sanitized and normalized on save.
Routing Provider and Profile
OSRM Base URL + Profile Selection
Set the OSRM base URL to the public demo server or your self-hosted instance. Choose from five routing profiles: driving, driving-traffic, car, bike, and foot. The profile determines how OSRM calculates routes and which road types it prefers.
Geocoder Configuration
Nominatim Base URL + Enable/Disable
Point the geocoder at the public Nominatim API or your own self-hosted instance. Disable geocoding entirely if you supply coordinates directly. When enabled, results are cached as transients for 7 days.
Map Tiles and Attribution
Tile URL Template + Attribution String
Set the map tile URL pattern using standard {s}, {z}, {x}, {y} placeholders. Defaults to OpenStreetMap tiles. Customize the attribution string displayed in the map corner.
Tracking Controls
Interval, Privacy Radius, Route Age, Movement Threshold
Configure the update interval (default 15 seconds, minimum 5), privacy radius (default 2 miles, minimum 0.1), maximum route age before recalculation (default 45 seconds, minimum 10), and minimum movement to trigger a new route (default 30 meters).
Frequently Asked Questions
Does this module require a paid API key?
No. Route Intelligence uses OSRM for routing and Nominatim for geocoding, both of which are open-source. The default configuration points at the free public demo servers. For production use, you can self-host both services on your own server with Docker for zero ongoing API costs at any query volume.
What is OSRM and why use it instead of Google Maps?
OSRM (Open Source Routing Machine) is a high-performance routing engine that uses OpenStreetMap data. It is free, open-source, and can be self-hosted. Unlike Google Maps, there are no per-request charges, no API key management, and no usage caps. OSRM returns the same data you need for navigation: distance, duration, GeoJSON geometry, and turn-by-turn steps.
Can I use this module without live tracking?
Yes. The routing and geocoding services work independently. You can use the Routing service class to calculate routes between coordinate pairs without enabling live tracking. You can also use the Geocoding service to convert addresses to coordinates. The live tracking feature is opt-in and controlled by the Enable live tracking setting.
How does the privacy radius work?
When tracking starts, the system records the first GPS position as the origin. On every subsequent update, it calculates the haversine distance between the current position and the origin. If the distance is less than the configured privacy radius (default 2 miles), the frontend shows a masked status message and hides the map. Once the distance exceeds the radius, the map appears with full position, route, and ETA data.
What happens if the OSRM server is unreachable?
Route calculations return an error state, and the tracking system continues recording position updates without route data. The frontend widget shows the ETA as Calculating and omits the route polyline. Once the OSRM server is reachable again, the next route calculation succeeds and the full display resumes.
Can I swap OSRM for a different routing provider?
Yes. The architecture routes all calculations through a Routing service that delegates to provider classes. The current provider is selected by a single settings key. To add a new provider, create a class that accepts origin and destination coordinates and returns the standard response format (ok, distance_m, duration_s, geometry, steps). Register it in the Routing service and select it in settings.
Does the shortcode work on any page?
Yes. The [luperiq_route_tracking] shortcode can be placed on any post, page, or custom post type. The frontend JavaScript and Leaflet library are only loaded on pages where the shortcode is detected, so there is no performance impact on pages that do not use it.
How do I set up a self-hosted OSRM server?
The module includes a step-by-step guide at wp-content/luperiq-modules/route_intelligence/docs/osrm-local-setup.md. The process uses Docker to download a regional OpenStreetMap extract, build the routing graph, and run the OSRM service on localhost port 5000. A monthly cron script is included to refresh the map data automatically.
Add Route Planning and Live Tracking to Your WordPress Site
Stop paying per-request fees for routing APIs and stop building custom AJAX tracking from scratch. Install LuperIQ, activate Route Intelligence, and get OSRM routing, Nominatim geocoding, Leaflet maps, and live location tracking from one module with one settings page.