Introducing the new Proximity and Map facets in FacetWP v4.4

To bring FacetWP up-to-date with the latest Google Maps developments, FacetWP v4.4 (released on April 23, 2025) significantly changes how Google Maps and the needed Google APIs are integrated.

These changes affect the Proximity facet and the Map facet.

This page describes what has changed, why we did this and what you need to do. It also explains why you should consider migrating to the new facet types, how to do that, and what new documentation is available.

What has changed?

A lot. To prevent broken sites from a plugin update containing all these changes, we decided to split the Proximity and Map facet types into two versions.

Both facet types now have a “legacy” version without the changes, and a “new” version with the changes. If you are an existing user, and you update to FacetWP v4.4+, you will automatically still be using the legacy facets, and can migrate to the new versions at a time of your convenience.

Two Proximity facet types

In FacetWP v4.4 and newer, you can now choose between two Proximity facet types:

• The Legacy Proximity facet – uses Google’s legacy “Places API”.
• The new Proximity facet – uses Google’s “Places API (New)“.

The Proximity facet can be switched with the new “Use Legacy Proximity facet” setting located in FacetWP > Settings. But before touching that switch, read about how to migrate.

Two Map facet types

In FacetWP v4.4 and newer, there are also two Map facet types:

• The Legacy Map facet – Needs the Map facet add-on installed.

• 

  The new Map facet – Built into the main FacetWP plugin. Needs the Map facet add-on not installed.

The new Map facet is now built into the main FacetWP plugin. It can be enabled by deactivating the Legacy Map facet add-on. But before you do that, read about how to migrate. Because there are many potentially breaking changes, especially if you have many code customizations.

With this split, the Map facet add-on has reached its last version ever (v1.2) and will not be updated anymore.

New and changed features

In FacetWP v4.4 and newer, if the new Proximity and Map facets are used, the following features are new or changed:

• “Places API (New) ” – Replaces Google’s legacy “Places API”, which cannot be enabled anymore after March 1, 2025. See the API key documentation. Places API (New) loads asynchronously, offering better performance. For high traffic sites, it may be useful to know that it uses a more cost-effective new pricing model, as noted in Google’s migration overview page.
• New “Use Legacy Proximity facet” setting – This new setting, located in FacetWP > Settings, determines if the Legacy Proximity facet is used or not. The setting can also be set or overridden with a hook.
• New Google API check setting – A new Google API test feature was added that lets you test the correct connection to the needed APIs.
• Asynchronous loading of Maps JavaScript API – New async map loading, for improved performance. Replaces the the legacy (synchronous) direct script loading tag that generates a warning in the browser console. Without the legacy Map facet add-on installed, a page with only a Proximity facet will load the Maps JavaScript API asynchronously when the “Use Legacy Proximity” setting is disabled and non-asynchronously when it is enabled. If the page also (or only) has a Map facet, the Maps JavaScript API will always load asynchronously, regardless of the “Use Legacy Proximity” setting. If the legacy Map facet add-on is active, the Maps JavaScript API will always load non-asynchronously.
• Advanced Markers – Unleash your creativity with highly customizable marker pins, or even use arbitrary HTML for markers. See our new Customize Advanced Markers page for all info. Advanced Markers replace legacy markers, which are already deprecated since February 21st, 2024 and generate a warning in the browser console.
• New marker clustering library – New, highly customizable official Google Maps JavaScript MarkerClusterer library, supporting Advanced Markers. See the new documentation.
• Updated Open Marker Spiderfier library – Updated OMS library, supporting Advanced Markers. See the new documentation.
• Map IDs and vector map rendering – Manage your map settings and styling in the Google Cloud Console with a Map ID. You can now choose a map rendering type (raster or vector). The new vector rendering type makes maps render very fast and snappy. Vector maps also enable new features like map tilt and rotation and 3D map features.
• Cloud-based map styling – Style your maps in the Google Cloud Console, based on their Map ID. Unfortunately, there is a drawback: no more (importable) JSON-based map styling.
• New Map facet settings – The Map facet has a new (optional) “Map ID” setting. The “Map design” setting is removed. The legacy “Map design” setting has been replaced with cloud-based map styling based on Map ID.
• “Marker content” terminology, variables and setting names – “Marker content” now refers to the content of the Advanced Marker (the pin or HTML marker itself). Before, this referred to the marker info window content. The new Map facet settings have been renamed to reflect this change.
• New PHP and JS marker hooks – There are several new PHP and JavaScript hooks available for styling and customizing behavior of Advanced Markers.
• New PHP map parameters hook – There is a new facetwp_gmaps_params hook to set the map parameters like the API key and API version to load. It can also be used to set the map language and region and preload Map IDs for performance.
• New PHP map loading hook – There is a new facetwp_load_gmaps hook to disable loading of FacetWP’s instance of the Google Maps JavaScript API, if you use another way of loading the Google Maps API.
• Customization snippets – Because of all changes mentioned above, many of the documented legacy customization snippets will not work anymore and will need to be updated to their new equivalents. But don’t worry, we made sure there is a replacement for all relevant snippets, and each one that needs updating has a purple migration banner with instructions. See the migration instructions below.
• Google free pricing tier changes – This has nothing to do with FacetWP, but coincides with above other changes. Before March 1, 2025, Google offered a free monthly credit of $200. On March 1, 2025, this has changed to a free monthly usage threshold of 10K requests for each product. Check the pricing page and the Pricing Calculator to estimate your costs.

Why all these changes? And why now?

The main reason for making all these changes now, is that the Google Maps Platform itself changed a number of things, a few with hard deadlines. Some of these changes were already resulting in deprecation warnings in the browser console for a long time (some for over a year). Some of the new features required other changes:

• New way of loading Maps JavaScript API
  FacetWP was using a legacy (synchronous) direct script loading tag to load the Maps JavaScript API. This caused a warning in the browser console about “suboptimal performance”, triggering questions in support. The new asynchronous Dynamic Library Import way of loading already existed for a while, and is recommended because it is much better for performance.
• “Places” API deprecated
  Starting on March 1, 2025, the Google “Places API”, that FacetWP uses in the Proximity facet, has so-called legacy status and is replaced by the new, asynchronously loading “Places API (New)”. This means that from this date onward, new API users can no longer enable the legacy “Places API” in the Google Cloud Console. Existing API users who were already using the “Places API” before March 1, can continue to use it at the time of writing. This also means that new FacetWP or Proximity facet users will no longer be able to use FacetWP’s Legacy Proximity facet after March 1, 2025.
• Legacy markers deprecated
  On February 21st, 2024, Google deprecated legacy markers. This was causing a warning in the browser console already for over a year. At the time of writing (March 2025), legacy markers are not yet scheduled to be discontinued, but using the new Advanced Markers is encouraged. The switch to Advanced Markers is an exciting one though, because markers can now be highly customizable marker pins, but can also consist of HTML. This means that anything you can come up with for a marker, you can now create, very easily.
• External libraries incompatible with Advanced Markers
  Moving FacetWP from legacy markers to Advanced Markers meant updating two libraries that FacetWP uses, to versions that work with Advanced Markers. For the Overlapping Marker Spiderfier library, this meant a relatively simple update. But we had to switch the marker clustering library that FacetWP was using to the official Google Maps JavaScript MarkerClusterer library, which supports Advanced Markers. This change is a good thing, because this new library is much better and more flexible than the old one. Cluster icons are now Advanced Markers too, gaining all their new exciting ways of customization. This makes it easy to create customized cluster icons.
• Advanced Markers, Map IDs, and map styling
  Advanced Markers could only be implemented using Google’s new “Map ID” feature. Map IDs make it possible to manage maps from the Google Cloud Console. Currently, you can do two things in the new “Map Management” section: set a map rendering type (raster or vector), and give your map a “Map Style”. This last change has implications for how maps are styled: this is now only possible with cloud-based map styling, in the Google Cloud Console. Unfortunately, this change also meant no more “Map design” setting, or importable (third-party or self-created) JSON-based map styling. This is a regrettable decision by Google. But it’s not entirely unthinkable they may re-introduce importable/exportable styles in the future, as a lot of users will be frustrated by this.

We decided to tackle all of these changes in one big update, so that FacetWP’s Google Maps integration is now entirely up-to-date again with the latest Google Maps developments.

What do I need to do?

New Proximity/Map facet users

If you are a new FacetWP user (starting at v4.4 or later), or if you want to start using the Proximity and/or Map facet for the first time, there is nothing to migrate. Just start using the new facet types, as documented on the Proximity facet and Map facet pages. Don’t install the Map facet add-on, as this will switch you back to the Legacy Map facet.

Existing Proximity/Map facet users

As an existing Proximity/Map facet user, after updating to FacetWP v4.4+, you will still automatically be using the legacy Proximity and Map facet versions, which remain fully working, including any custom code snippets you may be using.

You can decide to migrate to the new versions at a time of your convenience. While migrating to the new version is recommended, it is completely optional at this point in time, and can be postponed (but not indefinitely).

Migrating to the new facet versions is easy, if you have no code customizations (meaning code snippets from any of the Legacy documentation pages you have in your functions.php or code snippets plugin). To migrate the Proximity facet you only need to disable the “Use Legacy Proximity facet” setting, and switch your site to the “Places API (New)” in the Google Cloud Console. For the Map facet, you only need to deactivate the Map facet add-on.

However, many documented custom code snippets will not work anymore after migration. If you are using any of these, we have you covered with detailed migration info on each legacy snippet, but going through them all one by one could cost considerable time and effort, depending on how many you have. Make sure to plan accordingly.

Can I choose not to migrate?

Yes, you can decide to keep using both legacy facet versions for now. But, to future-proof your site, we recommend taking the time to migrate to the new Proximity and Map facets. Consider that eventually, you’ll need to migrate anyway, when Google inevitably discontinues the below-mentioned features. You may want to prevent a forced and stressful migration at the moment this happens in the future.

We will keep the legacy versions available as long as they keep working, which will not be indefinitely. The Legacy Proximity facet will keep working until Google decides to discontinue the legacy “Places API”. The Legacy Map facet (with the Map facet add-on installed) will keep working until Google discontinues either the (synchronous) direct script loading tag (which already shows a warning in the browser console), or legacy markers (which are already deprecated since February 21st, 2024).

When the mentioned features will be discontinued exactly is unknown at the time of writing. We recommend keeping an eye on Google’s legacy and deprecations pages.

Why should I consider migrating?

Because eventually, you’ll need to migrate anyway: when Google discontinues Places API, legacy markers, or the legacy (synchronous) direct script loading tag, at an unknown point in the future.

On the positive side: migrating to the new versions will give you access to all new features mentioned above. Here is a shortlist of the things we are most excited about:

• Much better performance because of async Map loading, async Places API loading, vector maps, and preloading of Map IDs, to name a few things.
• The new Places API (New) has much better options to localize or optimize the places suggested in the Proximity facet’s dropdown. For example to limit them to countries or place types. Or to bias or restrict them to a specific area.
• Vector maps are very snappy, and enable map tilt and rotation, map height, 3D map features, and more.
• Cloud-based map styling makes it possible to create your own map styles online and attach them to any map on any site, based on Map ID.

• 

  Advanced Markers are awesome. You can style Google’s default marker pins in many creative ways, even using images, SVGs, or icon fonts within the pin itself. Or you can use HTML for markers, making it possible to create anything you can come up with. You can also change the marker design based on any post data. All of this can be done with PHP or JS hooks. There are also many new ways to customize marker behavior, like animation.

• 

  The new marker clustering library is also amazing. Cluster icons are now Advanced Markers, so all of the above creative goodness applies to them too. Custom cluster rendering makes it possible to create your own cluster icon design and apply your own logic for how clusters look based on the number of markers or the cluster location.

• The same applies to the Overlapping Marker Spiderfier feature: Advanced Marker design can easily be customized based on whether markers are (un)spiderfiable and/or spiderfied.

How do I migrate?

How to migrate depends on your exact situation. Make sure to carefully read, and follow the steps outlined in these migration guides:

• Migrate the Legacy Proximity facet to the new Proximity facet.
• Migrate the Legacy Map facet to the new Map facet.

Available documentation

The Map and Proximity facets now have two sets of documentation: the new current one, and the “Legacy” documentation:

New documentation

For FacetWP v4.4 or newer, without the Map facet add-on installed, use:

• Map facet
  • Advanced map customizations
    • Customize Advanced Markers
    • Customize marker clustering
    • Customize Overlapping Marker Spiderfier

For FacetWP version 4.4 or newer, with the “Use Legacy Proximity facet” setting disabled, use:

• Proximity facet

Legacy documentation

For FacetWP (any version), with the Map facet add-on (any version) installed, use the following pages. Where relevant we added purple banners with migration information about what changed, with links to the relevant new documentation sections and snippets. If a legacy snippet does not have a purple banner, you can safely assume it still works and does not need adapting.

• Map facet (legacy)
  • Advanced map customizations (legacy)
    • Customize marker pins (legacy)
    • Customize marker clustering (legacy)
    • Customize Overlapping Marker Spiderfier (legacy)

For FacetWP versions older than v4.4, and for version 4.4 or newer with the “Use Legacy Proximity facet” setting enabled, use:

• Proximity facet (legacy)