Store Locator for Magento 2 user guide

No coding is needed. Every setting lives in the Magento admin, and the guide walks you through them.

Overview

Store Locator is a Magento 2 extension from Magexweb that helps customers find your physical stores, dealers or partners. Visitors search by address or their current location, filter by category, service or opening hours, and see the results on a map (Google Maps or OpenStreetMap) and in a list. Every store gets its own SEO-friendly page with address, opening hours, directions, photos and a contact form.

Stores are managed in the Magento admin like any other content: add them one by one, import them from a CSV file, or let visitors suggest new ones for you to approve.

Important: Store Locator pages are cached by Magento's full page cache, and the search uses its own Store Locator cache type and search index. After installing, enable the Store Locator cache type in System > Cache Management, and make sure the Magento cron is running (geocoding, background imports and the search index use it).

Key features

  • Store search by address, place, ZIP/postal code or the visitor's location, with a distance radius and store name search
  • Filters for categories, services, country, region, city, "Open now" and your own custom attributes
  • Google Maps with marker clustering, custom marker images per store or category, Map ID / Advanced Markers and custom map styles
  • OpenStreetMap as an alternative without an API key: Leaflet maps with clustering and info windows, address suggestions, automatic coordinates and Google, OpenStreetMap or Apple Maps directions
  • Six layouts: Map + List, List + Map, Full Map, Grid, List and Map + Grid
  • Store pages with image gallery, opening hours with live open/closed status, holiday hours, directions, contact links, custom attributes and nearby stores
  • Weekly opening hours with several periods per day, after-midnight closing and per-date holiday hours, each store in its own timezone
  • Categories, services and custom attributes (text, number, yes/no, date, URL, dropdown, multiple select)
  • Store view translations, store view assignment and customer group visibility per store
  • "Contact this store" and "Suggest a store" forms with email notifications, spam protection and optional Google reCAPTCHA
  • CSV import and export with validation, background and scheduled imports (file or HTTPS URL)
  • Automatic coordinates (geocoding) for stores without latitude and longitude
  • SEO: URL rewrites with 301 redirects, meta templates, canonical URLs, JSON-LD structured data and XML sitemap
  • Usage reports (searches, page views, directions, calls, emails) and optional Google Tag Manager events
  • CMS widget, REST API, CLI commands, sample data and granular admin permissions
  • Full page cache compatible

How it works

Once installed, the store locator is available at www.yourstore.com/store-locator (the path is configurable). Customers can:

  • Search for stores near an address or their location. Results are sorted by distance and shown on the map and in the list, with each store's opening status, services and quick actions.
Store locator search results with filters, map and store list
  • Open a store page with photos, address, contact buttons, opening hours, a map with directions and the nearest other stores.
Store page with image gallery, address, opening hours and map
  • Use the store locator on a phone: the search panel, filters and results adapt to small screens.
Store locator on a mobile phone

Requirements and compatibility

ItemDetail
PlatformMagento Open Source or Adobe Commerce 2.4.8 and 2.4.9
PHP8.1 to 8.5 (as supported by your Magento version)
DatabaseMySQL 8 or MariaDB 10.6+
CronMagento cron must be running (geocoding, background and scheduled imports, message clean-up)
MapsA Google Maps Platform account, or OpenStreetMap without an account (see Map setup)
Module codeMagexweb_StoreLocator
Composer packagemagexweb/storelocator
LicenseOpen Software License 3.0 (OSL-3.0)

Installation

Composer installation (recommended)

  1. Place the extension in your project (via the Adobe Commerce Marketplace, a private Composer repository, or by copying it under app/code).
  2. From the Magento root, run the following commands:
CommandPurpose
composer require magexweb/storelocatorOnly if distributed via a Composer repository
php bin/magento module:enable Magexweb_StoreLocatorRegisters and enables the module
php bin/magento setup:upgradeCreates the store locator tables and URL rewrites
php bin/magento setup:di:compileRecommended for production mode
php bin/magento setup:static-content:deploy -fRequired in production mode
php bin/magento cache:enable magexweb_storelocatorEnables the Store Locator cache type (new cache types are disabled on existing installations)
php bin/magento cache:flushClears the Magento cache

Manual (ZIP) installation

  • Extract the ZIP package to app/code/Magexweb/StoreLocator in your Magento installation, so that app/code/Magexweb/StoreLocator/registration.php exists.
  • Run the same bin/magento commands listed above (module:enable, setup:upgrade, di:compile, static-content:deploy, cache:enable, cache:flush).
  • Check the module is active: php bin/magento module:status Magexweb_StoreLocator

Sample data

Install the sample data to see the store locator in action straight away: 21 stores of a fictional brand ("Maple & Main") in Toronto, Montreal, Vancouver, New York, Chicago and San Francisco plus an online store, with opening hours (including split, late-night and 24/7 hours), upcoming holidays, 4 categories, 4 services, 2 custom attributes ("Free Parking", "Store Size") and placeholder images.

CommandPurpose
php bin/magento magexweb:storelocator:sample-data:installInstalls the sample stores, categories, services, attributes and images
php bin/magento magexweb:storelocator:sample-data:removeRemoves exactly what was installed (your own stores are never touched)

Note: sample codes start with maple-main-. If a code is already used in your store, the sample item gets a number added instead of replacing your content. Phone numbers use 555 numbers and email addresses use example.com.

After installing

  • Choose the map provider and, for Google Maps, enter the API keys (see Map setup).
  • Add stores, or import them, under Store Locator > Stores (see Managing stores and Import and export).
  • Open the store locator at www.yourstore.com/store-locator (the path is configurable).
  • On production stores, set System > Index Management > Store Locator Search to "Update by Schedule" (changes are applied by cron within a minute), or keep "Update on Save".

Map setup

Maps, address suggestions and the automatic store coordinates use one of two map providers. Choose it in Store Locator > Configuration > Map > Map Provider; the settings of that group change with the provider (see Admin configuration).

Google MapsOpenStreetMap
Account / API keyGoogle Cloud project with billing and two API keysNot needed
MapGoogle Maps, Advanced Markers with a Map ID, custom map styleLeaflet with OpenStreetMap tiles or the tile server of your choice
Address suggestionsGoogle Places API (New)Photon (photon.komoot.io or your own service)
Store coordinatesGoogle Geocoding APINominatim (nominatim.openstreetmap.org or your own service)
Directions linksGoogle MapsGoogle Maps, OpenStreetMap or Apple Maps

Google Maps

Create two API keys in the Google Cloud console (billing must be enabled on the project) and enter them in Store Locator > Configuration > Map.

KeyAPIs to enableRestrictionWhere to enter it
Browser keyMaps JavaScript API, Places API (New), Geocoding APIWebsites (HTTP referrers): your storefront and admin domainsMap > Browser API Key
Server keyGeocoding APIIP addresses of your serverMap > Server Geocoding API Key (stored encrypted)

Important: the browser key is visible in the page source. Always restrict it to your own domains (for example https://www.yourstore.com/* and your admin domain). If a domain is missing from the list, Google shows "This page can't load Google Maps correctly" and the map stays grey.

Map ID (optional). Create a Map ID in Google Cloud > Map Management (map type JavaScript) and enter it in Map > Map ID to use Google's Advanced Markers and cloud map styling. A Map Style (JSON) takes precedence over the Map ID, because Google cannot combine both; with a style, the map uses classic markers.

OpenStreetMap

Choose OpenStreetMap as the Map Provider. No account or API key is needed: the defaults work straight away. The maps use Leaflet (included in the extension) with the same features as with Google: marker clustering, info windows, the search radius, "Use my location", address suggestions and the map picker in the store form.

Store locator search results on an OpenStreetMap map
Store info window on an OpenStreetMap map
SettingDefaultNotes
Tile Server URLhttps://tile.openstreetmap.org/{z}/{x}/{y}.pngThe map images. Use a tile provider (e.g. MapTiler, Stadia Maps, Thunderforest, with its key in the URL) or your own tile server for busy shops.
Place Search URLhttps://photon.komoot.io/api/Photon compatible service for the address suggestions and the visitors' address search. Empty: no address search.
Geocoding URLhttps://nominatim.openstreetmap.org/searchNominatim compatible service that finds store coordinates (cron, Find Coordinates, command line); at most one request per second.
Geocoding Contact Email(empty)Your email, sent with geocoding requests as the Nominatim usage policy asks.
Directions ServiceGoogle MapsRoute planner opened by the Directions links: Google Maps, OpenStreetMap or Apple Maps.

Important: the public OpenStreetMap tile server, Photon and Nominatim are free services for light use with fair use policies. For a busy shop, enter the URLs of a commercial provider or of your own servers. When Magento's Content Security Policy is in restrict mode, add a tile, search or geocoding host other than the defaults to the CSP whitelist.

Map ID, Map Style (JSON) and Minimum Cluster Size are Google Maps settings; with OpenStreetMap the tile provider decides the map style and clusters start at 2 stores.

Store coordinates

Every store needs a latitude and longitude to appear on the map and in distance searches:

  • In the store form, use the map under Address and Location: type a place or address in the search box and choose a suggestion, click Find from Address, click the map or drag the marker.
  • Stores saved or imported with an address but without coordinates are looked up by cron (every 5 minutes, 50 stores per run) with the map provider's geocoding service (Google: the server key; OpenStreetMap: the Geocoding URL).
  • The Coordinates column of the store grid shows the state: Pending, Found, Not Found or Manual. The grid action Find Coordinates queues the selected stores again.
  • Run the lookup right away: php bin/magento magexweb:storelocator:geocode [--limit=500] [--retry-failed]
Location on Map field in the store form with Google Maps

The same field with OpenStreetMap:

Location on Map field in the store form with OpenStreetMap

Admin configuration

All settings live under Stores > Settings > Configuration > Magexweb Extensions > Store Locator (also available from Store Locator > Configuration). Use the Scope switcher at the top of the page to use different settings for a website or store view.

General

Store Locator configuration: General
FieldDescription
Enable Store LocatorMaster switch. Set to No to hide the store locator, store pages and links for this store view.
Default: Yes
Page TitleHeading of the store locator page, also used in breadcrumbs and as the default link label.
Default: Store Locator
Store Locator URL PathExample: store-locator gives /store-locator. Use lowercase letters, numbers and hyphens.
Default: store-locator
Store Page URL StructureURL of store pages: the locator path plus the store URL key, or with an extra segment in between.
Default: Locator Path / URL Key (store-locator/example-store)
Store Page URL SegmentThe extra segment when the URL structure includes one (e.g. store gives /store-locator/store/example-store).
Default: store
URL SuffixExample: .html. Leave empty for no suffix.
Default: (empty)
Default LayoutLayout of the store locator page: Map + List, List + Map, Full Map, Grid, List or Map + Grid.
Default: Map + List
Show Link In FooterAdds a link to the store locator in the footer links.
Default: Yes
Show Link In Top MenuAdds the store locator to the top menu (category navigation), also in the mobile menu.
Default: No
Top Menu Link LabelLeave empty to use the Page Title.
Default: (empty)
Top Menu Link PositionShows the top menu link first or last.
Default: Last
Show Link In Header LinksAdds the store locator to the header links (next to "Sign In" / "Create an Account").
Default: No
Header Link LabelLeave empty to use the Page Title.
Default: (empty)
Header Link PositionShows the header link first or last.
Default: Last

Map

With Google Maps as the Map Provider:

Store Locator configuration: Map settings with Google Maps

With OpenStreetMap as the Map Provider:

Store Locator configuration: Map settings with OpenStreetMap
FieldDescription
Map ProviderMap service used for maps, place search and geocoding: Google Maps (API key needed) or OpenStreetMap (no API key). The settings below change with the provider.
Default: Google Maps
Tile Server URLOpenStreetMap only. Map images. The default OpenStreetMap server is free for light use only (see its tile usage policy). For busy shops use a tile provider (e.g. MapTiler, Stadia Maps, Thunderforest, with its key in the URL) or your own tile server. Placeholders: {z}, {x}, {y}, optionally {s} and {r}.
Default: https://tile.openstreetmap.org/{z}/{x}/{y}.png
Tile Server Maximum ZoomOpenStreetMap only. Highest zoom level of the tile server (OpenStreetMap: 19). Closer zoom levels enlarge these tiles.
Default: 19
Map AttributionOpenStreetMap only. Shown in the corner of the map. Keep the copyright notice your tile provider requires.
Default: © OpenStreetMap contributors
Place Search URLOpenStreetMap only. Photon compatible place search for the address suggestions and the visitors' address search (default: photon.komoot.io, free for fair use). Leave empty to switch off the address search.
Default: https://photon.komoot.io/api/
Geocoding URLOpenStreetMap only. Nominatim compatible search used by the server to find the coordinates of stores saved or imported without them (cron, the store grid's "Find Coordinates" action and bin/magento magexweb:storelocator:geocode). At most one request per second is sent. Only public https:// addresses are accepted.
Default: https://nominatim.openstreetmap.org/search
Geocoding Contact EmailOpenStreetMap only. Sent with geocoding requests, as the Nominatim usage policy asks, so the service can contact you about problems.
Default: (empty)
Directions ServiceOpenStreetMap only. Route planner opened by the "Directions" links.
Default: Google Maps
Browser API KeyGoogle Maps only. Shows the maps on the store locator, store pages and widgets, the place search, the address search of visitors and the map in the admin store form. Visible to visitors, so in Google Cloud restrict it to your storefront and admin websites (HTTP referrers) and to the Maps JavaScript API, Places API (New) and Geocoding API.
Default: (empty)
Server Geocoding API KeyGoogle Maps only. Used only by the server to find the coordinates of stores saved or imported without them. Stored encrypted and never sent to the browser. Use a separate key restricted to the Geocoding API and, where possible, to your server's IP addresses.
Default: (empty)
Map IDGoogle Maps only. Optional. With a Map ID the maps use Google's Advanced Markers (the current marker type; classic markers are deprecated by Google) and the map style you design for the Map ID in Google Cloud. Create it with the map type "JavaScript". Without a Map ID the maps use classic markers. Marker images work either way. A Map Style (JSON) takes precedence over the Map ID.
Default: (empty)
Default Latitude / Default LongitudeCenter of the map before a search, in decimal degrees.
Default: 20.000000 / 0.000000
Default ZoomZoom level of the map before a search (1 = world, 20 = buildings).
Default: 2
Minimum Zoom / Maximum ZoomVisitors cannot zoom out or in further than these levels.
Default: 2 / 20
Map Style (JSON)Google Maps only. Optional JSON style array (e.g. from mapstyle.withgoogle.com). It takes precedence over the Map ID: Google cannot combine both, so with a style the map uses classic markers.
Default: (empty)
Default Marker ImageUsed when neither the store nor its category has a marker. Leave empty for the provider's default marker.
Default: (empty)
Enable Marker ClusteringGroups nearby markers into a numbered cluster at low zoom levels.
Default: Yes
Cluster Radius (pixels)Markers within this distance on screen are grouped into one cluster.
Default: 60
Minimum Cluster SizeSmallest number of markers shown as a cluster.
Default: 2
Custom Cluster IconOptional image for clusters. Leave empty for the default cluster icon.
Default: (empty)
Show Directions LinksShows a Directions link (route planner) on store cards, info windows and store pages.
Default: Yes
Enable "Use My Location"Browsers allow location access only on HTTPS pages. The visitor's location is not stored.
Default: Yes

Search

Store Locator configuration: Search
FieldDescription
Distance UnitUnit of radius options and distances shown to visitors.
Default: Kilometers
Radius OptionsComma-separated, in the distance unit. Example: 5,10,25,50,100
Default: 5,10,25,50,100
Default RadiusRadius used when the visitor does not choose one.
Default: 25
Allow Custom RadiusYes: visitors may search any radius up to the maximum. No: only the Radius Options are accepted.
Default: No
Maximum RadiusLargest radius a search can use, in the distance unit.
Default: 500
Results Per PageNumber of stores in each page of results.
Default: 20
PagingLoad further results with page numbers or with a "Show more stores" button.
Default: Load More Button
Visible FiltersCustom attributes marked "Use in Filters" are added automatically.
Default: Category, Service, Open Now
Maximum Markers Per Map ViewLimits how many markers are sent to the browser at once. Zooming in loads the rest.
Default: 2000
Search Requests Per Minute Per VisitorProtects the search from automated abuse. 0 = no limit.
Default: 60

Opening Hours

Store Locator configuration: Opening Hours
FieldDescription
Time FormatHow opening times are shown on the storefront.
Default: 24-hour (09:00)
"Opening Soon" / "Closing Soon" (minutes)0 shows only "Open" and "Closed".
Default: 30
Show Holiday Hours For The Next (days)Upcoming holiday hours within this number of days are listed on store pages.
Default: 14

Store Page

Store Locator configuration: Store Page
FieldDescription
Show MapShows a map with the store's location on the store page.
Default: Yes
Show Nearby StoresLists the closest other stores at the bottom of the store page.
Default: Yes
Number Of Nearby StoresMaximum number of nearby stores shown.
Default: 3
Nearby Stores RadiusOnly stores within this distance are listed as nearby.
Default: 50

SEO

Store Locator configuration: SEO
FieldDescription
Store Locator Meta TitleLeave empty to use the page title.
Default: (empty)
Store Locator Meta DescriptionMeta description of the store locator page.
Default: (empty)
Store Locator Meta KeywordsMeta keywords of the store locator page (optional; most search engines ignore them).
Default: (empty)
Store Page Meta Title TemplateUsed when a store has no meta title. Variables: {name}, {city}, {region}, {country}, {postcode}.
Default: {name} - {city}
Store Page Meta Description TemplateUsed when a store has no meta description. Same variables as the title template.
Default: (empty)
Add Structured Data (JSON-LD)Adds schema.org business data (address, coordinates, opening hours) to store pages.
Default: Yes
Default Business TypeCan be changed per store.
Default: Local Business
NOINDEX Filtered Search URLsAdds "noindex,follow" to store locator URLs that contain search parameters, so search engines index only the main page and store pages.
Default: Yes
Add Store Pages To XML SitemapAdds store pages to the XML sitemap generated in Marketing > Site Map.
Default: Yes
Sitemap PriorityBetween 0.0 and 1.0.
Default: 0.5
Sitemap Change FrequencyHow often search engines should expect store pages to change.
Default: Weekly

Statistics

Store Locator configuration: Statistics
FieldDescription
Count UsageDaily counts of searches, store page views and clicks (directions, call, email, website), shown under Store Locator > Reports. No personal data or IP addresses are stored.
Default: Yes
Send Events to Google Tag ManagerPushes events (e.g. storelocator_directions) to window.dataLayer when it exists. Requires Google Tag Manager on the site.
Default: No

Contact Store Form

Store Locator configuration: Contact Store Form
FieldDescription
EnableShows a "Contact this store" form on store pages. Messages are listed under Store Locator > Store Messages.
Default: No
Send to the Store's EmailSends each message to the email address of the store, when it has one.
Default: Yes
Also Send ToEmail addresses, separated by commas.
Default: (empty)
Email SenderStore email identity used as the sender of message emails.
Default: General Contact
Notification Email TemplateEmail template; customize it in Marketing > Email Templates.
Default: Default template
Send Confirmation to VisitorSends the visitor a copy of their message.
Default: Yes
Confirmation Email TemplateEmail template; customize it in Marketing > Email Templates.
Default: Default template
Google reCAPTCHAProtects the "Contact this store" form with Magento's Google reCAPTCHA. Only available when Magento's reCAPTCHA modules are enabled; without them the form works without reCAPTCHA.
Default: No
Messages per Visitor and Hour0 = no limit.
Default: 5
Delete Messages After (Days)Messages contain personal data. 0 = keep them until deleted by hand.
Default: 0

Note: to protect the form with Google reCAPTCHA, enter your reCAPTCHA keys in Stores > Configuration > Security > Google reCAPTCHA Storefront, then choose the same reCAPTCHA type in the form's Google reCAPTCHA setting.

Suggest a Store Form

Store Locator configuration: Suggest a Store Form
FieldDescription
EnableLets visitors suggest a store (link on the store locator). Suggestions are reviewed under Store Locator > Store Suggestions.
Default: No
NotifyEmail addresses, separated by commas. Leave empty for no notification.
Default: (empty)
Email SenderStore email identity used as the sender of suggestion emails.
Default: General Contact
Notification Email TemplateEmail template; customize it in Marketing > Email Templates.
Default: Default template
Enable Approved StoresNo: approving creates a disabled store, so you can complete it (hours, categories, coordinates) before it is shown.
Default: No
Inform the Visitor of the DecisionEmails the visitor when their suggestion is approved or declined.
Default: Yes
Approved Email Template / Declined Email TemplateEmail templates; customize them in Marketing > Email Templates.
Default: Default template
Google reCAPTCHAProtects the "Suggest a store" form with Magento's Google reCAPTCHA. Only available when Magento's reCAPTCHA modules are enabled.
Default: No
Suggestions per Visitor and Hour0 = no limit.
Default: 3

Import

Store Locator configuration: Import
FieldDescription
Import Right Away Up To (Rows)Larger admin imports run in the background by cron (Magento cron must be running).
Default: 1000
Maximum File Size (MB)Largest CSV file accepted by uploads, scheduled imports and URL downloads.
Default: 20
Scheduled ImportImports (adds and updates) stores from a CSV file on a schedule. The file is skipped when it has not changed since the last import.
Default: No
SourceRead the scheduled import from a file in var/import_export or from an https:// URL.
Default: File on the server
FilePath inside var/import_export, e.g. storelocator/stores.csv.
Default: (empty)
URLPublic https:// address of the CSV file. Addresses of private or local networks are refused, redirects are not followed.
Default: (empty)
ScheduleCron expression (server time), e.g. 0 2 * * * for every night at 2:00.
Default: 0 2 * * *

Developer

Store Locator configuration: Developer
FieldDescription
Debug LoggingWrites geocoding, map provider and import problems to var/log/magexweb_storelocator.log. API keys and customer data are never logged.
Default: No

Managing stores

Everything is managed from the Store Locator menu in the Magento admin: Stores, Categories, Services, Custom Attributes, Store Messages, Store Suggestions, Reports, Import / Export and a link to the configuration.

Store Locator menu in the Magento admin

Stores grid

Go to Store Locator > Stores. The grid supports keyword search, filters (including store view, category, customer group and coordinates state), column selection and mass actions: Enable, Disable, Find Coordinates, Export to CSV and Delete. Each row also has Edit, Duplicate, Enable/Disable and Delete actions. Click Add New Store to create a store.

Stores grid in the Magento admin

Adding and editing a store

The store form is divided into sections:

SectionFields
GeneralEnable Store, Store Name, Store Code (used by imports and the API), Store Views, Customer Groups, Featured (shown first, with a badge), Online Store (no address on the map), Sort Order, Business Type (structured data)
Address and LocationCountry, State/Province, City, Street Address (2 lines), ZIP/Postal Code, Location on Map (search box with place suggestions, Find from Address and a map with a draggable marker), Latitude, Longitude, Timezone
ContactPhone, Alternate Phone, Email (also receives contact form messages), Website
DescriptionShort Description (store list and info windows) and Description (WYSIWYG, store page)
ImagesLogo, Featured Image (store list, info windows, first on the store page), Map Marker, and up to 20 Gallery Images with alt text and drag-to-sort
Categories and ServicesThe categories and services the store belongs to (used by filters and widgets)
Opening HoursOne row per opening period, e.g. Monday 09:00 – 13:00 and Monday 14:00 – 18:00. Days without rows are closed. A closing time earlier than the opening time ends after midnight.
Holiday HoursRows for a date replace the weekly hours of that date: mark the date as Closed or enter its hours, with a title such as "Christmas Eve"
Custom AttributesValues of your custom attributes (see Custom attributes)
Search Engine OptimizationURL Key, Meta Title, Meta Description, Meta Keywords, Canonical URL

Note: choose a store view in the scope switcher of the form to translate the name, descriptions, URL key and meta data. Fields left on "Use Default Value" follow the default text.

Store form: General section
Store form: Contact section
Store form: Description section
Store form: logo, featured image, map marker and gallery images
Store form: Categories and Services
Store form: weekly opening hours
Store form: holiday hours
Store form: Search Engine Optimization

Categories, services and custom attributes

Categories

Go to Store Locator > Categories to group stores, for example Flagship Stores, Outlets or Service Centers. Each category has a name, code, status, description, sort order, an icon, an image, a map marker (used for its stores that have no marker of their own) and SEO fields. Categories appear as filters on the store locator and can limit a widget to certain stores.

Store categories grid
Editing a store category

Services

Go to Store Locator > Services to manage what stores offer, for example Click & Collect, Repairs or EV Charging. Each service has a name, code, status, description, sort order and icon. Services are shown on store cards and store pages and can be used as filters.

Store services grid
Editing a store service

Custom attributes

Go to Store Locator > Custom Attributes to add your own store fields. Choose the input type (text, text area, number, yes/no, date, URL, dropdown or multiple select) and whether the attribute is:

  • Required when a store is saved,
  • Shown on the storefront (store cards and store pages),
  • Used in search filters (yes/no, dropdown and multiple select),
  • Used in keyword search.

Dropdown and multiple select attributes have a list of options, and every attribute can have its own label per store view.

Custom store attributes grid
Editing a custom store attribute with options

Note: the input type cannot be changed after the attribute is created. Create a new attribute instead.

Store messages and suggestions

Contact this store

When the Contact Store Form is enabled in the configuration, store pages show a "Contact this store" form. Messages are emailed to the store's email address and/or other recipients, optionally confirmed to the visitor, and listed under Store Locator > Store Messages.

In Store Messages, filter messages by store or status, open a message to read it, set its status (New, Contacted, Closed) and add an internal note. Messages can be deleted automatically after a number of days (Configuration > Contact Store Form > Delete Messages After).

Store Messages grid
Reading a store message, with status and internal note

Suggest a store

When the Suggest a Store Form is enabled, the store locator links to a page where visitors can suggest a store, for example a shop that sells your products.

Review suggestions under Store Locator > Store Suggestions. Correct the data if needed, then click Approve and Create Store to create the store (disabled by default, so you can complete its hours, categories and coordinates) or Decline. The visitor can be informed of the decision by email.

Store Suggestions grid
Reviewing a store suggestion before approving it

Spam protection and Google reCAPTCHA

Both forms are protected by Magento's form key, a hidden anti-spam field and a limit of submissions per visitor and hour. They can also use Magento's own Google reCAPTCHA:

  • Enter the keys of the reCAPTCHA type you want (v2 "I am not a robot", v2 Invisible or v3 Invisible) under Stores > Configuration > Security > Google reCAPTCHA Storefront.
  • Choose that type in Google reCAPTCHA of the Contact Store Form and/or the Suggest a Store Form. "No" switches it off for that form.

Note: reCAPTCHA is optional. When Magento's reCAPTCHA modules are disabled or removed, the setting only offers "No" and both forms keep working with their other protections. Email templates can be customized in Marketing > Email Templates (templates starting with "Store Locator").

Import and export

Go to Store Locator > Import / Export to add or update many stores at once:

  • Click Download a sample file to see all columns.
  • Choose a CSV file (UTF-8, comma or semicolon separated) and a behavior, then click Check File. The file is validated first; errors are listed by line and nothing is changed until the whole file is valid.
  • Click Import. Files with more rows than "Import Right Away Up To" are imported in the background by cron.

Every import is listed in the Import History with its result and errors. Exports (all stores on this page, or the selected stores with the grid action Export to CSV) use the same format and can be imported again.

Import / Export Stores page with import history

CSV format

ColumnContent
identifierRequired. Unique store code; existing stores are updated
store_viewEmpty for the store row; a store view code for a row with translated text (name, url_key, descriptions, meta fields)
storesStore view codes where the store is shown, separated by |, or all (default for new stores)
categories, servicesCategory and service codes separated by |
hoursMon 09:00-12:00,13:00-17:00|Tue 09:00-17:00 (days not listed are closed)
special_hours2026-12-24 09:00-13:00 Christmas Eve|2026-12-25 closed Christmas Day
attr:<code>Custom attributes: text, Yes/No, or option labels (separated by | for multiple select)
customer_groupsCustomer group names separated by |, or all (default for new stores)
logo, imagePath of an image already in pub/media, e.g. magexweb/storelocator/location/shop.jpg (image = featured image)
imagesGallery images: paths separated by |, each optionally followed by ::alt text

Note: an empty cell keeps the current value; __EMPTY__VALUE__ clears it. The behavior "Delete the listed stores" deletes the stores whose identifiers are in the file. Cells starting with =, +, - or @ are exported with a leading apostrophe so spreadsheet programs do not run them as formulas; the import removes it.

Scheduled import

In Configuration > Import > Scheduled Import, import a CSV file from var/import_export or from a public https:// URL on a cron schedule. Unchanged files are skipped. URLs on private or local networks are refused and redirects are not followed.

Command line

CommandPurpose
php bin/magento magexweb:storelocator:import stores.csv [--behavior=append|delete] [--validate-only]Imports (or only checks) a CSV file
php bin/magento magexweb:storelocator:export stores.csv [--ids=1,2,3] [--no-store-views]Exports all or selected stores
php bin/magento magexweb:storelocator:import:process [--scheduled] [--force]Runs queued and scheduled imports now

Reports

Go to Store Locator > Reports to see, per period and store view: store locator and store page views, searches, searches without results, map selections, directions, calls, emails, website visits and messages, daily charts and the most active stores.

Store Locator usage reports with daily charts and top stores

Note: only daily counts are stored: no IP addresses, search terms or visitor identifiers. Optionally the events are also pushed to Google Tag Manager (window.dataLayer) as storelocator_<event>, for example storelocator_directions, with the store ID and name.

Storefront behaviour

Once enabled and configured, the store locator behaves as follows for shoppers:

  • The store locator is available at /store-locator (or the URL path you configured), with links in the footer and optionally in the top menu and header links.
  • Visitors search by address or place (with suggestions), "Use my location" (HTTPS only), distance and store name, and refine the results with filters.
  • The search is kept in the page URL, so results can be shared and the browser back button works.
  • Only enabled stores assigned to the current store view and visible to the visitor's customer group are shown, on the map, in the list, in widgets, in the REST search and in the sitemap.
  • Store cards show distance, live open/closed status ("Opens at 10:00", "Closing soon"), categories, services, custom attributes, opening hours and quick actions: call, email, website, directions and show on map.
  • Store pages show the gallery, address, contact buttons, opening hours (today highlighted), holiday hours, map with info window, description, custom attributes, nearby stores and the contact form.
Store locator search panel with filters
Store page: address, contact buttons and opening hours with today highlighted
Store page: nearby stores

CMS widget

Add a store locator to any CMS page or block with Insert Widget > Store Locator in the editor, or in Content > Widgets. Choose a title, limit it to categories and/or services (for example a "Dealers" page), choose the layout and whether to show filters. Several widgets can be placed on one page.

Widget optionDescription
TitleHeading shown above the widget (optional)
Only Stores in CategoriesShows only stores of the selected categories
Only Stores With ServicesShows only stores offering the selected services
LayoutMap + List, List + Map, Full Map, Grid, List or Map + Grid
Show FiltersShows or hides the search filters. Default: Yes

SEO and URLs

PageURL
Store locator/store-locator
Store page/store-locator/store-url-key (or /store-locator/store/store-url-key)
Suggest a store/magexweb_storelocator/submission
Filtered search/store-locator?lat=…&lng=…&radius=…&category=…
  • The URL path, store page URL structure and optional URL suffix (for example .html) are set in General configuration.
  • When a URL key or URL setting changes, store page URLs are rebuilt and old URLs redirect (301) to the new ones. Rebuild them by hand with php bin/magento magexweb:storelocator:urls:regenerate.
  • Every store has its own meta title, meta description, meta keywords and canonical URL; empty values use the templates from SEO configuration ({name} - {city} by default).
  • Store pages include JSON-LD structured data (LocalBusiness or the chosen business type, with address, coordinates and opening hours) and BreadcrumbList.
  • Search URLs with parameters can be set to "noindex,follow" so search engines index only the main page and store pages.
  • Store pages are added to the XML sitemap generated in Marketing > Site Map.

Admin permissions

In System > Permissions > User Roles > Role Resources > Store Locator, each area is a separate permission, so you can give staff exactly the access they need:

ResourceAllows
StoresView stores; Save Store, Delete Store, Duplicate Store, Edit Store Hours and Edit Holiday Hours are separate permissions
Categories / Services / Custom AttributesView, save and delete each
Store MessagesView messages; Edit Message Status; Delete Messages
Store SuggestionsView suggestions; Edit, Approve and Decline Suggestions; Delete Suggestions
ReportsView the usage reports
Import / ExportImport Stores and Export Stores
Store Locator ConfigurationStores > Configuration > Store Locator

REST API

The store search is public and returns only enabled stores of the store view in the URL (/rest/<store_code>/V1/...) that are visible to guests (or, with a customer token, to the customer's group). Page size, radius and filters are limited to the store settings, and the search is rate limited. Management endpoints need an admin or integration token with the matching Store Locator permission.

EndpointDescription
GET, POST /V1/storelocator/searchStore search (public)
GET /V1/storelocator/locations, /locations/:locationIdList or get stores (Stores permission)
POST /V1/storelocator/locations, PUT /locations/:locationIdCreate or update a store (Save Store)
DELETE /V1/storelocator/locations/:locationIdDelete a store (Delete Store)
/V1/storelocator/categories, /servicesGET, POST, PUT and DELETE categories and services (Category and Service permissions)

Example: GET /rest/default/V1/storelocator/search?request[latitude]=43.65&request[longitude]=-79.38&request[radius]=25&request[sort]=distance

Note: bearer tokens require the web server to pass the Authorization header to PHP (Magento's pub/.htaccess does this; check your setup if the document root is not pub).

Cron jobs and commands

Cron jobSchedulePurpose
magexweb_storelocator_geocode_pendingEvery 5 minutesFinds coordinates of new stores
magexweb_storelocator_import_processEvery minuteRuns queued admin imports
magexweb_storelocator_import_scheduledConfigured scheduleScheduled CSV import
magexweb_storelocator_leads_cleanDailyDeletes old store messages (if configured)
CommandPurpose
magexweb:storelocator:sample-data:install / :removeInstall or remove the sample stores
magexweb:storelocator:geocodeFind missing coordinates now
magexweb:storelocator:import / :exportCSV import and export
magexweb:storelocator:import:processRun queued and scheduled imports now
magexweb:storelocator:urls:regenerateRebuild the store page URL rewrites

Uninstallation

Composer installation

  1. Optional: php bin/magento magexweb:storelocator:sample-data:remove
  2. php bin/magento module:uninstall Magexweb_StoreLocator --remove-data (removes the module's tables, configuration, URL rewrites and media files)

Manual (app/code) installation

  1. php bin/magento module:disable Magexweb_StoreLocator
  2. Delete the app/code/Magexweb/StoreLocator folder.
  3. php bin/magento setup:upgrade && php bin/magento cache:flush. The tables stay until you remove them by hand.

Important: back up your database before uninstalling with --remove-data: stores, messages and suggestions are deleted permanently.

Troubleshooting and FAQ

The map is grey or shows "This page can't load Google Maps correctly"

  • Check the Browser API Key, that billing is enabled, that the Maps JavaScript API, Places API (New) and Geocoding API are enabled, and that your domain is in the key's website restrictions.

The OpenStreetMap map stays grey or shows no tiles

  • Check the Tile Server URL (https:// with {z}, {x} and {y}) and the key of your tile provider. With Content Security Policy in restrict mode, add the tile host to the CSP whitelist (img-src).

No address suggestions with OpenStreetMap

  • Check the Place Search URL (empty switches the address search off). With Content Security Policy in restrict mode, add its host to the CSP whitelist (connect-src).

Coordinates are not found with OpenStreetMap

  • Check the Geocoding URL and Contact Email and that cron is running. Requests are sent at most once per second, so large imports take a while; problems are logged in var/log/magexweb_storelocator.log.

A store does not appear on the storefront

  • Check that it is enabled, assigned to the store view, visible to the customer group and has coordinates. Then make sure the Store Locator Search index is up to date (cron must run when it is "Update by Schedule").

A store has no coordinates

  • Enter the Server Geocoding API Key, check the Coordinates column in the grid, run Find Coordinates or bin/magento magexweb:storelocator:geocode, and look in var/log/magexweb_storelocator.log.

Configuration changes do not show

  • Flush the cache in System > Cache Management (Full Page Cache and Store Locator).

"Use my location" does nothing

  • Browsers allow location access only on HTTPS pages, and the visitor must allow it.

An import stays queued

  • Large imports run in the background: make sure Magento cron is running, or run bin/magento magexweb:storelocator:import:process.

Store page URLs return 404 after changing the URL path

  • Run bin/magento magexweb:storelocator:urls:regenerate and flush the cache.

Searches return "Too many searches"

  • Increase Search > Search Requests Per Minute Per Visitor, or set it to 0. Behind a proxy or CDN, configure Magento to use the visitor's real IP address.

Support

For help, email info@magexweb.com. Please include your Magento version, PHP version, a description of the problem and, if possible, var/log/magexweb_storelocator.log (enable Developer > Debug Logging for details).

Tell us about your project.

Share a few details and we will reply with questions, a recommended approach and next steps.

  • Email info@magexweb.com
  • Phone +91 99092 71288
  • Hours Mon–Fri, 10:00 AM to 8:00 PM IST
  • Office D-1002, Jasmin Green 1, Near Vaishnodevi Circle, Ahmedabad 382421, India

  • Free consultation
  • NDA available
  • Reply by email