feat: add ?dst and ?src URL params for address-based deep-linking (#405)

Allow third-party sites to link to the OSRM frontend with a pre-set
destination (and optionally an origin) by address string, without
needing to look up coordinates first.

New URL parameters:
  ?dst=<address>  destination address (geocoded on load)
  ?src=<address>  origin address (geocoded on load, optional)

These are one-time deep-link parameters. On page load they are resolved
via Nominatim and replaced in the URL by loc= coordinate pairs through
the existing state machinery. They are ignored when loc= waypoints are
already present, so existing sessions are not affected.

Example usage:
  https://map.project-osrm.org/?dst=Berlin
  https://map.project-osrm.org/?src=Paris&dst=Berlin

Changes:
- src/links.js: parse q.src/q.dst → originAddress/destinationAddress
- src/index.js: geocode address params after LRM init, set waypoints
- test/links.test.js: 10 new unit tests for parse/format behaviour

Closes #337

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: DennisOSRM

src/index.js

@@ -208,6 +208,42 @@ plan.on('waypointgeocoded', function(e) {
   }
 });
 
+// If dst/src address params were passed and no loc= waypoints exist, geocode them now.
+(function applyAddressParams() {
+  var hasLocWaypoints = mergedOptions.waypoints && mergedOptions.waypoints.some(function(wp) {
+    return wp && wp.latLng;
+  });
+  if (hasLocWaypoints) return;
+
+  var srcAddr = mergedOptions.originAddress;
+  var dstAddr = mergedOptions.destinationAddress;
+  if (!srcAddr && !dstAddr) return;
+
+  var geocoder = createGeocoder.coordPreserving();
+
+  function geocodeAddress(addr, cb) {
+    if (!addr) {
+      cb(null);
+      return;
+    }
+    geocoder.geocode(addr, function(results) {
+      cb(results && results.length > 0 ? results[0] : null);
+    });
+  }
+
+  geocodeAddress(srcAddr, function(srcResult) {
+    geocodeAddress(dstAddr, function(dstResult) {
+      var origin = srcResult
+        ? L.Routing.waypoint(srcResult.center, srcResult.name)
+        : L.Routing.waypoint(null, srcAddr || '');
+      var destination = dstResult
+        ? L.Routing.waypoint(dstResult.center, dstResult.name)
+        : L.Routing.waypoint(null, dstAddr || '');
+      lrmControl.setWaypoints([origin, destination]);
+    });
+  });
+}());
+
 // add onClick event
 map.on('click', function (e) {
   addWaypoint(e.latlng);

src/links.js

@@ -80,6 +80,8 @@ function parseLink(link) {
     parsedValues.units = q.df;
     parsedValues.layer = q.ly;
     parsedValues.service = q.srv;
+    parsedValues.originAddress = q.src;
+    parsedValues.destinationAddress = q.dst;
   } catch (e) {
     console.log("Exception " + e.name + ": " + e.message);
   }

test/links.test.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// Mock leaflet and leaflet-routing-machine so tests run in Node without a DOM
+jest.mock('leaflet', () => ({
+  latLng: function(lat, lng) { return { lat: lat, lng: lng }; },
+  Routing: {
+    waypoint: function(latlng, name) { return { latLng: latlng, name: name || '' }; }
+  }
+}));
+jest.mock('jsonp', () => {});
+
+const links = require('../src/links');
+
+describe('links.parse — dst/src address parameters', () => {
+  test('parses ?dst into destinationAddress', () => {
+    const result = links.parse('dst=Berlin');
+    expect(result.destinationAddress).toBe('Berlin');
+  });
+
+  test('parses ?src into originAddress', () => {
+    const result = links.parse('src=Paris');
+    expect(result.originAddress).toBe('Paris');
+  });
+
+  test('parses both ?src and ?dst together', () => {
+    const result = links.parse('src=Paris&dst=Berlin');
+    expect(result.originAddress).toBe('Paris');
+    expect(result.destinationAddress).toBe('Berlin');
+  });
+
+  test('parses address strings with spaces and special characters', () => {
+    const result = links.parse('dst=New%20York%2C%20NY');
+    expect(result.destinationAddress).toBe('New York, NY');
+  });
+
+  test('returns undefined originAddress when src is absent', () => {
+    const result = links.parse('dst=Berlin');
+    expect(result.originAddress).toBeUndefined();
+  });
+
+  test('returns undefined destinationAddress when dst is absent', () => {
+    const result = links.parse('src=Paris');
+    expect(result.destinationAddress).toBeUndefined();
+  });
+
+  test('dst/src absent from result when empty string', () => {
+    const result = links.parse('dst=&src=');
+    // Empty strings are filtered out by the existing options filtering logic
+    expect(result.destinationAddress).toBeUndefined();
+    expect(result.originAddress).toBeUndefined();
+  });
+});
+
+describe('links.format — dst/src are not serialized', () => {
+  test('formatLink does not include dst in output', () => {
+    const L = require('leaflet');
+    const output = links.format({
+      zoom: 13,
+      center: L.latLng(52.5, 13.4),
+      waypoints: [],
+      language: 'en',
+      destinationAddress: 'Berlin',
+      originAddress: 'Paris'
+    });
+    expect(output).not.toContain('dst=');
+    expect(output).not.toContain('src=');
+  });
+});
+
+describe('links.parse — existing loc= params still work', () => {
+  test('parses loc= coordinate pairs normally', () => {
+    const result = links.parse('loc=52.5,13.4&loc=48.8,2.3');
+    expect(result.waypoints).toHaveLength(2);
+    expect(result.waypoints[0].latLng.lat).toBeCloseTo(52.5);
+    expect(result.waypoints[1].latLng.lat).toBeCloseTo(48.8);
+  });
+
+  test('dst and src are parsed alongside loc= without conflict', () => {
+    const result = links.parse('loc=52.5,13.4&loc=48.8,2.3&dst=Lyon');
+    expect(result.waypoints).toHaveLength(2);
+    expect(result.destinationAddress).toBe('Lyon');
+  });
+});