Nominatim: reject suggest() per usage policy

The Nominatim usage policy forbids auto-complete: "you must not implement
such a service on the client side using the API". Implement suggest() so
that it throws a dedicated SuggestUnsupportedError referencing the policy,
rather than leaving the method absent.

Since the control feature-detects suggest() by its presence, it now catches
SuggestUnsupportedError, detaches the input listener and stops issuing
suggestion requests -- so the default geocoder keeps working on submit.

https://operations.osmfoundation.org/policies/nominatim/

Author: simon04

spec/nominatim.spec.ts

@@ -1,11 +1,19 @@
 import { afterEach, describe, expect, it, vi } from 'vite-plus/test';
 import { mockFetchRequest } from './mockFetchRequest';
 import { Nominatim, NominatimResponse } from '../src/geocoders/nominatim';
+import { SuggestUnsupportedError } from '../src/geocoders/api';
 
 describe('L.Control.Geocoder.Nominatim', () => {
   afterEach(() => vi.clearAllMocks());
   const geocoder = new Nominatim();
 
+  it('refuses to suggest, per the Nominatim usage policy', async () => {
+    await expect(geocoder.suggest('innsbruck')).rejects.toThrow(SuggestUnsupportedError);
+    await expect(geocoder.suggest('innsbruck')).rejects.toThrow(
+      /must not implement such a service/
+    );
+  });
+
   it('geocodes Innsbruck', async () => {
     const result = await mockFetchRequest(
       'https://nominatim.openstreetmap.org/search?q=innsbruck&limit=5&format=json&addressdetails=1',

src/control.ts

@@ -1,6 +1,11 @@
 import * as L from 'leaflet';
 import { Nominatim } from './geocoders/index';
-import { IGeocoder, GeocodingResult, GeocodingContext } from './geocoders/api';
+import {
+  IGeocoder,
+  GeocodingResult,
+  GeocodingContext,
+  SuggestUnsupportedError
+} from './geocoders/api';
 
 export interface GeocoderControlOptions extends L.ControlOptions {
   /**
@@ -144,6 +149,7 @@ export class GeocoderControl extends EventedControl {
   private _results: any;
   private _selection: any;
   private _suggestTimeout: any;
+  private _suggestUnsupported = false;
 
   /**
    * Instantiates a geocoder control (to be invoked using `new`)
@@ -317,9 +323,22 @@ export class GeocoderControl extends EventedControl {
     this.fire(suggest ? 'startsuggest' : 'startgeocode', event);
 
     const context: GeocodingContext = { map: this._map };
-    const results = suggest
-      ? await this.options.geocoder!.suggest!(value, context)
-      : await this.options.geocoder!.geocode(value, context);
+    let results: GeocodingResult[];
+    if (suggest) {
+      try {
+        results = await this.options.geocoder!.suggest!(value, context);
+      } catch (e) {
+        if (e instanceof SuggestUnsupportedError) {
+          // the geocoder's service forbids auto-complete — stop asking
+          this._suggestUnsupported = true;
+          L.DomEvent.off(this._input, 'input', this._change, this);
+          return;
+        }
+        throw e;
+      }
+    } else {
+      results = await this.options.geocoder!.geocode(value, context);
+    }
 
     if (requestCount === this._requestCount) {
       const event: FinishGeocodeEvent = { input: value, results };
@@ -454,6 +473,9 @@ export class GeocoderControl extends EventedControl {
   }
 
   private _change() {
+    if (this._suggestUnsupported) {
+      return;
+    }
     const v = this._input.value;
     if (v !== this._lastGeocode) {
       clearTimeout(this._suggestTimeout);

src/geocoders/api.ts

@@ -40,6 +40,18 @@ export interface GeocodingResult {
   properties?: any;
 }
 
+/**
+ * Thrown by {@link IGeocoder.suggest} when the backing geocoding service does not
+ * permit auto-complete style queries. The control catches this and stops issuing
+ * suggestion requests for the remainder of its lifetime.
+ */
+export class SuggestUnsupportedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SuggestUnsupportedError';
+  }
+}
+
 /**
  * An interface implemented to respond to geocoding queries
  */
@@ -54,6 +66,10 @@ export interface IGeocoder {
    * Performs a geocoding query suggestion (this happens while typing) and returns the results as promise
    * @param query the query
    * @param context the context for the query
+   *
+   * A geocoder whose backing service forbids auto-complete may implement this method
+   * and throw {@link SuggestUnsupportedError}, in which case the control silently
+   * disables suggestions instead of querying on every keystroke.
    */
   suggest?(query: string, context?: GeocodingContext): Promise<GeocodingResult[]>;
   /**

src/geocoders/nominatim.ts

@@ -1,6 +1,13 @@
 import * as L from 'leaflet';
 import { template, getJSON } from '../util';
-import { IGeocoder, GeocoderOptions, geocodingParams, GeocodingResult, reverseParams } from './api';
+import {
+  IGeocoder,
+  GeocoderOptions,
+  geocodingParams,
+  GeocodingResult,
+  reverseParams,
+  SuggestUnsupportedError
+} from './api';
 
 export type NominatimResponse = NominatimResult[];
 
@@ -108,6 +115,21 @@ export class Nominatim implements IGeocoder {
     });
   }
 
+  /**
+   * Auto-complete is explicitly forbidden by the Nominatim usage policy, which states:
+   * "Auto-complete search — This is not yet supported by Nominatim and you must not
+   * implement such a service on the client side using the API."
+   *
+   * @see https://operations.osmfoundation.org/policies/nominatim/
+   * @throws {SuggestUnsupportedError} always
+   */
+  async suggest(_query: string): Promise<GeocodingResult[]> {
+    throw new SuggestUnsupportedError(
+      'Nominatim forbids auto-complete search: "you must not implement such a service on ' +
+        'the client side using the API". See https://operations.osmfoundation.org/policies/nominatim/'
+    );
+  }
+
   async reverse(location: L.LatLngLiteral, scale: number) {
     const params = reverseParams(this.options, {
       lat: location.lat,