CodeCanyon Store Locator Google Maps - WordPress Plugin

CodeCanyon Store Locator Google Maps Setup Guide for WordPress

CodeCanyon Store Locator Google Maps is the marketplace listing for the Agile Store Locator plugin, which adds a store map, location list, address search, filters, directions, and backend tools for managing locations to a WordPress site. In this guide, we will not repeat the short product description already shown above on the page. Instead, we will walk through how to prepare the site, which settings to check first, how to add stores, how to place the locator on a page, and how to confirm that everything is working properly.

This guide is written for a site owner, content manager, or developer who needs to turn a basic "Where to Buy" page into a clear tool for finding the nearest location. Special attention is given to the Google Maps API, the [ASL_STORELOCATOR] shortcode, coordinates, search modes, filters, opening hours, CSV import, JSON cache, and troubleshooting common issues.

If you only have one location on the map, some of the plugin's features may feel excessive. But for a retail chain, dealer map, service center network, pickup locations, or partner directory, CodeCanyon Store Locator Google Maps is useful precisely because it brings the map, location cards, filtering, templates, import tools, and result validation into one workflow.

What a store locator actually solves on a WordPress site

The job of this plugin is broader than simply "showing a map." A standard Google Maps embed works fine for a single address, but it quickly breaks down as a user experience when you have many locations. Visitors do not want to inspect dozens of markers manually. They want to enter a city, ZIP code, or address, choose a category, see the closest options, open a store card, and get directions. The administrator, in turn, wants to update addresses without editing code by hand.

CodeCanyon Store Locator Google Maps solves that problem as a WordPress plugin: stores are managed in the admin panel, the map is displayed through a shortcode, search can rely on the Google Place API or database data, and the appearance is controlled with templates, colors, markers, and settings. According to the Agile Store Locator documentation, a store entry is more than just a name and address. For proper functionality, the city, state or region, ZIP code, country, and latitude/longitude coordinates also matter.

The main practical value of a store locator is reducing the path from "where can I buy this nearby?" to a specific location with an address, business hours, and directions. For a product site, that reduces pressure on support. For a dealer network, it helps surface partners clearly. For a service company, it helps route customers to the nearest office.

When the plugin is an especially good fit

The plugin makes sense when the site has multiple physical addresses and those addresses need to be searchable by distance, category, or region. That could be a chain of stores, showrooms, pickup points, dealers, service centers, clinics, training branches, sales offices, or a partner map.

The strength of Agile Store Locator is not a single standalone screen, but a set of connected tools. The official page highlights templates, list and accordion layouts, categories, opening hours, store logos, custom fields, analytics, import and export, multilingual support, Google Advanced Markers, database search, and Google-based search. In a real project, that means you can start with a simple locator and gradually make the experience more advanced: add categories such as "Retail" and "Service," enable a brand filter, import new locations through CSV, limit results to the nearest stores, and turn on caching for high-traffic use.

When another solution may be a better choice

The plugin may be unnecessary if the site only needs one address in the footer or a simple static map with no search. It also does not solve inventory management, appointment booking, a full real estate catalog, or a complex GIS setup on its own. For WooCommerce scenarios where the customer chooses a store during checkout, Agile Logix offers separate add-ons, so you should not expect the basic locator to automatically replace delivery logic, inventory handling, and pickup workflows.

Another important consideration is its dependence on Google Maps Platform. Maps, address suggestions, geocoding, and directions all require correctly enabled services and properly configured keys. If the team is not prepared to work with Google Cloud, key restrictions, request billing, and console errors, it is better to evaluate OpenStreetMap-based alternatives or a simpler directory without an interactive map upfront.

What to check before installation and first launch

Before installation, it helps to split preparation into three areas: the WordPress technical environment, store data, and external map services. This order saves time because most store locator issues are not caused by the shortcode itself, but by missing coordinates, an invalid API key, JavaScript optimization conflicts, or an unprepared address structure.

WordPress technical environment

Make sure you have WordPress administrator access, the ability to install a ZIP plugin, permission to edit pages, and access to clear the site cache. The CodeCanyon page lists compatibility with current WordPress branches as well as integrations with popular builders and forms, including Elementor, WPBakery, Contact Form 7, Gravity Forms, WPForms, WPML, and WooCommerce. That does not mean every optimization stack will work without testing, but it does provide a useful baseline: the plugin is designed for a standard WordPress site, not a separate external platform.

If the site uses aggressive JavaScript optimization, delayed script loading, or minification, identify in advance which plugin is responsible for those features. The Agile Store Locator documentation specifically discusses a conflict with WP Rocket, where delayed loading can break Google Maps and locator scripts. During preparation, you should know exactly where to disable optimization for specific files if the map does not appear.

Store data

For testing, one real or demo location is enough, but it needs to be filled out completely. The minimum set for a proper check is: name, street, city, state or region, ZIP code, country, and coordinates. The documentation notes that coordinates are essential for the marker to appear, and that empty or zero values will prevent the location from showing on the map. For a real launch, also add the phone number, website link, description, logo, business hours, and category if those details matter to users.

If you have dozens or hundreds of locations, do not start with a blind bulk import. First create one location manually and verify the map, then import a small CSV with three to five rows. Only after that should you import the full file. This approach helps catch column, encoding, ZIP code, and coordinate issues before the database fills up with hundreds of duplicates.

Google Maps Platform

For full functionality, you will need the Google Maps services that match your use case: map display, address geocoding, place suggestions, and directions. The Agile Store Locator documentation directly connects the API key field with the Direction API, Geocoding API, Google Javascript API, and Google Place API. Google also emphasizes in its own recommendations that keys should be restricted by application type and the specific APIs they need, and that map errors are often visible in the browser console.

Practical check: after adding the key, open the locator page in an incognito window, press F12, switch to the console, and run a test address search. If the map does not load, check the Google Maps error first, then the plugin settings, not the other way around.

Installation, the Google Maps key, and the first page output

Installation should not be the longest stage, but it is where people often skip the most basic validation. After uploading the ZIP package through Plugins - Add New - Upload Plugin, activate the plugin and go to its settings. Do not start with design, templates, or colors. First you need the basic chain of "API key - one location - shortcode - visible result."

Adding the API key

In the Agile Store Locator settings, find the Google API Key field, paste in the key, and save the settings. If the key is invalid, missing required services, or blocked by restrictions, both search and the map may fail. The official documentation recommends checking errors in the browser console. That is far more useful than guessing based on the page appearance, because different issues can look identical: an empty block, a gray rectangle, a Google message, or a missing search box.

For security, do not publish the key in instructions, tickets, or documents. Configure restrictions on the Google Cloud side. For the browser-based Maps JavaScript API, domain restrictions are typically used. For server-side requests, use the restriction type that fits the server scenario. Do not mix a public browser key with a server key unless you understand which APIs each part of the plugin actually uses.

Your first store and coordinate validation

In the Add New Store form, fill out the store data sections. The documentation describes four main groups: Store Information, Store Address, Store Timings, and Other Details. For the first test, the address and coordinates matter most. If automatic coordinate filling does not work, check the key and the geocoding service, then enter the coordinates manually. Do not leave latitude and longitude set to zero.

After saving, open the store list and make sure the entry did not lose its city, country, or ZIP code. If you later import a CSV, this manual record becomes your reference point: it makes it easy to compare column names, phone formatting, business hour formatting, and the presence of coordinates.

Displaying the map with a shortcode

The basic way to display the map is to add the shortcode to a WordPress page or post:

[ASL_STORELOCATOR]

The Agile Store Locator documentation also shows that the shortcode accepts attributes. For example, you can control map behavior, map controls, zoom, search, filters, and other modes:

[ASL_STORELOCATOR gesture_handling="cooperative" zoomcontrol="false" zoom="4"]

Do not add many attributes at once. First validate the basic output, then enable one option at a time and test the result. If the map breaks after adding an attribute, it is much easier to roll back one line than to debug a long shortcode with ten settings.

How to plan your store structure, categories, and fields

The most common implementation mistake is treating a store as a single address line. In practice, the locator works much better when the data is structured in advance by purpose: address fields for search, categories for filtering, custom fields for business attributes, business hours for deciding "go now or later," and logos and descriptions for trust.

Categories and markers

Categories are useful when visitors need more than the nearest address and want to choose the type of location. For example: retail store, service center, pickup point, dealer, showroom, or online location. Agile Store Locator supports categories, markers, and icon customization. That matters on larger maps because distinct markers help users understand which locations fit their needs before they even open a store card.

Do not create categories "for the future" if they do not help people choose. Five categories with a clear purpose are better than twenty internal statuses. A good test is this: if visitors do not understand why they need a filter, that filter is better kept as an admin note or a custom field instead of being shown on the public map.

Custom fields

The official documentation describes the Custom Field Manager and secondary field-based search. This is useful when stores have attributes that do not exist in the default form: service area availability, partner type, supported brand, pickup availability, parking, or service format. For custom-field search, you can use the search_2 attribute, for example:

[ASL_STORELOCATOR search_2="title,description"]

The documentation notes one limitation: secondary search is not available in every template. So choose the template first, then verify whether it supports the type of search you need. Do not promise users brand or service search until you have tested it in the selected layout.

Business hours and status handling

Opening hours are one of the most useful sections in a store card. Agile Store Locator allows you to define schedules, including multiple time slots per day. That makes it possible to show lunch breaks, different hours by day, and closed days. For visitors, that information is more valuable than a nice-looking marker because it immediately tells them whether it is worth going to that location.

If the schedule changes often, assign someone to keep it updated. Outdated business hours are worse than no hours at all: users show up to a locked door and lose trust in the site. At launch, test one regular day, one weekend day, one day with a break, and the display of a "closed" status if that status is used.

Configuring search, radius, and map behavior

Users judge a locator by the first search they perform. If they enter a city and see an empty map, too many markers, or an irrelevant list, even a correctly installed plugin will feel broken. That is why search configuration should come before decorative customization.

Address search vs. database search

Agile Store Locator supports multiple search types. Address search through the Google Place API is convenient when a user enters a street, city, or ZIP code and expects suggestions. Database search is useful when visitors are looking for a specific store, city, state, category, or custom field. The documentation also describes Boundary Box search, where results are limited to the visible map area.

The right mode depends on audience behavior. For a "where to buy nearby" page, address search and radius filtering are usually the best fit. For a dealer network where partner names are already known, store-name search can be more useful. For a directory of regional branches, filtering by country, region, and city is often the most practical option.

Radius, list display, and limiting the number of results

The documentation highlights three distance control options: slider, dropdown, and Boundary Box. A slider is visual, but it can lead to accidental radius changes. A dropdown works better when you want strict values. Boundary Box is useful when the user moves the map and wants to see only the locations within the current area.

On large datasets, do not show every store at once. The performance guidance recommends limiting the number of displayed locations, for example by showing only the nearest results, and in some cases displaying stores only after a search query. That reduces load and keeps the map readable. If you show hundreds of markers at once, enable clustering and test the speed on mobile.

Marker clustering

Clustering combines nearby markers into a single numbered cluster. For a regional or city map, this is close to essential. Otherwise, the city center turns into a dense patch of overlapping markers. Agile Store Locator lets you enable clustering in the settings or through a shortcode attribute:

[ASL_STORELOCATOR cluster="1"]

After enabling clustering, test two zoom levels: a broad regional view and a close neighborhood-level view. Good clustering should not hide stores permanently. Users should understand that the cluster expands as they zoom in, while individual store cards remain accessible.

Fallback store for empty results

If a user searches in an area where you have no locations, a blank screen feels like a failure. The Agile Store Locator documentation describes the default_store attribute, which displays a specified store when nothing is found within the radius. Example:

[ASL_STORELOCATOR default_store="14"]

This mode works only in distance-based filtering scenarios. Use it carefully: the fallback location needs to make sense. For example, a headquarters office, online store, main service center, or nearest regional warehouse. In the page copy, explain that if there is no nearby location, the visitor can contact the main office or use delivery instead.

CSV import, coordinates, and updating a large location database

For a network with many addresses, manual entry quickly becomes a bottleneck. Agile Store Locator supports importing and exporting store data through CSV. But import is not just a file upload. It is a data-quality process: you need to prepare the columns, verify the encoding, make sure coordinates are available, and avoid creating duplicates.

A mini workflow for safe imports

1. Create one location manually and export it as a structure sample.
2. Prepare a CSV with a few test rows, including addresses from different cities.
3. Check that the file includes country and ZIP code if they matter for your geography.
4. If coordinates are missing, make sure the Google Geocoding API is working and that the key is accepted by the plugin.
5. Upload the test file, import it, and verify the map, list, filters, and store cards.
6. Only after that should you import the full file.

The Import/Export Stores Data documentation explicitly calls out checking the Google Geocoding API Key before attempting to fetch missing coordinates. That is an important detail: if you import a file without coordinates while geocoding is not working, you will end up with records that exist in the admin panel but do not produce the expected markers on the map.

How to avoid duplicates and lost leading zeros

Duplicates appear when the same store is imported again without a clear update key. Before a large import, decide what counts as the identifier: an internal store code, the exact store name, the address, or a dedicated column. If you do not have such a field, it is safer to update in small batches and review the result after each one.

Also check ZIP codes that begin with a zero. Spreadsheet tools may convert those values to numbers and strip the leading zero. For a store locator, that is critical: ZIP-code search becomes inaccurate, and geocoding may pick the wrong region. Store ZIP codes as text and validate them after import.

When coordinates are better entered manually

Automatic geocoding is convenient, but it is not always precise enough. Manual coordinates are better for shopping centers, large campuses, warehouses, service entrances, markets, and properties with multiple buildings. Users are not looking for an abstract address - they are looking for the exact point of entry. If the marker lands on the building next door, the route may be technically correct but practically useless.

After editing coordinates, open the public map, click the marker, check the address in the store card, and test the directions. If the card shows one address but the marker is placed elsewhere, users will spot that mismatch faster than the administrator will.

Templates, appearance, and mobile result validation

Once the map loads and search is working, you can move on to the visual layer. Agile Store Locator includes several templates and layouts, including list, grid, and accordion options. The official page also mentions color schemes, map customization, markers, store logos, and responsive behavior.

How to choose the right template for the job

For a standard "Where to Buy" page, it is best to start with a layout where the map and list are visible at the same time. Users enter an address, see the nearest locations, and immediately compare distance, city, business hours, and buttons. For a regional directory, an accordion layout with a country - region - city structure may work well. For a showcase page with only a small number of locations, a card grid can be a good fit.

Do not choose a template based only on a screenshot. Test it with your real data: long city names, different phone formats, multiple categories, missing logos, closed days, and mobile screens. A beautiful demo layout can fall apart with real addresses if the store cards contain too much text.

Mobile behavior

Most store locator users open it on a phone while they are already in the city or near a store. That makes mobile testing more important than a perfect desktop view on a wide monitor. Check whether the search field fits, whether markers are easy to tap, whether the list blocks the map, whether the directions button works, and whether the site's sticky header gets in the way.

The documentation includes settings for showing the map above the listing on mobile devices, controlling map height, enabling fullscreen mode, hiding the list, and adjusting other elements. Use those options not for decoration, but to improve the user's first action: enter an address, choose a location, and get directions.

Careful customization without editing the plugin core

Do not edit plugin files directly. Those changes are easy to lose during updates, and troubleshooting becomes harder. If you need to change text, data order, colors, or the template, first look for built-in settings, the Content Customizer, the Template Customizer, string translations, and documentation for safe customization. For minor CSS changes, use the location recommended by the documentation or your site theme.

If a tweak depends on a specific class, find it first with your browser inspector on the actual page. Do not paste random CSS from a forum if it was written for a different locator template. The safe workflow is simple: copy the page to a staging site, apply one change, verify desktop and mobile, then move it to production.

Practical scenario: a "Where to Buy" page for a store network

Let us look at a concrete example that fits CodeCanyon Store Locator Google Maps well: a brand has a network of partners, the customer needs to find the nearest location, filter service stores, and view business hours. The goal is not just to display a map, but to build a working, testable user flow.

Goal

You need to create a "Where to Buy" page where a visitor enters their city or address, sees the nearest stores, can choose the "Retail" or "Service" category, open a location card, and get directions. The administrator should be able to update locations through CSV and review search statistics.

Preparation

Before configuration, prepare three test stores: one central location, one regional location, and one service location. For each one, fill in the address, coordinates, phone number, website, category, business hours, and a short description. If you plan to use logos, include at least one store with a logo and one without it so you can verify both card states.

Steps

1. Install and activate the plugin, then add the Google API Key in the settings.
2. Create store categories, for example "Retail" and "Service."
3. Add three test locations through Add New Store and verify the coordinates.
4. Create a WordPress page and insert the [ASL_STORELOCATOR] shortcode.
5. If you need clustering, add the cluster="1" attribute or enable the setting in ASL Settings.
6. Test address search, name search, category filtering, and directions.
7. Adjust the template and colors only after search and data are working correctly.

Validation

Open the page as a regular visitor. Enter an address near the first store and make sure it appears higher in the list. Then enter a city where you have no locations and check the empty-result behavior. If you use a fallback store, confirm that it appears only in the intended mode. Finally, open the map on a mobile device and make sure the directions button is not hidden and the map does not freeze.

One important nuance

If address search works but the distance-based sorting seems wrong, do not rush to change the template. First check the store coordinates and the format of the entered address. The problem may be in the data, not the map. For ZIP codes that exist in multiple countries, include the country or limit the search to the appropriate region.

Performance, caching, and optimization compatibility

A locator with ten locations and a locator with a thousand locations create very different loads. Even if the plugin is installed the same way, the map, list, and filters can behave differently. That is why performance needs to be planned in advance, especially if the page gets heavy traffic or the location database is updated often.

JSON Cache

The Agile Store Locator documentation describes JSON Cache as a way to pre-save store data and serve it from JSON files instead of repeating requests to admin-ajax.php and the database. That reduces server load and speeds up delivery on multilingual sites, because files for active languages can be served directly.

Enable caching only after the data and filters have already been validated. Then change one test store and confirm that the update appears on the public page after the cache is refreshed. If visitors are seeing old data, the issue may be the caching layer rather than the import itself.

Limiting the result set

For large databases, it is often better to show not every location, but a limited set of nearest results. The slow-map documentation recommends using JSON Cache, limiting the number of stores, and in some cases showing locations only after the user enters a search query. That approach is better for both speed and usability: visitors rarely need to see every store in the country all at once.

WP Rocket and delayed JavaScript loading

If the site uses WP Rocket or a similar optimizer, test the map after enabling delayed JavaScript loading. The Agile Store Locator documentation describes cases where lazy loading or JavaScript delay breaks Google Maps and the plugin files. The suggested fix is to exclude jQuery, the Google Maps API, and Agile Store Locator scripts from the relevant optimization modes.

Do not copy exclusions mechanically. File paths may differ, and the active script set depends on the plugin version and configuration. Open the page source, find the actual locator script URLs, and add exclusions in a test environment first. Then clear the cache, open the page in incognito mode, and check the console.

SEO, accessibility, and trust on the "Where to Buy" page

A locator helps not only the user, but also the overall quality of a product page. Still, it does not replace textual content. Search engines and assistive technologies understand a map less effectively when it is not surrounded by context, addresses, explanations, and standard navigation. That is why a "Where to Buy" page should combine an interactive map with clear HTML text.

What to add next to the map

Add a short explanation before the locator: how to search, what the categories mean, and when to use the filters. If the network is small, you can also add a plain list of key cities or regions below the map. If there are different partner types, explain them in the surrounding text. This helps users who do not want to interact with the map and improves the page's overall clarity.

If stores have separate detail pages, make sure they do not create duplicates with empty or nearly identical content. The Agile Store Locator documentation mentions compatibility with SEO plugins and the Store Detail page feature. For real SEO value, those pages should have unique address details, clear headings, and should not end up indexed as hundreds of thin duplicate pages.

Accessibility and clear actions

The CodeCanyon page and the official site mention ADA compliance. In practical terms, that does not remove the need to test your theme, contrast, and user-facing text. Make sure the directions and website buttons are visible, color markers are not the only way to identify a category, and store card text remains readable on mobile.

It is also helpful to add a short text fallback such as: "If the map does not load, contact us or choose your city from the list." This is especially important if your audience uses corporate networks, script blockers, or browsers with restricted geolocation permissions.

Multiple locators, languages, and team workflow

On a small site, one administrator often manages the locator. On a larger project, the map quickly becomes a shared workflow: regional managers send new addresses, the content team updates business hours, the developer handles the template, and the marketer reviews search analytics. If that process is not defined in advance, the plugin may be configured correctly while the data gradually becomes outdated.

When you need different locators on different pages

The official Agile Store Locator documentation describes creating multiple locators on different pages. That is useful when one map should show every brand location, while other pages should show only specific regions, categories, or use cases. For example, the main product page can display an overall "Where to Buy" map, the service page can show only service centers, and the partner section can show dealers with a separate template.

The practical risk here is that the team starts copying the same shortcode and accidentally ends up with identical maps across different sections. Before publishing, create a simple table: page, purpose, category set, template, shortcode attributes, and who updates the data. That is much easier than later trying to figure out why a regional page is showing stores from another country.

Example of page-level separation

• The "Where to Buy" page shows all retail locations and uses address search.
• The "Service" page shows only service centers and displays an expanded description.
• The "Dealers" page uses region filtering and a city-based accordion layout.
• A campaign-specific page opens a preselected category or address through shortcode parameters, if that scenario is supported by the configuration.

After configuring each page, test it independently: basic search, default category, empty results, mobile view, and absence of irrelevant stores. If two pages use different data sets, do not evaluate both of them with the same test address.

Multilingual setup and interface strings

The official materials mention support for multiple languages, RTL, and WPML integrations. That matters for international directories, but a multilingual locator requires discipline. You need to translate more than just static UI text such as the search placeholder. Custom fields, category names, store descriptions, and sometimes country-specific data also need a plan.

If the site runs in multiple languages, first decide which data set is the primary one. One option is a shared store database with translated interface strings. Another is separate locators for different regions and languages. According to the documentation, JSON Cache can serve active languages, so after enabling cache, verify not only the main language but also each localized page.

Localization check: open the locator in each language, run the same search, compare the store card, category name, empty-result text, and directions button. If the UI is translated but the store data remains in one language, that should be a deliberate choice, not an accidental gap.

Roles and permissions for data updates

Not every employee needs full WordPress administrator access. If store data is updated by a content manager, that person needs access to the relevant sections, not to themes, plugins, and security settings. The Agile Store Locator documentation includes separate materials on permissions, so for a team project it is worth verifying which roles are actually required to add, edit, and import stores.

Even with the right permissions, you still need a review process. A solid workflow looks like this: the manager prepares the CSV, a second person reviews a few rows, the administrator imports a test batch, and only then is the main file published. For manual edits, keep a change log: who updated the address, what exactly changed, and when the public map was checked. This is especially important for networks where an incorrect address or business hour creates an immediate offline problem.

Search analytics and feedback

The official Agile Store Locator site mentions a dashboard and analytics: number of stores, categories, markers, searches, popular queries, and views. That data is useful not as a decorative chart, but as a source of improvement ideas. If users frequently search for a city where you do not have a location, you can add fallback text, a shipping page, or a partner contact. If one store receives frequent views, make sure its hours and contact details are fully up to date.

Do not draw conclusions from a single day of data. Look for recurring patterns: empty results, popular cities, frequent clicks on directions, and stores with no views. Those signals can help you change category order, add new filters, enable a default store, refine address suggestions, or place a region list below the map.

Pre-launch validation and rollback planning

Before showing the locator to your full audience, run a short acceptance test. It should cover more than just "the page loads." Include user actions, admin actions, and a failure scenario. The more locations and filters you have, the more important it is to have a rollback plan.

Public-side checklist

• The page opens without errors in the browser console.
• A basic address search returns the expected nearest location.
• The category filter does not accidentally hide every store.
• Clustering expands as you zoom in and does not prevent store selection.
• The store card contains the address, phone number, business hours, and a clear directions button if those fields are used.
• The mobile version lets users search, open a store card, and go to directions without horizontal scrolling.
• Empty results explain what to do next instead of leaving the user with a blank map.

Admin-side checklist

In the admin panel, test adding a new location, editing an existing one, importing a test CSV, exporting data, refreshing the JSON cache, and rolling back a questionable setting. If multiple employees use the locator, each one should perform their actual workflow: the content manager edits a store, the marketer checks analytics, and the developer reviews the console and cache behavior.

For rollback, save the working shortcode, an export of the current stores, and a list of modified settings. If the map stops working after you enable a new option, you should be able to return quickly to the last stable state: remove the attribute, clear the cache, restore the previous template, or disable the JavaScript optimization. This plan becomes especially important before an advertising campaign, when the "Where to Buy" page is about to receive a sharp traffic increase.

Common CodeCanyon Store Locator Google Maps issues and troubleshooting

The best way to troubleshoot is to move from the visible symptom to the cause. Do not change multiple settings at once. First reproduce the issue in a clean browser window, then open the console, then check the store data, and only after that review optimization settings or the template.

The map does not load or shows a Google error

Symptom: instead of the map, you see an empty block, a Google message, a gray background, or the map disappears after loading. Possible cause: an invalid API key, a required service that is disabled, key restrictions, missing billing, or a script conflict. What to check: the browser console, the presence of maps.googleapis.com in the page source, the key configuration in Google Cloud, and the API key field in ASL Settings. How to fix it: enable the required services, correct the restrictions, save the plugin settings, and clear the cache. If the error changes after that, continue troubleshooting based on the new error, not the old symptom.

Address search does not return suggestions

Symptom: the map is visible, but the address field does not suggest places or the search returns an empty result. Possible cause: an issue with the Places API, changes to newer Google APIs, incorrect key restrictions, or the search region. Agile Store Locator separately documents Google Place API issues and newer search scenarios. What to check: enabled APIs, console messages, and Google's Autocomplete documentation. How to fix it: use the current mode supported by your installed plugin version, and temporarily test the alternative database search if address suggestions are unavailable.

Markers do not appear even though stores exist in the admin panel

Symptom: the store list is populated, but there are no markers on the map, or some locations are missing. Possible cause: empty or zero coordinates, a faulty import, a category filter, a radius restriction, or a JSON cache holding stale data. What to check: the latitude and longitude of the specific store, its category, country, ZIP code, cache status, and the list-loading mode. How to fix it: fill in coordinates manually or through a valid Geocoding API, clear the cache, disable the questionable filter, and test a single location on a clean page with the basic shortcode.

ZERO_RESULTS error during geocoding

Symptom: geocoding returns a message saying the address was not found. Possible cause: an ambiguous ZIP code, missing country information, duplicate ZIP codes across different countries, or a search query that is too short. The Agile Store Locator documentation gives an example where the same postal code can exist in multiple countries. What to check: the full address, country, city, and region. How to fix it: make the address more specific, add the country, limit the search to the right territory, or enter the coordinates manually.

The map performs slowly on a large database

Symptom: the page takes a long time to open, the browser freezes, or markers appear with a delay. Possible cause: too many markers on the initial screen, no JSON Cache, a heavy theme, an unoptimized list, or script conflicts. What to check: the number of locations, the "show only after search" mode, JSON cache, clustering, and result limits. How to fix it: enable JSON Cache, clustering, nearest-result limits, and post-search loading. If the issue appeared after an optimizer was enabled, temporarily disable delayed JavaScript loading for the map and plugin scripts.

The shortcode appears as text or displays nothing

Symptom: the page shows [ASL_STORELOCATOR] as plain text, or the locator area is empty. Possible cause: the plugin is not active, the shortcode was inserted into a block that does not process shortcodes, or the page is serving an old cached version. What to check: whether the plugin is active, whether you are using a Shortcode block in the editor, the uncached page, and the basic shortcode without attributes. How to fix it: activate the plugin, move the shortcode into the correct block, remove invalid quotes, and test on a new temporary page.

When CodeCanyon Store Locator Google Maps is the right choice

CodeCanyon Store Locator Google Maps is worth using if you need more than a decorative map block and want a functional WordPress locator: stores in the admin panel, address search, categories, filters, business hours, CSV import, multiple templates, caching, and troubleshooting tools. It is especially useful for chains, dealers, service centers, and manufacturer sites where users need to find the nearest location quickly and get directions.

Before launch, verify three things: a valid Google Maps API setup, correct coordinates for at least one test location, and the basic shortcode on a clean page. After that, gradually enable filters, clustering, templates, caching, and import. That order reduces the risk of debugging the API key, CSV, theme, optimizer, and custom template all at the same time.

If the final review shows that the workflow matches your site's needs, you can get the WordPress version, install it on a staging copy of the site, and walk through the full visitor journey from entering an address to getting directions. Make the final decision not by the number of features, but by how quickly a real user can find the right store and how confidently the administrator can keep the data up to date.