Requirements

Before installing the Webkul Magento 2 OpenStreetMap Address AutoComplete extension, verify that your server environment and Magento instance meet the following prerequisites.

Environment Compatibility

Magento Framework Dependencies

The extension integrates with core Magento checkout, customer, directory, sales, and UI modules, as declared in its composer.json:

{
  "name": "webkul/module-openstreetmapaddressautocomplete",
  "require": {
    "magento/framework": "103.0.*",
    "magento/module-backend": "102.0.*",
    "magento/module-customer": "103.0.*",
    "magento/module-checkout": "100.4.*",
    "magento/module-directory": "100.4.*",
    "magento/module-sales": "103.0.*",
    "magento/module-ui": "101.2.*",
    "webkul/module-base": "^4.0"
  }
}

Hyvä Theme Requirements

If your store uses the Hyvä Theme, you must also install the companion Hyvä compatibility module: Webkul_OpenStreetMapAddressAutoCompleteHyva.

The Hyvä module replaces the RequireJS-based JavaScript layer with a native inline script that integrates seamlessly with Alpine.js and Magewire-powered checkout pages. It requires no additional configuration beyond what is already set up in the base module.

Network & API Connectivity

Because autocomplete queries are resolved via server-side cURL requests (Webkul\OpenStreetMapAddressAutoComplete\Model\Api\Client), your web server must be capable of establishing outbound HTTPS connections:

1. Public Nominatim Service:
   • Host: https://nominatim.openstreetmap.org/search
   • Port: 443
   • Firewall: Allow outbound traffic from the web server IP to OpenStreetMap endpoints.
2. Self-Hosted Nominatim (Private Endpoint):
   • If hosting your own Nominatim instance inside a local network, ensure the internal URL is reachable from Magento PHP-FPM workers without proxy blocks.

You can verify server-side connectivity from your terminal:

curl -I -A "Magento2-Webkul-OpenStreetMapAddressAutoComplete/4.0.0 ([email protected])" \
  "https://nominatim.openstreetmap.org/search?q=London&format=jsonv2&limit=1"

A response of HTTP/2 200 confirms network connectivity.

Nominatim Usage Policy Compliance

When utilizing the free public OpenStreetMap Nominatim endpoint, merchants must adhere to the Nominatim Usage Policy:

• User-Agent Header: Nominatim requires a distinct, informative User-Agent header identifying the application and domain. The extension automatically generates this header.
• Contact Email: Providing a valid contact email in the module settings (openstreetmap_autocomplete/general/contact_email) appends your email to the User-Agent, enabling Nominatim administrators to contact you if query traffic requires attention rather than abruptly blocking your server IP.
• Rate Limit: The public Nominatim server limits client requests to a maximum of 1 request per second. The extension includes client-side keystroke debouncing (default: 300ms), minimum character thresholds (default: 3 chars), and in-memory caching to stay well within operational thresholds.
• Heavy Volume / Bulk Queries: For stores with high concurrent checkout traffic, deploying a self-hosted Nominatim container is recommended.

Filesystem Permissions

Ensure the Magento filesystem owner user (e.g., www-data or your server's deployment user) has appropriate read and write permissions to standard Magento directories:

chmod -R 775 app/code generated pub/static var
chown -R www-data:www-data app/code generated pub/static var