Dealer Locator for Magento 2





Dealer Locator for Magento 2
A Dealer Page With Map and Distance Search in Your Store
Dealer Locator adds a dealer page to your Magento 2 store. Visitors search by city, postcode, address or dealer name, or click "Use my location", and see the nearest dealers in a list and on a map, sorted by distance.
You manage dealers and product categories under "Content" > "Dealer Locator", one by one or in bulk with a CSV import. The extension looks up the map coordinates from each address, so nobody has to enter latitude and longitude by hand.
The map runs on OpenStreetMap without an API key or on Google Maps, and the page has its own templates for Hyvä and Luma.

What Dealer Locator Does
Search by Place, Postcode or Name
Visitors type a city, postcode, address or dealer name, or share their location, and get the nearest dealers first.
OpenStreetMap or Google Maps
Choose the "Map Provider" per website: OpenStreetMap works without an API key, Google Maps with two keys you can test in the admin.
Coordinates From the Address
Leave "Latitude" and "Longitude" empty and the extension looks them up when you save or import a dealer.
CSV Import With a Report per Row
Create and update dealers by code, validate a file without saving anything and see per row what went wrong.
Dealers and Texts per Store View
Assign dealers to store views and set the URL key, page title and category labels per store view.
Map Only After Cookie Consent
Optionally hold the map until the visitor consents, while the dealer list keeps working.
Find the Nearest Dealer in a List and on a Map
The search field takes a city, postcode or address. The map provider looks up the place and the list is sorted by distance, in the unit you choose under "Distance Unit": "Kilometres (km)" or "Miles (mi)". In kilometres, a dealer closer than 1 km is shown in metres, for example "850 m", and the decimal separator follows the language of the store view.
A dealer name works too. When a search term matches a dealer name but no street, city or postcode, the page filters on that name instead of sending it to the geocoder, which would return an unrelated place. Matching ignores capitals and accents, so "zurich" finds a dealer in Zürich.
- Location: "Use my location" sorts the list from the visitor's current position.
- Filter: the "All product categories" dropdown appears as soon as there is more than one product category.
- Per dealer: "Plan route" opens the route in Google Maps and "Show on map" jumps to the marker.
- List and map: a dealer picked on the map is selected in the list, also when it sits beyond "Show more".
- Length: "Results per Page" sets how many dealers are listed before "Show more", from 1 to 100, with 10 as the default.
On small screens the page switches to two tabs, "List" and "Map".


OpenStreetMap Without an API Key, or Google Maps
"Map Provider" has two options: "OpenStreetMap (free, no API key)", which is the default, and "Google Maps (API key required)". The provider you choose is used for the map, for the visitor's address search and for looking up dealer coordinates.
With OpenStreetMap you can start right away. Geocoding runs through Nominatim, which allows one request per second, and you can fill in "Contact Email for Nominatim" as their usage policy asks.
Google Maps needs a Google Cloud project with the Maps JavaScript API and the Geocoding API, and two keys:
- "Google Maps Browser API Key": used in the visitor's browser and visible in the page source, so restrict it to your shop domain.
- "Google Geocoding Server API Key": stored encrypted and used by Magento when you save or import dealers. Restrict it to the IP address of your server.
Under each key is a "Test API key" button. It checks the value in the field, also before you save. For the browser key it tests both APIs in your browser and whether the key is restricted to websites. For the server key it sends one Geocoding request from the server. A wrong or unrestricted key shows up in the admin instead of on the live dealer page.
"Default Map Centre Latitude", "Default Map Centre Longitude" and "Default Zoom Level" set what the map shows before a search. "Restrict Address Search to Countries" improves results for ambiguous input such as postcodes. Leave it empty and the page searches in the countries your dealers are in.
Dealers With Coordinates Looked Up for You
A dealer has four sections in the admin: "General", "Address and Location", "Contact" and "Product Categories and Store Views". Fill in the address and leave "Latitude" and "Longitude" empty: the extension looks them up when you save. Coordinates you enter yourself are kept, which helps for a location the geocoder places wrongly.
The "Code" is the unique reference of a dealer, for example your customer number. The CSV import uses it to update existing dealers.
Under "Product Categories" you select what a dealer sells, and visitors can filter on it. You manage the categories under "Content" > "Dealer Locator" > "Product Categories", each with a "Default Label", a "Sort Order" and "Labels per Store View", so the filter reads correctly in every language. "Store Views" decides in which store views a dealer is shown.
For dealers that are not on the map yet, bin/magento dealerlocator:geocode looks up the missing coordinates from the command line. Add --limit to process a set number of dealers per run.


Import and Update Dealers From CSV
"Import CSV" in the dealer grid creates new dealers and updates existing ones, matched on their code. "Download Sample CSV" gives you a file with the right columns to start from.
- Columns: 13 columns, of which
code,nameandcountryare required. Header names such aszip,lat,lngandtelephoneare recognised as well. - File format: comma, semicolon or tab separated, in UTF-8 (with or without BOM) or Windows-1252, so a CSV saved from Excel on Windows imports as is. The admin accepts files up to 10 MB.
- Updates: columns that are not in the file stay untouched on existing dealers. An empty cell clears the value, and empty coordinates keep the stored ones.
- Values:
activeaccepts 1 and 0, yes and no, and also "ja" and "nee".storestakes store view codes orall. Coordinates may use a decimal comma. - Errors: every row is saved on its own, so one failing row does not stop the rest.
The form has three options: "Look up missing coordinates from the address", "Create product categories that don't exist yet" and "Validate only, don't save anything". The last one checks the whole file and reports what would be created and updated, without changing a dealer.
After the import you see "Created", "Updated", "Unchanged" and "Failed", plus a table with the row, the code and the message for every row that needs attention. With OpenStreetMap, the admin import stops looking up coordinates after 60 seconds and saves the remaining dealers without them. You locate those afterwards with the "Find Location" action in the grid.
Your Own URL, Title and Meta Data per Store View
The dealer page is available at your store URL followed by the "URL Key", which is dealers by default. A nested path such as service/dealers works as well.
"URL Key", "Page Title", "Meta Title" and "Meta Description" can all be set per store view. Together with dealers per store view and category labels per store view, each language of your store gets its own dealer page, with its own address, texts and dealers.
The page is off after installation. Set "Enabled" to "Yes", for all store views at once or per store view, when your dealers are in place.


Load the Map Only After Cookie Consent
When the map loads, the map provider receives the visitor's IP address. With "Load Map Only After Cookie Consent" set to "Yes", the map waits until the visitor has given consent. The setting is off by default.
- Magento and Hyvä: the map follows Magento's Cookie Restriction Mode and Hyvä's cookie consent.
- Other consent tools: dispatch the
dealer-locator:consent-grantedevent onwindowto start the map. - The visitor decides: the page shows which provider the map comes from and a "Show map" button.
The search and the dealer list stay available without consent, so a visitor can always find a dealer.

All Dealers in One Grid, With Bulk Actions
The grid under "Content" > "Dealer Locator" > "Dealers" shows the address, product categories, store views and status of every dealer. The "On Map" column tells you which dealers have coordinates.
Filter on "Store View", "Product Category" or "On Map" and apply one of the mass actions: "Activate", "Deactivate", "Find Location" or "Delete". To place the remaining dealers on the map after a large import, filter "On Map" on "No", select the dealers and choose "Find Location".
Dealer Locator for Magento 2: Technical Details for Developers and Store Owners
The Advantages for Developers
- Requirements: Magento 2.4.4 or higher and PHP 8.1 or higher.
- Hyvä and Luma: the page has its own Hyvä layout and template next to the Luma version. The search and distance logic sits in
view/frontend/web/js/core/locator.js, without DOM or map code, and is shared by both front ends. - Import from the command line:
bin/magento dealerlocator:import <file>with--dry-run,--no-geocodeand--no-create-categories. Add-vto see the progress per row. The command returns a failure exit code when the report contains errors, which makes it usable in a scheduled script. - Geocoding from the command line:
bin/magento dealerlocator:geocode, with--limitfor a maximum number of dealers. - Consent hook: any consent tool can start the map with the
dealer-locator:consent-grantedevent onwindow. - Permissions: importing has its own ACL resource,
Magmodules_DealerLocator::import, separate from managing dealers, product categories and the configuration. - Logging: "Debug Mode" writes API requests and responses to a debug.log file. Errors are always written to error.log.
- Self-test: seven checks cover the PHP version, the Magento version, the extension status, the map configuration, geocoding, the Google browser key and the number of dealers.
Good to Know for Store Owners
- Version 1.0.0 is the first release of Dealer Locator.
- OpenStreetMap is free and needs no account. Its geocoder allows one lookup per second, so looking up coordinates for a large import takes time.
- "Map Provider" and the Google keys are set per website, not per store view. The map centre, zoom level, results and page texts can differ per store view.
- "Plan route" always opens Google Maps, also when the map itself runs on OpenStreetMap.
- The self-test gives a warning when you have more than 3,000 dealers.
Put Your Dealers on the Map
Dealer Locator 1.0.0 runs on Magento 2.4.4 and higher, with templates for Hyvä and Luma. Install the extension, choose a map provider and import your dealers from CSV.
Knowledgebase
All familiar Help articles
A list of the most frequently asked questions from the Dealer Locator extension for Magento 2. We've tried our best to help you with the installation, configuration and troubleshooting. If you do not find the answer you were looking for, you can always send us a message through this form.
Installation articles
Configuration
Changelog 1.0.0 is released on 18 November 2026
Our plugins are regularly updated to ensure compatibility with the latest Magento release.
-
Features:
- A dealer locator page where visitors find the nearest dealer by place, postcode, address or their own location, on a map and in a list sorted by distance.
- Google Maps or OpenStreetMap: OpenStreetMap works without an API key, Google Maps with a browser key and a server key.
- Dealers close together are grouped on the map, and choosing a dealer in the list highlights it on the map and the other way round.
- Every dealer shows its address, distance, product categories, phone number, website and a link that plans the route in Google Maps.
- Product categories with a name per store view, offered as a filter on the page.
- Dealers appear only in the store views they are assigned to, and only while active.
- Coordinates are looked up from the address when a dealer is saved, coordinates entered by hand are kept, and "Find Location" places the selected dealers that are not on the map yet.
- Hundreds of dealers are added or updated at once from a spreadsheet, in the admin or on the command line, with a check-only run and a report per row.
- The page address, title and meta description are set per store view, with a canonical link for search engines.
- The map can wait for cookie consent, so the map provider receives nothing before the visitor agrees, while the list and the search keep working.
- "Test API key" buttons check both Google keys from the configuration, including whether the browser key is restricted to your website.
- Works with Luma and Hyvä, on desktop, tablet and mobile, in English and Dutch, with documentation in both languages. Tests:
- 163 unit tests with the module-standards architecture checks on Magento 2.4.7 and 2.4.9, 39 tests of the storefront and admin scripts, and PHPStan level 8 on both versions. Compatibility:
- Magento 2.4.4 and up
- PHP 8.1 and up
100% Unencrypted Code quality guaranteed.

Adobe Commerce Marketplace Approved
This extension is listed on the official Adobe Commerce Marketplace and has passed their review process for code quality, performance and security.
Adobe Marketplace approval means the extension follows Magento coding standards and integrates properly with the platform. Updates go through the same review process.

Hyvä Compatible Plugin
This extension includes full support for Hyva Themes. All frontend components, widgets and templates work natively with Hyva's Alpine.js and Tailwind CSS stack.
The extension works out of the box on Hyva and is tested with every new Hyva release to ensure continued compatibility.

GraphQL Made Ready
This extension exposes its data and configuration through Magento's GraphQL API. You can query and mutate data directly from headless frontends or custom applications.
The GraphQL schema follows Magento's conventions and covers all key functionality of the extension. This makes it ready for PWA Studio, Vue Storefront or any other headless setup.

Magento Cloud Support
This extension is fully compatible with Adobe Commerce Cloud (Magento Cloud). It works with the read-only filesystem, the build and deploy pipeline and cloud-specific caching layers.
No additional configuration or workarounds are needed for cloud environments. The extension handles static content deployment and config management the same way as on-premise installations.

Private Composer Repo
After purchase you get access to a private Composer repository with personal credentials. Install and update the extension with a single composer command, just like any other dependency.
Your Composer credentials are available in your account dashboard. Updates are published to the repository as soon as a new version is released, so you always have access to the latest version.