Update gsm/nominatim geocoder implementation with user agent support and fix cache bug (#287)

rtpHarry · web-flow · commit 533af1df8a34 · 2026-03-16T12:30:16.000-03:00
* feat(geocoder): rewrite osm geocoder with new endpoint, user agent, and wp_remote_get

* feat(geocoder): add accept-language based on gotcha tip in nominatim docs

* fix(geocoder): throw exception on fail instead of polluting cache with false as an object

* refactor(geocoder): don't reuse var in endpoint url

* feat(geocoder): osm lazy cache self-healing

* feat(plugin-option): add placeholder support to input text

* feat(plugin-settings): add nominatim_contact_email support

* feat(geocode): add leaflet_map_nominatim_contact_email filter

* docs(readme): document setting and filter for the nominatim contact email sent in the geocoder user agent

* fix(geocoder): only use site language otherwise the global cache can end up multilingual depending on the users language
diff --git a/README.md b/README.md
@@ -110,6 +110,14 @@ However, you can also just give it an address, and the chosen geocoder (default:
 [leaflet-map address="Oslo, Norway"]
 ```
 
+When using the OpenStreetMap Nominatim geocoder, the plugin sends a contact email in the request user agent. By default this uses the site admin email, but you can override it in the plugin settings with `Nominatim Contact Email (optional)` or in code with the `leaflet_map_nominatim_contact_email` filter.
+
+```php
+add_filter('leaflet_map_nominatim_contact_email', function ($email) {
+    return 'maps@example.com';
+});
+```
+
 #### [leaflet-map] Options:
 
 | Option                       | Default                                              |
diff --git a/class.geocoder.php b/class.geocoder.php
@@ -44,22 +44,32 @@ public function __construct ($address) {
         /* retrieve cached geocoded location */
         $found_cache = get_option( $cached_address );
 
-        if ( $found_cache ) {
+        if ( $this->is_valid_cached_location( $found_cache ) ) {
             $location = $found_cache;
         } else {
+            if ( false !== $found_cache ) {
+                $this->remove_cache_key( $cached_address );
+            }
+
             // try geocoding
             $geocoding_method = $geocoder . '_geocode';
 
             try {
                 $location = (Object) $this->$geocoding_method( $address );
 
+                if ( ! $this->is_valid_cached_location( $location ) ) {
+                    throw new Exception('Invalid geocoder response');
+                }
+
                 /* add location */
                 add_option($cached_address, $location);
 
                 /* add option key to locations for clean up purposes */
                 $locations = get_option('leaflet_geocoded_locations', array());
-                array_push($locations, $cached_address);
-                update_option('leaflet_geocoded_locations', $locations);
+                if ( ! in_array( $cached_address, $locations, true ) ) {
+                    array_push($locations, $cached_address);
+                    update_option('leaflet_geocoded_locations', $locations);
+                }
             } catch (Exception $e) {
                 // failed
                 $location = $this->not_found;
@@ -83,6 +93,51 @@ public static function remove_caches () {
         delete_option('leaflet_geocoded_locations');
     }
 
+    /**
+    * Determines whether a cached geocode entry is valid.
+    *
+    * @param mixed $location Cached location value from WordPress options.
+    * @return bool
+    */
+    private function is_valid_cached_location( $location ) {
+        if ( ! is_object( $location ) ) {
+            return false;
+        }
+
+        if ( ! isset( $location->lat ) || ! isset( $location->lng ) ) {
+            return false;
+        }
+
+        return filter_var( $location->lat, FILTER_VALIDATE_FLOAT ) !== false
+            && filter_var( $location->lng, FILTER_VALIDATE_FLOAT ) !== false;
+    }
+
+    /**
+    * Removes a single geocode cache entry and its registry reference.
+    *
+    * @param string $cached_address Option key for the cached geocode.
+    * @return void
+    */
+    private function remove_cache_key( $cached_address ) {
+        delete_option( $cached_address );
+
+        $addresses = get_option( 'leaflet_geocoded_locations', array() );
+        $addresses = array_values(
+            array_filter(
+                $addresses,
+                function ( $address ) use ( $cached_address ) {
+                    return $address !== $cached_address;
+                }
+            )
+        );
+
+        if ( empty( $addresses ) ) {
+            delete_option( 'leaflet_geocoded_locations' );
+        } else {
+            update_option( 'leaflet_geocoded_locations', $addresses );
+        }
+    }
+
     /**
     * Used by geocoders to make requests via curl or file_get_contents
     *
@@ -158,24 +213,51 @@ private function google_geocode ( $address ) {
     /**
     * OpenStreetMap geocoder Nominatim (https://nominatim.openstreetmap.org/)
     *
-    * @param string $address    the urlencoded address to look up
-    * @return varies object from API or null (failed)
+    * @param string $address The URL-encoded address to look up.
+    * @return object Object containing lat and lng properties.
+    * @throws Exception When the request fails or no valid coordinates are returned.
     */
+    private function osm_geocode( $address ) {
+        $request_url = sprintf(
+            'https://nominatim.openstreetmap.org/search?format=jsonv2&limit=1&q=%s',
+            $address
+        );
 
-    private function osm_geocode ( $address ) {
-        $geocode_url = 'https://nominatim.openstreetmap.org/?format=json&limit=1&q=';
-        $geocode_url .= $address;
-        $json = $this->get_url($geocode_url);
-        $json = json_decode($json);
+        $accept_language = str_replace( '_', '-', get_locale() );
+        
+        $settings = Leaflet_Map_Plugin_Settings::init();
+        $contact_email = $settings->get( 'nominatim_contact_email' );
 
-        if (isset($json[0]->lat) && isset($json[0]->lon)) {
-            return (Object) array(
-                'lat' => $json[0]->lat,
-                'lng' => $json[0]->lon,
-            );
-        } else {
-            return false;
+        if ( empty( $contact_email ) ) {
+            $contact_email = get_bloginfo( 'admin_email' );
         }
+
+        $contact_email = apply_filters( 'leaflet_map_nominatim_contact_email', $contact_email );
+
+        $agent = 'Nominatim query for ' . get_bloginfo( 'url' ) . '; contact ' . $contact_email;
+
+        $response = wp_remote_get(
+            $request_url,
+            array(
+                'user-agent' => $agent,
+                'headers' => array(
+                    'Accept-Language' => $accept_language,
+                ),
+            )
+        );
+
+        if ( ! is_wp_error( $response ) && isset( $response['body'] ) ) {
+            $json = json_decode( $response['body'] );
+
+            if ( isset( $json[0]->lat ) && isset( $json[0]->lon ) ) {
+                return (object) array(
+                    'lat' => $json[0]->lat,
+                    'lng' => $json[0]->lon,
+                );
+            }
+        }
+
+        throw new Exception('No Address Found');
     }
 
     /**
@@ -198,4 +280,4 @@ private function dawa_geocode ( $address ) {
             'lng' => $json[0]->adgangsadresse->adgangspunkt->koordinater[0]
         );
     }
-}
+}
diff --git a/class.plugin-option.php b/class.plugin-option.php
@@ -55,6 +55,7 @@ class Leaflet_Map_Plugin_Option
     public $min = 0;
     public $max = 0;
     public $step = 0;
+    public $placeholder = '';
 
     /**
      * Instantiate class
@@ -76,6 +77,7 @@ function __construct($details = array())
             'min'              =>     FILTER_DEFAULT,
             'max'              =>     FILTER_DEFAULT,
             'step'             =>     FILTER_DEFAULT,
+            'placeholder'      =>     FILTER_SANITIZE_FULL_SPECIAL_CHARS,
             'options'          =>     array(
                 'filter' => FILTER_SANITIZE_FULL_SPECIAL_CHARS,
                 'flags'  => FILTER_FORCE_ARRAY
@@ -112,6 +114,7 @@ class="full-width"
             name="<?php echo $name; ?>" 
             type="<?php echo $this->type; ?>" 
             id="<?php echo $name; ?>" 
+            placeholder="<?php echo htmlspecialchars($this->placeholder); ?>"
             value="<?php echo htmlspecialchars($value); ?>" 
             />
             <?php
@@ -181,4 +184,4 @@ class="full-width">
             break;
         }
     }
-}
+}
diff --git a/class.plugin-settings.php b/class.plugin-settings.php
@@ -346,6 +346,19 @@ private function __construct()
                 ),
                 'helptext' => __('Select the Geocoding provider to use to retrieve addresses defined in shortcode.', 'leaflet-map')
             ),
+            'nominatim_contact_email' => array(
+                'display_name'=>__('Nominatim Contact Email (optional)', 'leaflet-map'),
+                'default' => '',
+                'type' => 'text',
+                'placeholder' => sprintf(
+                    __('defaults to admin email (%s)', 'leaflet-map'),
+                    get_bloginfo('admin_email')
+                ),
+                'helptext' => __(
+                    'Optional contact email to send with OpenStreetMap Nominatim geocoding requests. If blank, the site admin email will be used.',
+                    'leaflet-map'
+                ),
+            ),
             'google_appkey' => array(
                 'display_name'=>__('Google API Key (optional)', 'leaflet-map'),
                 'default' => __('Supply a Google API Key', 'leaflet-map'),
diff --git a/readme.txt b/readme.txt
@@ -28,6 +28,10 @@ Lookup an address with:
 
 `[leaflet-map address="chicago"]`
 
+When using the OpenStreetMap Nominatim geocoder, the plugin sends a contact email in the request user agent. By default this uses the site admin email, but you can override it in the plugin settings or with the `leaflet_map_nominatim_contact_email` filter.
+
+`add_filter('leaflet_map_nominatim_contact_email', function ($email) { return 'maps@example.com'; });`
+
 Know the latitude and longitude of a location? Use them (and a zoom level) with:
 
 `[leaflet-map lat=44.67 lng=-63.61 zoom=5]`
