FacetWP Map - WordPress Plugin

FacetWP Map Guide: configuring the map, geo-filtering, and result display

FacetWP Map is not meant to simply drop a nice-looking map onto a page. Its job is more involved: connect a Google Map to FacetWP results, show markers based on post coordinates, and let visitors filter a directory using standard facets, radius search, or the current map area.

This guide walks through a practical setup for a WordPress site: what to check before installation, how to understand the difference between the legacy Map add-on and the new built-in Map facet, what data markers require, how to connect the map to Listing Builder, how to configure the Google Maps API, Map ID, clustering, marker info windows, result validation, and troubleshooting for common issues.

This material is aimed at a webmaster, developer, or directory site owner who already understands why the site needs a map: store locations, branch offices, real estate listings, event venues, jobs, service centers, tourist attractions, or any other set of posts with coordinates. If your use case comes down to a single static address on a contact page, this guide will still help you see why FacetWP Map may be more than you need.

What problem the map solves in FacetWP

In FacetWP, the map is not a standalone directory and not a replacement for your post output template. In the FacetWP documentation, it is described specifically as a facet, meaning a filtering control that works together with a FacetWP-enabled listing. That distinction matters: the map pulls its set of posts from the active listing, draws markers using the coordinates of those posts, and updates alongside the other facets.

In practice, that means the user does not see "every point in the database," only the markers that match the current result set. If a visitor selects a category, city, price, service, or search radius, the map should show markers only for matching posts. If filtering by the visible map area is enabled, the visible map area itself becomes a filter: the user pans or zooms the map, and the result list updates in sync.

The key rule of FacetWP Map is this: you need a properly configured listing first, then coordinates, and only then the map. If you start with the map while the listing is not configured or FacetWP cannot determine the query, markers will not appear, even if the Google API key is entered correctly.

Where the map is especially useful

The best FacetWP Map use cases are the ones where each post has real geographic meaning and users choose based not only on text, but also on distance or location. For example, a branch directory can be filtered by services and neighborhood, a real estate catalog by property type and price, a doctor directory by specialty and proximity to the user, and an events list by topic and city.

• A store directory where visitors are trying to find the nearest location or partner.
• A real estate site where the map helps compare listings in a specific neighborhood.
• A directory of service centers, branches, dealers, or regional offices.
• An events portal, local attractions site, or local services directory.
• An internal asset directory, if editors already manage coordinates through ACF, Meta Box, or another data source.

When the product may be unnecessary

FacetWP Map can be overkill if the page only needs a single "how to find us" location, a simple embedded Google Map with no filters, or a ready-made store locator with its own location storage system. FacetWP becomes valuable when the map needs to be part of a filterable set of WordPress posts. If the site does not yet have a post structure, coordinate fields, and a clear listing, you will need to design that data first.

A good pre-launch check is this: if every point on the map can be represented as a separate WordPress post with a title, address, coordinates, and a card in the listing, FacetWP Map is a good fit. If a point exists only as a line inside an arbitrary block of text, the setup will become artificially complicated.

The legacy add-on and the new Map facet: why you need to understand the difference before installing

There is an important source of confusion around the FacetWP Map name. The old Map Facet existed as a separate add-on. In the current FacetWP branch, a new built-in Map facet has been introduced, while the legacy Map add-on remains available for sites that already use the older implementation and are not ready to change their code, settings, and integrations right away.

For a new project, the logic is simple: do not start with the legacy add-on, and use the new Map facet in the main FacetWP plugin if your installed version supports it. On an existing live site, you cannot just remove the add-on and expect everything to keep working unchanged. The documentation specifically warns about migration because the Google Maps integration, markers, clustering, Map ID, terminology, and some custom code have changed.

If you are launching the map for the first time

For a new directory page, use the new built-in Map facet as your reference point. That lowers the risk of building on an add-on that is no longer the main development path. In the admin panel, you still need to create a facet of type Map, choose the coordinate source, add the facet to the page, and connect it to the listing, but in this scenario you do not need the separate legacy add-on.

If the site already uses the legacy Map add-on

An existing site is best migrated using a separate plan: create a copy on staging, update FacetWP, check the current coordinate fields, disable the legacy add-on only in the test environment, recreate or update the Map facet, and test markers, Proximity, marker info windows, clustering, and any snippets. Pay especially close attention to custom markers, because the new implementation relies on Advanced Markers and different hooks.

Do not replace the legacy Map setup on a live site without a backup and a staging check. The problem may not show up right away: the map may load, but markers, popup content, clustering, or filtering by the map area may behave differently.

What to prepare before installation and initial setup

Preparing for FacetWP Map starts with data. The map can display only those posts that have coordinates in a format FacetWP understands. The documentation points to two main options: a single field containing a latitude, longitude pair, or separate latitude and longitude fields. In a real project, that data usually comes from an ACF Google Map field, Meta Box, a location import, an address geocoder, or manual coordinate entry.

The minimum required for a working map

Before installation, check not only that the plugin files are available, but also that the future directory has a clear structure. Without these pieces in place, the map turns into a series of random experiments.

• You have a post type or regular posts that need to appear in the directory.
• Each post has coordinates, not just a text address.
• It is clear which listing will be filtered: Listing Builder, an archive, a custom query, blocks, or a supported page builder.
• The page will contain only one FacetWP-enabled listing, because multiple active listings on the same page often break query detection.
• A Google Maps API key has been created and restricted, and the required APIs are enabled in Google Cloud Console.
• It is clear whether you need a Proximity facet for radius search, or whether markers and standard filters are enough.

Why it is better not to leave addresses as text only

Visitors see an address as a readable string, but the map works with coordinates. If your posts contain only something like "New York, Fifth Avenue," the system still has to convert that address into latitude and longitude. You can do that through a separate geocoder or a map field, but the result still needs to end up in a custom field that FacetWP can index and use in the Map facet.

If coordinates are imported from an external table, check the decimal format, the order of values, and the absence of extra characters. Problems like swapped latitude and longitude, a comma used as a decimal separator, or empty values in some posts lead to a strange map: markers appear in the wrong place, some points disappear, and the fallback center may land in the ocean or show the entire globe.

Installation and the first validation check in WordPress

Installing FacetWP Map depends on which path you chose: the legacy add-on for an existing site, or the new built-in Map facet for a current project. In both cases, the core FacetWP plugin must be active, and the page must contain a listing plus a facet shortcode or widget.

General installation sequence

1. Install and activate the main FacetWP plugin in the standard way through Plugins and ZIP upload.
2. If you maintain an older site that already uses the legacy Map add-on, do not remove it before migration testing.
3. For a new project, create or verify the listing in Settings > FacetWP, then create a facet of type Map.
4. Select the coordinate source in the Map facet settings.
5. Add the listing and the Map facet to the same page using a shortcode, block, page builder widget, or PHP call.
6. Click Re-index after creating or changing facets and data sources.
7. Open the page without cache and check the map, markers, listing, and browser console.

Shortcode structure for a simple page

If you use Listing Builder, a basic page can contain a listing and several facets. The names in this example are placeholders: the technical names must match what you created in the FacetWP admin panel.

[facetwp facet="search"]
[facetwp facet="service_type"]
[facetwp facet="location_map"]
[facetwp template="stores_listing"]

This order is not the only valid one. What matters more is that the page has one filterable listing, and all facets belong to it. If you use Elementor, Bricks, Beaver Builder, or another supported approach, the logic stays the same: the map and the listing must live in the same FacetWP context.

Coordinates, the listing, and the index: the three foundations of a working map

The most common mistake in map setup is treating the Map facet as an independent widget. In reality, FacetWP builds the result through the index and the listing. The index stores facet values for posts, the listing defines the set of posts, and the Map facet visualizes the posts with coordinates and can filter the listing by the visible map area.

How to choose the data source for markers

In the Data source setting, choose the field that stores the latitude or the coordinate pair. If latitude and longitude are stored in separate fields, specify the latitude field as the main source and the longitude field in the Longitude setting. If you use a field that stores an array or a more complex structure, review the ACF or Meta Box integration documentation and make sure FacetWP is actually indexing the value you need.

If a post has multiple addresses or branches, you need a separate approach. The FacetWP documentation covers scenarios with multiple sources or repeater fields, but it is better to plan that in advance. If you simply dump several coordinates into one text field without a clear structure, the map may not generate the markers you expect.

Why re-indexing is mandatory

FacetWP does not rescan all custom fields from scratch every time a visitor clicks something. It uses its own index table for fast search and filtering. That is why after adding a Map facet, changing the coordinate source, importing locations, fixing addresses, or changing custom field values, you need to run Re-index. Without it, the map may show old points or fail to show new ones.

A quick check after indexing: open a few posts, compare the coordinates in the custom fields, then verify that those same posts appear in the listing and receive markers on the map. If the listing shows a post but the marker is missing, the issue is usually with the coordinates or the Map facet data source.

One dynamic listing per page

FacetWP supports different ways of outputting a listing, but for a filterable page the rule is strict: there should be only one active FacetWP-enabled listing. Additional blocks with similar cards can be static, but if the page has two dynamic listings with the facetwp-template class, FacetWP may select the wrong query or trigger an auto-detection error.

On a map page, this becomes especially obvious. The map is built from one result set, and visually the user expects the list next to the map to show those same items. If there are multiple queries, the map and the cards can drift apart: the marker belongs to one set, while the list belongs to another.

Configuring the Map facet after installation

It is better to work through Map facet settings not mechanically from top to bottom, but as a chain: data, map behavior, marker display, performance, and validation. That makes it easier to understand what each parameter changes and how to roll it back if the result is not right.

Google Maps API key

Map and Proximity facets require a valid Google Maps API key. In Google Cloud Console, you would usually enable the Maps JavaScript API, and for Proximity and address autocomplete also verify Geocoding API and Places API (New) depending on the mode you use. The key should be restricted by site and allowed APIs so it is less likely to be used unintentionally elsewhere.

After adding the key, use the built-in Google API check in FacetWP settings if it is available in your version. If the map shows This page can't load Google Maps correctly, do not start changing FacetWP settings at random. Open the browser console and Google Cloud Console first: most often the cause is an invalid key, an API that was not enabled, a referrer restriction, disabled billing for the project, or a conflict between the legacy and new Places API.

Map ID and cloud-based styling

In the new Map facet implementation, the old JSON map style approach has been replaced with cloud-based styling through Google Map ID. A Map ID is not required for a basic map, but you do need it if you want to control map styling, rendering type, or related options in Google Cloud Console. If the site previously relied on an imported JSON map design, you should check in advance how that style translates into the new system.

A safe approach is this: first get the map working without a custom Map ID, then add the Map ID and check rendering, styling, zoom, markers, Proximity, and mobile behavior. If the map starts looking different or warnings appear after adding the Map ID, temporarily remove the Map ID and return to the base setup.

Marker clustering and overlapping markers

Marker clustering is useful when you have many markers or when they are concentrated in one region. Instead of seeing dozens of points piled on top of each other, the user sees clusters with a marker count. On a large directory, that improves readability and reduces visual noise. When coordinates are extremely close together, Overlapping Marker Spiderfier can also help: after zooming in, markers can spread apart so the user can select the right one.

Do not enable clustering just because it looks modern. On a small directory with ten points, it can get in the way: visitors expect to see the individual branches immediately. On a large directory, by contrast, a map without clustering quickly becomes hard to read.

Marker limit, pagination, and Load more

The Marker limit setting determines whether markers are shown for all matching results or only for the current results page. The documentation notes an important limitation: the "current page results" option works with a Pager facet of type Page numbers, but not with Load more. That matters when you are designing the directory interface.

If users see the map next to the list and expect the markers to match only the visible cards, current page results may be more convenient. If the map is meant to show the full current result set regardless of pagination, it makes more sense to display all matching markers. For large directories, this decision should be tested against real data, because a map with hundreds of markers and heavy info windows can slow the page down.

Info window content and AJAX loading

The marker info window should answer one simple question: "What is this point, and where do I go next?" Usually a title, address, one short detail, and a link to the post are enough. If you place a large card, gallery, form, or long description into the popup, the map becomes heavy and awkward to use. For a large number of markers, consider Info window ajax loading: the window content will load on click instead of being rendered up front for every point.

Map height and responsiveness

The map will not display properly if its container has no defined height. In the Map width / height setting, you can specify dimensions, but in a responsive theme it is often more convenient to define the height with CSS. This is a safe visual adjustment: it does not change the filtering logic and is easy to roll back.

Add the CSS to a child theme, a safe theme CSS area, or a trusted snippet plugin. Do not place it in WordPress core files or FacetWP files.

.facetwp-type-map {
  min-height: 460px;
}

@media (max-width: 768px) {
  .facetwp-type-map {
    min-height: 360px;
  }
}

After adding the CSS, check the page on a desktop screen and a mobile device. If the map shows gray bands or is zoomed out too far, go back to the minimum zoom and fallback center settings. If the CSS does not work for your layout, remove the snippet or restore the previous height.

Connecting the Map facet, Proximity, and map area filtering

The strongest part of FacetWP Map reveals itself not in a standalone map, but in combination with other facets. The Proximity facet adds radius search based on an entered address or the user's detected location. Standard facets filter by post type, service, category, or price. And enabling filtering by the visible map area lets visitors narrow results by moving the map.

How Proximity works together with the map

The user enters an address or uses the location detection button, selects a radius, and FacetWP returns posts within that radius. The map automatically adjusts its viewport to the locations it found. When Proximity is in use, a separate search-center marker appears on the map, and that marker can be configured or disabled through the Map/Proximity documentation.

Do not promise absolute accuracy from location detection. The Browser Geolocation API may determine an approximate position by IP or request more precise data from the browser, but the user can deny access, be behind a VPN, or receive an imprecise center point. Because of that, the interface should let people correct the address manually.

When to enable viewport filtering

Filtering through the current map area is useful for directories where users naturally "explore an area": real estate, attractions, local services, events, parking, branches. Once Enable map filtering is turned on, the user moves the map and the listing updates based on the coordinates inside the visible area.

For a store finder focused on the nearest location, viewport filtering may be less intuitive than a Proximity radius search. Visitors are more likely to enter an address and see the closest branches than to move the map manually. In that case, map-area filtering can still be available, but it should not be the main search method.

Practical application ideas

The same settings can be turned into very different interfaces. The key is to start from the user's goal, not from the idea of showing a map at any cost.

• Store locator. The user's goal is to find the nearest branch. Use "Store" posts, coordinates, a Proximity facet, service categories, and a short info window with the address.
• Real estate. The goal is to compare properties in an area. Use the map next to the listing, filters for price and property type, clustering, and a tidy popup with the key details.
• Events or places. The goal is to explore a city or region. Categories, dates, viewport filtering, and a fallback center for the target city work well here.
• Service network. The goal is to see where a specific service is available. Filter by service, brand, or support type, and show only the information in the popup that helps the user choose a location.

Practical example: a branch directory page with a map and radius search

Let us look at a realistic scenario: a company site has multiple branches, each with an address, coordinates, a list of services, and a detail page. You need to build a page where visitors choose a service, enter a city or address, set a radius, and see a list of branches with markers on the map.

Goal

Create a "Branches" page where the listing shows branch cards, the Map facet displays those same branches on the map, the Proximity facet handles radius search, and a standard facet filters by service. The user should always see a consistent result: if the list narrows down to three branches, the map should also show those same three points or the corresponding clusters.

Preparation

• Create a store post type, or use an existing type if branches are already stored in WordPress.
• Add fields for the address, latitude, longitude, and services. For services, a taxonomy or repeater field with a clear structure is usually the better choice.
• Fill in coordinates for at least several test posts.
• Create a Listing Builder listing with a branch card: title, address, short list of services, and a link to the page.
• Create the facets: Map, Proximity, for example service_type, and Reset if needed.

Configuration steps

1. In Settings > FacetWP > Listings, create the branch listing and make sure it outputs only the required post type.
2. In the Map facet, choose the coordinate field as the Data source. If latitude and longitude are in separate fields, also fill in Longitude.
3. Set the map dimensions. For the initial check, use a fixed height such as 460px to rule out a zero-height container issue.
4. Enable Marker clustering if you have many test points or expect many real ones later.
5. Create the Proximity facet and configure the coordinate field and default radius if your setup calls for it.
6. Add the listing and facets to the page using shortcodes or widgets.
7. Run Re-index and open the page with caching disabled.

Validating the result

First, open the page with no filters selected. You should see the listing and the map with markers. Then select a service: both the list and the map should narrow down to the points where that service is available. After that, enter an address in Proximity and set a radius. The map should zoom toward the matching points, and the listing should show the branches within that radius.

What can go wrong

If the list filters but the map does not, check the coordinate source and re-indexing. If the map shows markers but Proximity cannot find the address, check the Google API and Places/Geocoding. If the map and list show different sets, check whether the page contains a second dynamic listing or a third-party widget that is intercepting the query.

Result validation, performance, and SEO details

After the initial setup, it is important to check not only whether "the map is visible," but also how it behaves in a real user scenario. FacetWP uses URL parameters for selected facets, AJAX to update results, and the Google Maps API for the map itself. So the overall quality of the result depends on the theme, caching, third-party optimizations, listing structure, and the volume of data.

On-page validation checklist

• The map loads on the public-facing site without a Google warning.
• The markers match the current listing, not every post on the site.
• Standard facets update both the listing and the map.
• Proximity accepts the address and radius correctly, if it is being used.
• Reset returns the page to a clear and predictable state.
• On mobile, the map has sufficient height, does not cover the filters, and does not break page scrolling.
• The browser console shows no Google Maps API errors, JavaScript conflicts, or FacetWP errors.

Caching, minification, and deferred script loading

FacetWP updates results through AJAX, and the map depends on JavaScript. That means aggressive optimization can break the loading order. FacetWP performance documentation explicitly notes that HTML minification and script deferring often cause problems, especially if they remove HTML comments that FacetWP needs to detect the listing.

A safe troubleshooting approach is this: temporarily disable caching, HTML minification, deferred script loading, and JavaScript combining on the test page. If the map and filters start working, re-enable those optimizations one at a time and add exceptions for FacetWP and Google Maps wherever your cache plugin supports them.

SEO and FacetWP URL parameters

FacetWP adds selected filters to the URL query string. That is useful for sharing links to a filtered result set, but it does not mean every filter combination should be indexed by search engines. For map-based and local directories, SEO is usually built not on endless parameter combinations, but on high-quality location pages, a clear directory structure, indexable landing pages for important cities or categories, and careful canonical or noindex handling for utility filters.

If the map is being used for a local business, do not expect SEO growth from FacetWP Map alone. The map improves navigation and the user journey, but search value comes from individual listing pages, unique content, address data, internal linking, and technically accessible URLs.

Why the map is not working and how to diagnose the issue

FacetWP Map troubleshooting is best handled from the foundation upward: first the listing, then the index, then the coordinates, then the Google API, and only after that JavaScript and caching. If you start by changing Map ID, clustering, and CSS all at once, it is easy to fix a symptom by accident and still miss the actual cause.

The map does not appear at all

Symptom: the page shows an empty area, the map does not load, or the container height is nearly zero. Possible causes include an incorrect height, a JavaScript error, a missing Map facet, caching that delays scripts, or a Google API that failed to load.

What to check: the presence of the Map facet shortcode or widget, the height of the .facetwp-type-map container, the browser console, a cache-free test, and whether the API key is valid.

How to fix it: assign a clear map height, temporarily disable script optimization, verify the Google API, and then restore settings one by one. If the issue started after adding a Map ID, temporarily remove the Map ID and test the base map.

The map is visible, but there are no markers

Symptom: Google Map loads, but no points appear, or the map falls back to the fallback center. Most often, FacetWP cannot see coordinates in the index, or the listing does not contain posts with valid coordinates.

What to check: the selected Data source, the separate Longitude field, coordinate format, the presence of posts in the listing, whether Re-index has been run, and whether there is only one dynamic listing on the page.

How to fix it: correct the coordinate format, re-index FacetWP, and manually check a few posts. If the coordinates live inside a complex ACF repeater, use the official approach for multiple locations instead of an arbitrary text field.

A Google Maps error appears

Symptom: the map reports This page can't load Google Maps correctly, and the console shows key, project, or API errors. This is not a listing issue, because the map is failing before Google Maps fully loads.

What to check: whether Maps JavaScript API is enabled, whether billing is connected to the project, whether the HTTP referrers match the domain, whether the required APIs are allowed, and whether there is a legacy/new conflict around the Places API when Proximity is used.

How to fix it: correct the settings in Google Cloud Console, restrict the key by domain and required APIs, then use the Google API test in FacetWP and reload the page without cache. If the key was changed, allow time for the changes to propagate and clear the cache.

Filters change the list, but the map stays the same

Symptom: the listing cards update, but the markers do not. Possible causes include the map being tied to a different listing, multiple dynamic templates on the page, JavaScript broken by optimization, or the Map facet not receiving the new result set.

What to check: the number of elements with the facetwp-template class, the placement of facets and the listing, the browser console, and behavior without cache or deferred script loading.

How to fix it: keep only one FacetWP-enabled listing, make extra blocks static, and disable the problematic JavaScript optimization or add exceptions.

Markers are there, but the page became slow

Symptom: the initial load or filtering becomes noticeably slow, especially on a directory with a large number of points. The cause may not be the map alone: a heavy listing, too many facets, large popups, inefficient theme queries, poor pagination choices, or simply too many markers on the map can all contribute.

What to check: the number of markers, info window content, the number of facets, pagination settings, Query Monitor, behavior without cache, and the actual timing of AJAX requests.

How to fix it: enable clustering, simplify the info window, use AJAX loading for popup content if needed, reduce the number of active facets, optimize the listing, and consider the FacetWP Caching add-on for high-traffic pages.

When FacetWP Map is the right choice

FacetWP Map is worth using when the map should be more than a decorative block and should instead function as part of a filterable WordPress directory. The product is especially effective when combined with Listing Builder, custom fields, the Proximity facet, categories, taxonomies, and a carefully configured Google Maps API.

If you are ready to prepare coordinates, verify the listing, re-index the data, and test the map without aggressive caching, FacetWP Map gives you a clear user flow: the visitor chooses filters, sees markers, narrows by area or radius, and moves to the right post. If all you need is a single static map or a fully ready-made store locator without the FacetWP logic, it is better to compare alternatives before implementation.

Once you have tested on staging and understand the difference between the legacy add-on and the new Map facet, you can download FacetWP Map and test it on a site copy with real coordinates, a real listing, and several typical filters.