Easy Store Locator 3.0 shows your store locations on a map with a searchable list. Visitors can search by name, city, or ZIP, filter by tag or featured stores, open a pin, and click Call, Website, or Get Directions.

The package has two parts that work together:

• Component: Dashboard, Locations, Categories, Tags, CSV Import, Batch Geocoder, Search Log, and Configuration.
• Module: the public map and list. You choose the map provider, layout, search behaviour, and appearance here.

Map providers

• Google Maps: needs a Google Cloud project, billing, API key, Map ID, and the correct APIs enabled (see Google API setup).
• OpenStreetMap: Leaflet tiles bundled with the module. No Google API key. Follow OSM tile and Nominatim usage rules.

Both providers use the same location data and layouts. Only the map engine and geocoding path change.

Always required

• Joomla: 4.x, 5.x, or 6.x
• PHP: 8.1 or newer
• Access: Super User (or administrator) to install extensions

If you use Google Maps

• Google Cloud project with billing linked
• Maps JavaScript API enabled (map and markers)
• Places API enabled if you use Google place suggestions in the search box
• Geocoding API enabled if visitors search by city or ZIP for radius results, or if Batch Geocoder uses Google
• API key with HTTP referrer restrictions (browser key for the module)
• Map ID for Advanced Markers (DEMO_MAP_ID is fine for testing)
• Optional server key in Configuration for Batch Geocoder

If you use OpenStreetMap

• No Google Cloud project or API key
• Browser must load OpenStreetMap tiles
• City or ZIP radius search needs Nominatim (or your geocode path) reachable. Respect fair-use limits

1. Download EasyStoreLocator_UNZIP.zip from your purchase email or the Downloads section.
2. Extract the UNZIP on your computer. Inside you should see pkg_store_locator_3.0.0.zip and ReadMe.txt.
3. Important: do not upload the outer UNZIP file to Joomla. Install the package zip.
4. In Joomla go to System > Install > Extensions > Upload Package File.
5. Choose pkg_store_locator_3.0.0.zip and wait for success.
6. Open Components > Easy Store Locator to confirm the Dashboard loads.
7. System > Maintenance > Clear Cache.

Later updates: install a newer package the same way. Locations and module settings stay.

1. Open Components > Easy Store Locator.
2. Add locations under Locations (or Import CSV).
3. If addresses have no coordinates, open Configuration, set the geocode provider, then run Batch Geocoder.
4. Optional: create reusable tags under Tags.
5. Go to Content > Site Modules > New > Easy Store Locator.
6. Set Title, Status Published, and a Position (or load the module in an article).
7. Open the Map tab. Set Map provider to Google Maps or OpenStreetMap.
8. If Google: paste API key and Map ID (see Google API setup). Enable the APIs listed there first, or the map / search will not work.
9. Open Search & Filters and turn on radius search if you want city or ZIP search.
10. Save, clear cache, open the front-end page.

Set the provider on the module Map tab.

Quick comparison

• Cost: Google needs Cloud billing. OpenStreetMap has no Google bill, but heavy traffic may need your own tiles.
• Setup: Google needs key + Map ID + enabled APIs. OpenStreetMap works without a Google key.
• City / ZIP radius: both can do it when geocoding works (Google Geocoding API or Nominatim).
• Get Directions: always opens the public Google Maps website as a normal link. It does not use your Maps JavaScript API key.

Google strengths

• Familiar Google tiles and Advanced Markers
• Place suggestions when Places API is enabled
• Marker clustering when enabled in the module

Google limitations

• Billing required even for small sites
• Maps JavaScript API alone is not enough for city/ZIP search: you also need Geocoding API
• Place suggestions need Places API
• Wrong HTTP referrers cause a blank map
• Advanced Markers need a Map ID

OpenStreetMap strengths

• No Google key or Map ID
• Leaflet is bundled
• Good default when you want to avoid Google Maps Platform

OpenStreetMap limitations

• Public OSM tiles are for light use; high traffic should use a compliant tile provider
• Nominatim has fair-use and rate limits; do not hammer it for bulk geocoding
• Keep OSM attribution visible
• No Google-style map JSON themes or Map IDs
• No built-in OSM routing popup (Directions still opens Google Maps web)
• If the browser cannot reach tiles or Nominatim, the map or search can fail

Use these steps when the module Map provider is Google Maps. If an API is not enabled, the matching feature will not work even when the map looks fine.

Which APIs to enable

• Maps JavaScript API: required. Without it the map does not load.
• Places API: required for Google place suggestions in the search box. Without it, suggestions stay off or fail quietly.
• Geocoding API: required for city or ZIP radius search on the front end, and for Batch Geocoder when Configuration uses Google. Without it the map can still show pins, but radius search cannot resolve a place to coordinates.

Steps

1. Open Google Cloud Console, create or select a project, and link billing.
2. Go to APIs & Services > Library and enable Maps JavaScript API, Places API (if you want suggestions), and Geocoding API (if you want radius search or Google Batch Geocoder).
3. Create an API key under Credentials. Restrict it with HTTP referrers for your sites.
4. Under API restrictions, allow the same APIs you enabled.
5. Important: restricting the key is not enough. Each API must also be enabled on the project Library page.
6. Create a Map ID (or use DEMO_MAP_ID for tests).
7. In the module Map tab, paste the browser API key and Map ID.
8. For admin Batch Geocoder with Google, also paste a server-capable key under Components > Easy Store Locator > Configuration > Batch geocoder.
9. Save, clear cache, hard-refresh the front end.

Start guide: Google Maps Platform get started

1. Module > Map tab > Map provider = OpenStreetMap.
2. Leave Google API key and Map ID empty (they are hidden or unused).
3. Save, clear cache, open the front end.
4. Keep OpenStreetMap attribution visible.

Search and geocoding

• City and ZIP radius search use Nominatim-style geocoding on the front end.
• If Nominatim is blocked or rate-limited, radius search will not resolve the place. Pins that already have coordinates still show.
• For many addresses without coordinates, use Batch Geocoder with Configuration set to Nominatim (light use) or Google (with a server key).
• High-traffic sites should plan a compliant tile source instead of relying only on the public OSM tile endpoint.

Open Components > Easy Store Locator > Configuration (also linked from the Dashboard).

This screen stores global component settings. Front-end search defaults (radius, units, country bias, show on load) live on each module under Search & Filters, not here.

Batch geocoder

• Geocode provider: Google Geocoding API or OpenStreetMap Nominatim.
• Google server API key: used only by the admin Batch Geocoder when provider is Google. Without this key (and Geocoding API enabled), Google batch geocoding will not fill coordinates.
• Batch size: how many addresses to process per run.

Search logging

• Enable search logging: global master switch. If Off, no queries are stored even when a module has Search logging On.
• Search limit per IP: 0 = disabled. When set, limits how many logged searches one IP can send in the period.
• Rate limit period (seconds): window for the IP limit.

Module Search logging must also be On for that module to send log requests.

Advanced

• Keep data on uninstall: when Yes, location, tag, and search-log tables stay if you uninstall the component.

Permissions

• Standard Joomla ACL for who can configure and manage the component.

Dashboard

Open Components > Easy Store Locator. Counts and quick links to Locations, Categories, Tags, Import, Batch Geocoder, Search Log, and Configuration.

Locations

Open Locations to manage every store.

• Toolbar: New, Publish / Unpublish, Featured / Unfeatured, Duplicate, Delete, Import CSV, Export CSV
• Search matches title, address, phone, email, website, social, hours, description, tag, category, coordinates, and ID
• Filters: status, featured, category, tag, access

Edit location

• Store name (required)
• Category (component category) and Tag (dropdown of managed tags, or create new)
• Address, Phone, Email, Website, Facebook, Twitter / X, Hours, Description
• Latitude / Longitude: optional if Address is set. Leave empty and use Batch Geocoder, or use the map picker
• Sidebar: Status, Featured, Pin colour, Access, Publish dates, Ordering

Locations without coordinates do not appear on the map until geocoded.

Open Components > Easy Store Locator > Tags.

Tags power the visitor filter chips on the map (when Show tag chips is On in the module). Categories are separate and control which module instances can load which stores.

• Create, publish, unpublish, rename, delete, and order tags
• On the location form, choose an existing tag from the dropdown or use Create new tag
• New tags are saved automatically and appear next time
• Renaming a tag updates all locations that used the old name
• Deleting a tag clears that tag from matching locations

Import CSV

1. Open Import CSV (or from the Locations toolbar).
2. Download the sample CSV.
3. Required column: title. Coordinates optional when address is present.
4. Optional: Replace all existing component locations.
5. Import, then check pins on the front end.

Supported columns include tag, joomla_category, address, phone, email, website, facebook, twitter, hours, description, latitude, longitude, pin_color, featured, access, published, publish_up, publish_down.

Export CSV is on the Locations toolbar.

Batch Geocoder

1. Set provider (and Google server key if needed) under Configuration > Batch geocoder.
2. Open Batch Geocoder. It lists locations with an address but no coordinates.
3. Run the geocode action and confirm coordinates on the Locations list.

• Google: Geocoding API must be enabled and the Configuration key must be valid, or geocoding fails.
• Nominatim: light use only. Follow usage policy and keep a sensible batch size.

Open Components > Easy Store Locator > Search Log.

Shows front-end radius and name searches that were logged.

• Configuration > Enable search logging must be On (global)
• The module Search logging switch must also be On
• If either is Off, new searches are not stored
• Optional IP rate limits in Configuration reduce abuse
• Use Clear log on the toolbar when you want an empty table

Edit the module under Content > Site Modules and open the Map tab.

• Map provider: Google Maps or OpenStreetMap. Wrong choice for your keys means a blank map or unused Google fields.
• Google Maps API Key: required for Google. Without it the module shows a missing-key message.
• Map ID: required for Google Advanced Markers. Use DEMO_MAP_ID for tests.
• Map Language: Google map UI language.
• Map Height: desktop map height (example 560px).
• Scroll zoom: allow mouse wheel zoom on the map.
• Fit All Stores on Load: auto-zoom to show every pin. When Off, use Zoom and optional initial lat/lng.
• Map type (Google): roadmap, satellite, terrain, hybrid.
• Map type / Fullscreen / Street View controls (Google): show or hide those map controls.
• Marker clustering: group nearby pins (Google and OpenStreetMap).
• Map style JSON (Google): optional styled map. Empty = default look.

If Google APIs are not enabled as described in Google API setup, the map, place suggestions, or radius geocoding will not work.

Open the module Layout tab.

• Classic: map beside a store list (optional map/sidebar widths)
• Split: equal map and list columns
• Overlay: list floats over the map
• Cards: map on top, card list below
• Map only: full map; list opens with a toggle

• Sidebar position: left or right (Classic / Split / Overlay)
• Show sidebar and Sidebar toggle

Open the module Search & Filters tab. These settings are per module.

• Radius search: city or ZIP search with distance. Needs working geocoding (Google Geocoding API or Nominatim). If Off, visitors cannot run radius search.
• Default radius and Radius options: dropdown values (example 5,10,25,50).
• Distance unit: miles or kilometres.
• Show distance: show distance labels after a radius search.
• Geolocate on load: ask for browser location when the page opens (visitor must allow permission).
• Show geolocate button: Find my location control.
• Google place suggestions: Google only. Needs Places API. If Places API is off, suggestions will not work.
• Search logging: send queries to Search Log when Configuration logging is also On.
• Name search and Search bar position
• Max search results / Max search zoom
• Country geocode bias: dropdown of countries. Limits suggestions and geocoding to one country. None = worldwide.
• Show locations on load / Hide list until search
• Show tag chips / Show store count / Featured filter
• Chips position and Chips align

Open the module Store Details tab to show or hide fields in the list and info window.

• Get Directions, Address, Hours, Description
• Call, Email, Website, Facebook, Twitter / X

A button only appears when that field is filled on the location and the toggle is On. Get Directions opens the public Google Maps website and does not use your Maps JavaScript API key.

Locations

• Location source: component locations or module list
• Component categories: limit which category stores load
• Filter tags: optional comma-separated tag filter for which stores load

Appearance

• Accent colour, panel colours, text, borders
• Corner style, title size / weight / align, row padding
• Action button style: text, icons, or both

Open the module Advanced tab.

• Tablet / Mobile / Small phone map min height: minimum map height at those breakpoints
• Module Class Suffix and optional search CSS class
• Extra CSS: custom rules for this module instance
• Layout: Joomla alternate module layout if you override the template

The How To tab inside the module is a short in-admin guide.

Module position

1. Set a Position your template supports.
2. Under Menu Assignment, choose the pages.
3. Save and clear cache.

Module in an article

Insert the module with the editor module button (or loadmodule / loadposition).

Component map menu item

Create a menu item of type Easy Store Locator map view for a dedicated locator page.

After publishing

1. Clear cache and hard-refresh (Ctrl+F5).
2. Confirm pins, popup actions, search, and tag chips.
3. If Google: test city or ZIP radius search only after Geocoding API is enabled.
4. If OpenStreetMap: confirm tiles load and attribution is visible.

Map empty / no pins

• Each location needs a name plus valid latitude and longitude.
• Confirm the module loads component locations (or has its own stores).

Google map does not load

• Map provider = Google; key and Map ID filled.
• Maps JavaScript API enabled on the same project.
• Billing linked; HTTP referrers include your site.

Map loads but city / ZIP radius fails

• Enable Geocoding API on the project.
• Key restrictions must allow Geocoding API.

Place suggestions missing

• Module Google place suggestions = On.
• Places API enabled on the project and allowed on the key.

OpenStreetMap grey box

• Provider = OpenStreetMap; browser can reach OSM tiles.

Search Log empty

• Configuration Enable search logging = On and module Search logging = On.

Batch Geocoder fails

• Check Configuration provider and Google server key if using Google.
• Addresses must be filled; rows that already have coordinates are skipped.

Still stuck? Note Joomla version, PHP version, map provider, and which APIs are enabled. Open a ticket at support.joomlax.com.

• Which file do I install?

  • Unzip EasyStoreLocator_UNZIP.zip, then install pkg_store_locator_3.0.0.zip.

• Which Google APIs must be on?

  • Maps JavaScript API for the map. Places API for place suggestions. Geocoding API for city/ZIP radius search and Google Batch Geocoder.

• Does Get Directions use my API key?

  • No. It opens the public Google Maps website as a normal link.

• Where are radius and country bias set?

  • On the module Search & Filters tab. Configuration holds geocoder, logging, and permissions.

• Where can I get help?

  • support.joomlax.com

Documentation: joomlax.com/documentation/easy-store-locator