Magento 2 Dealer Locator Configuration Guide
Looking for Dealer Locator? View the full Dealer Locator page to explore features, configuration options, and pricing.
Here's where you'll find every setting of the Dealer Locator, explained in plain language. We follow the order of the admin panel: switching the module on, choosing between OpenStreetMap and Google Maps, the map's starting point, how results are listed, the page address and search engine texts, and the privacy setting for cookie consent. For each setting you'll read what it does and when you'd change it, with recommendations where they make a real difference. Most stores only touch a handful of these; the defaults are chosen so the page works without further setup. Where a setting can differ per store view, such as the page address or title, you set it in the store view scope as usual.
Complete reference for all Dealer Locator configuration options.
Location: Stores → Configuration → Magmodules → Dealer Locator
Branding
Shows the installed version and has buttons for the self-test and the manual. Use Run Self-test after changing the map settings: it checks that the chosen map provider has the keys it needs, that looking up an address works, and how many dealers the page has to show.
General
Enabled
Switches the dealer locator page on the storefront on or off. While it's off, the page address gives a "page not found", but you can already manage and import dealers in the admin.
Map & Geocoding
"Geocoding" means turning an address into map coordinates. The module does that in two places: in the admin, when you save or import a dealer, and in the visitor's browser, when they search for a place.
Map Provider
Which service draws the map and looks up addresses.
- OpenStreetMap (free, no API key): works straight after installation. Address lookups go through OpenStreetMap's Nominatim service, which allows one lookup per second. That's plenty for visitors searching, but it makes large imports slower (see the import guide).
- Google Maps (API key required): the familiar Google map and Google's address search. Needs a Google Cloud project with billing enabled and two keys (below). Google gives a monthly free usage allowance; check Google's current pricing for your expected traffic.
When to use:
- OpenStreetMap: you want to start right away, keep costs at zero, or prefer not to use Google.
- Google Maps: you want Google's map style and search quality, or your customers expect it.
Google Maps Browser API Key
Only shown for Google Maps. Used by the map and the place search in the visitor's browser. Because the browser needs it, this key is visible in your page source; that's normal for Google Maps, as long as you restrict it.
Recommended:
- In Google Cloud, restrict it to your shop's domain (HTTP referrers, e.g.
https://example.com/*) - Allow only the Maps JavaScript API and the Geocoding API
- Never enter the server key here: anyone can copy this key from your page source
Test API key: checks the key in the field, also before you save. Your browser loads the Maps JavaScript API and runs one address search with the key, and the server checks that the key is restricted to websites. Each part shows OK or Google's reason, such as a domain that isn't allowed or an API that isn't enabled. If your admin runs on a different domain than your shop, a key restricted to the shop domain fails the browser part here; the result then says so.
Google Geocoding Server API Key
Only shown for Google Maps. Used by Magento itself to look up dealer coordinates when you save or import dealers. It's stored encrypted and never sent to the browser.
Recommended:
- Restrict it to your server's IP address and to the Geocoding API only
- Use a separate key from the browser key: a key restricted to your domain (HTTP referrers) doesn't work from the server
Test API key: sends one request to the Geocoding API from your server with the key in the field (or the saved key, while the field shows asterisks), and shows Google's answer.
Contact Email for Nominatim
Only shown for OpenStreetMap. Optional email address sent along with address lookups, so the OpenStreetMap team can contact you if your shop sends unusually many requests, as their usage policy asks. It isn't shown to visitors.
Default Map Centre Latitude / Default Map Centre Longitude
Where the map is centred before a visitor searches, as soon as the page opens. The default is the middle of the Netherlands. Once the dealers are loaded, the map zooms to show the dealers in the list, so this mainly matters when there are no dealers yet or the map can't show any.
Example: Belgium: 50.5039 and 4.4699. Germany: 51.1657 and 10.4515.
Default Zoom Level
How far the map is zoomed in at that starting point, from 1 (whole world) to 20 (street level). 7 shows a country the size of the Netherlands; use 5 or 6 for Germany or France.
Restrict Address Search to Countries
Limits the visitor's place search to these countries. This matters for short or ambiguous input: "9711" is a postcode in Groningen, but also exists in other countries.
When to use:
- You sell in a few countries and want searches to stay within them.
When you leave it empty, the page limits the search to the countries your dealers are in (if that's at most 5 countries), which is usually what you want. Google Maps accepts at most 5 countries; the setting won't save with more when Google is selected.
Results
Results per Page
How many dealers the list shows before the Show more button. Each click shows this many more.
Distance Unit
Kilometres or miles for the distances in the list. You can set it per store view, for example miles for a UK store view.
Page & SEO
URL Key
The address of the dealer locator page after your store URL. With dealers the page is at https://example.com/dealers. You can use a nested address such as service/dealers, and a different key per store view, for example dealers in English and winkels in Dutch. Only lowercase letters, digits, "-" and "_" are allowed, with "/" between parts.
Tip: The page is also reachable at /dealerlocator; search engines are pointed to your URL key with a canonical link, so there's no duplicate content.
Page Title
The heading on the page. When empty, the page shows "Find a Dealer", translated into the language of the store view, so you only need this if you want different wording.
Meta Title
The title in the browser tab and in search results. When empty, the page title is used.
Meta Description
The short text search engines show under your page title. Mention what visitors find there, for example "Find a [brand] dealer near you, with address, phone number and route." Keep it under about 160 characters.
Privacy
Load Map Only After Cookie Consent
When the map loads, the map provider (Google or OpenStreetMap) receives the visitor's IP address, and Google may set cookies. With this setting on, the map waits until the visitor agrees. Until then a short notice with a Show map button is shown in its place, and visitors can still search: the list then matches dealers on name, city and postcode.
The map starts as soon as any of these happens:
- The visitor accepts cookies in Magento's own cookie notice (Cookie Restriction Mode)
- The visitor accepts cookies in Hyvä's cookie banner
- The visitor clicks Show map
- Another consent tool sends the event
dealer-locator:consent-grantedonwindow(your developer can add this to your consent tool's "accepted" callback)
Recommended:
- On, for shops in the EU that ask consent for third-party services
- Off, if your consent tool already blocks the page or you don't ask consent for maps
Debug & Logging
Debug Mode
Writes extra details to var/log/dealer-locator-debug.log, such as addresses the map provider couldn't find. Errors, like a rejected API key, are always written to var/log/dealer-locator-error.log. The buttons in this section show the latest lines of both logs in the admin.
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.