Dealer Locator

Version v1.0.0
Platform Magento 2
Module Released 18 November 2026

Magento 2 Dealer Locator Best Practices

Looking for Dealer Locator? View the full Dealer Locator page to explore features, configuration options, and pricing.

These are our recommendations for setting up the Dealer Locator well, based on how dealer networks are usually organised. You'll find a few complete example setups, from a single-country shop on OpenStreetMap to a multi-country, multi-language store on Google Maps, plus advice on keeping your dealer list up to date, privacy, performance and API key security. We end with the mistakes we see most often and some tips for developers who want to adjust the page to their theme. Take what fits your situation: none of this is required for the module to work, but it saves you time and support questions later.

Recommended configurations and patterns for the Dealer Locator.

General Guidelines

Do's

✅ Give every dealer a stable code, such as your customer number, so imports always update the right dealer
✅ Keep your dealer list in a spreadsheet or export it from your ERP, and re-import it after changes
✅ Run a new import file with "Validate only" first
✅ Check the dealer grid for On Map: No after every import
✅ Restrict both Google API keys in Google Cloud
✅ Run the self-test after changing map settings
✅ Translate product category names per store view in multi-language stores

Don'ts

❌ Don't change dealer codes: a new code creates a new dealer instead of updating the old one
❌ Don't use the same Google key for the browser and the server
❌ Don't leave a Google key unrestricted: the browser key is visible to anyone
❌ Don't enter coordinates for all dealers by hand when the address lookup can do it
❌ Don't put opening hours or notes in the name field; they are shown as part of the name everywhere

Common Scenarios

Scenario 1: Single-Country Shop, Quick Start

Use case: A Dutch shop with 50-200 dealers in the Netherlands, no API keys yet.

Configuration: Map & Geocoding:

  • Map Provider: OpenStreetMap (free, no API key)
  • Contact Email for Nominatim: your technical contact
  • Restrict Address Search to Countries: Netherlands

Results:

  • Results per Page: 10
  • Distance Unit: Kilometres (km)

Result: The page works without any keys or costs. Searching "9711" finds Groningen, not a place abroad.

Scenario 2: Brand with Dealers in Several Countries on Google Maps

Use case: A brand selling through 1,000+ dealers in the Netherlands, Belgium and Germany, with store views per language.

Configuration: Map & Geocoding:

  • Map Provider: Google Maps (API key required)
  • Google Maps Browser API Key: restricted to your domains and the Maps JavaScript API + Geocoding API
  • Google Geocoding Server API Key: restricted to your server IP and the Geocoding API
  • Restrict Address Search to Countries: Netherlands, Belgium, Germany
  • Default Map Centre and Zoom: per store view, e.g. Germany at 51.1657 / 10.4515, zoom 6

Page & SEO, per store view:

  • URL Key: dealers (English), dealers or verkooppunten (Dutch), haendler (German)
  • Meta Title and Meta Description in the store view's language

Product Categories:

  • Labels per store view filled in for every category

Result: Each country gets the locator in its own language and address, with Google's map and search. Import the dealer list once from the command line, then keep it up to date with imports from the admin.

Scenario 3: Dealers Only in Some Store Views

Use case: Some dealers only sell to customers of one country, while others serve everyone.

Configuration:

  • Dealers for everyone: Store Views set to All Store Views (stores column empty or all in the import)
  • Country-specific dealers: only their store view (stores column e.g. be_nl, be_fr)

Result: Visitors only see dealers that are relevant for the store view they're on.

Use case: A shop in the EU that asks consent before loading any third-party service.

Configuration: Privacy:

  • Load Map Only After Cookie Consent: Yes

When you use a consent tool other than Magento's own cookie notice or Hyvä's banner, have your developer send the event dealer-locator:consent-granted when the visitor accepts (see Module-Specific Tips).

Result: No request goes to Google or OpenStreetMap before consent. Visitors can still search the list, or click Show map to load the map just for themselves.

Keeping Dealers Up to Date

  • Small changes: edit the dealer in the admin.
  • Many changes: export your list from your ERP or spreadsheet with the same codes, and import it. Only changed dealers are saved; unchanged rows are skipped.
  • Removing dealers: the import doesn't delete dealers that are missing from the file. Deactivate them with an active column set to 0, or delete them in the grid.
  • Corrected addresses: when a re-imported row has a new address and no coordinates, the coordinates are looked up again automatically.

Performance Optimization

  • All active dealers of a store view are part of the page itself, which keeps searching instant. That works well up to a few thousand dealers; the self-test warns above 3,000.
  • The page is cached by Magento's full page cache and refreshed automatically when you save a dealer or category.
  • The map and its scripts load only on the dealer locator page, not on the rest of your shop.

Security Considerations

  • The Google Maps Browser API Key is visible in the page source by design. Restrict it to your domains (HTTP referrers) and to the Maps JavaScript API and Geocoding API, so nobody can use it elsewhere.
  • The Google Geocoding Server API Key is stored encrypted and only used by your server. Restrict it to your server's IP address and the Geocoding API.
  • Set a daily quota or budget alert in Google Cloud, so an unexpected spike can't cause a large bill.

Common Mistakes

Mistake: One Google key for everything

Why it's wrong: A key restricted to your domain doesn't work from the server, so dealer coordinates aren't found. An unrestricted key can be copied from your page and used by others. Correct approach: Two keys: a browser key restricted by domain, a server key restricted by IP.

Mistake: Importing without codes, or with changing codes

Why it's wrong: Every import then creates new dealers, and you end up with duplicates. Correct approach: Use a fixed reference per dealer, such as the customer number in your ERP.

Mistake: Dealers without postcode or city

Why it's wrong: Without a postcode or city the address can't be placed on the map, so the dealer isn't shown on the storefront. Correct approach: Always fill in postcode and city, or enter the coordinates yourself.

Mistake: Expecting a large OpenStreetMap import to finish in the admin

Why it's wrong: OpenStreetMap allows one lookup per second; the admin stops looking up after 60 seconds. Correct approach: Use bin/magento dealerlocator:import for the first big import, or import without lookups and run bin/magento dealerlocator:geocode afterwards.

Module-Specific Tips

Linking to the page: add a link to /dealers (or your URL key) in your menu or footer, for example in a CMS block. Developers can use Magmodules\DealerLocator\Service\Locator\Url::getUrl() to get the page URL per store view.

Starting the map from your consent tool: when the visitor accepts, run:

window.dispatchEvent(new Event('dealer-locator:consent-granted'));

Adjusting the look:

  • Luma: the styles are in the module's _module.less and use Luma's variables; override the .mm-dealer-locator and .mm-dealer-card classes in your theme.
  • Hyvä: buttons and fields use your theme's own btn and form-input classes. The layout comes from a small stylesheet; override the same class names, or change the CSS variables --mm-dl-accent, --mm-dl-height and others on .mm-dealer-locator. The list markup is a regular template (Magmodules_DealerLocator::hyva/locator.phtml) that you can override in your theme.

Other map tiles: the OpenStreetMap tiles come from OpenStreetMap's own servers, which are meant for normal traffic. Shops with very high traffic can switch to a commercial tile service with a di.xml argument for Magmodules\DealerLocator\ViewModel\Locator (tileUrl and tileAttribution).

Need More Help?

Documentation:

Support:

For a complete overview of features and configuration options, see Dealer Locator.

Article Updated:
Download PDF
star star star star star
star star star star star
Gaaf - digital agency
We have tried the integration with SnelStart through several different providers, and this is the only solution that simply works. We needed support on two occasions, and it was provided quickly and professionally. We do recommend this company!
Google 12 May 2026
star star star star star
star star star star star
Andrew Velikiy
Great vendor with handy modules and quick support!
Google 13 Apr 2026
star star star star star
star star star star star
Alexandru-Manuel Carabus
Magmodules sets the bar for Magento module quality and support—we check their catalog first for client feature requests, and they’re our first choice for licenses.
Google 11 Nov 2025
star star star star star
star star star star star
Matt Austin
Possibly the fastest support response times of any Magento Extension vendor. Great extensions too!
Google 09 Sep 2025
star star star star star
star star star star star
Jan Privé
Dankzij de heldere uitleg en snelle reactie van Magmodules kon mijn vraag, en dus mijn Magento-probleem, binnen enkele uren worden beantwoord. Doeltreffend, zonder moeilijke termen, gewoon zo als het zou moeten zijn.... Bedankt!
Google 05 Sep 2025
star star star star star
star star star star star
Denis Metzler
To evaluate a provider, it is not enough to consider only the product offered, but also its after-sales service, such as support and troubleshooting. Magmodules has been extremely satisfactory at all levels on multiple occasions and sets the bar at the top when comparing the competition.
Google 02 Sep 2025
star star star star star
star star star star star
Bleijenberg winkelinrichting en materialen
Goed bereikbaar, reageren snel en denken oplossingsgericht. Een aanrader.
Google 30 Jul 2025
star star star star star
star star star star star
Patrick Verduijn
Magmodules biedt plugins aan die van hoge kwaliteit zijn tegen een goede prijs, waar dit bedrijf in uitblinkt is de bereidheid om de zeldzame feedback & problemen met de plugins te willen onderzoeken, mee te willen denken in het debuggen van problemen en goede oplossingen toe te passen. In mijn decennium ervaring met Magento & 3th parties is Magmodules absoluut een uniqum binnen de markt.
Google 25 Jul 2025
star star star star star
star star star star star
Erik de Groot
Magemodules heeft hele sterke Magento extensies en een proactieve support. Al jaren heel erg tevreden over jullie service en producten!
Google 18 Jul 2025
star star star star star
star star star star star
René Zeuner
We are using the Mollie Magento extension from Magmodules. It works excellently without flaws. Very fast, competent and friendly support. Thanks!
Google 30 Jun 2025