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),dealersorverkooppunten(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 (
storescolumn empty orallin the import) - Country-specific dealers: only their store view (
storescolumn e.g.be_nl, be_fr)
Result: Visitors only see dealers that are relevant for the store view they're on.
Scenario 4: Strict Cookie Consent
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
activecolumn set to0, 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.lessand use Luma's variables; override the.mm-dealer-locatorand.mm-dealer-cardclasses in your theme. - Hyvä: buttons and fields use your theme's own
btnandform-inputclasses. The layout comes from a small stylesheet; override the same class names, or change the CSS variables--mm-dl-accent,--mm-dl-heightand 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:
- All Help Articles - Complete documentation overview
Support:
- Contact Support - Get help from our team
For a complete overview of features and configuration options, see Dealer Locator.