Map

This add-on adds a Map facet type, which works just like any other facet type. The generated map displays geocoded results and can also filter results by showing only results within the map viewport.

Combine a Map facet with a Proximity facet

A Map facet can be combined well with a Proximity facet, which returns results within a chosen radius from a specified location.

When a location and radius are set (or changed) with the Proximity facet, the map will automatically zoom in or out, showing the locations that are within the radius of the set location. It will also display a marker pin at the set location (which can be customized or disabled).

Available options

Data source

The Data source should be a custom field containing a comma-separated latitude, longitude.

You can also use separate custom fields for the latitude and longitude, see the available options.

Note: it is also possible to index multiple locations for a post, by using a multi-value custom field, like a repeater field or for example a simple checkboxes/dropdown field.

Other data sources

The following plugins and themes offer dedicated custom fields for latitude and longitude that can be used as data sources for the Map facet. Click the links for specific instructions on using these fields:

• Advanced Custom Fields
• WP Job Manager
• Listify theme
• Listable theme

Google Maps API key

Generate a Google Maps API key

The Map facet requires a valid Google Maps API key. To generate a key, you have to log into Google Cloud Console, set up a project, add an API key under API's & Services > Credentials, and enable the following three API services for the key:

1. Maps JavaScript API: required for the Map / Proximity facets to work
2. Geocoding API: required for the Proximity facet’s “Locate me” button
3. Places API: required for the Proximity facet’s autocomplete box

To be able to use the key, you also need to set up a Billing Account in Google Cloud Console, and add your project to it. You will need a creditcard to set up billing. There is a free monthly credit of $200, which amounts to 28000+ map loads per month.

Add the Google Maps API key to FacetWP

After generating an API key, add it to: Settings > FacetWP > Settings > Google Maps API key.
Both the Map facet and the Proximity facet use this key.

Besides in FacetWP’s settings, the API key can also be set with a constant in wp-config.php:

define( 'GMAPS_API_KEY', 'your-api-key' ); 

Or with a hook in your (child) theme’s functions.php:

add_filter( 'facetwp_gmaps_api_key', function( $api_key) {
    return 'your-api-key';
});

Add the Google Maps API key to Advanced Custom Fields

If you are using the Advanced Custom Fields Google Map field as the data source, make sure you pass the same Google Maps API key into ACF. ACF needs the Google Maps API in the backend to geolocate the address entered for each post.

Add the Google Maps API key to Listify, Listable, WP Job Manager

If you are using Listify theme, Listable theme and/or the WP Job Manager plugin, make sure to also add the Google Maps API key to:
(Job) Listings > Settings > Google Maps API Key

The Listify theme itself has a second settings to enter the Google Maps API key, at:
Appearance > Customize > Listings > Map settings

Add marker content

The “Marker content” setting can be used to create the content of the info window popup that displays when a marker is selected. The setting’s field accepts HTML and PHP code.

The following example outputs the title, link, and excerpt:

<h3>
  <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
    <?php the_title(); ?>
  </a>
</h3>
<?php the_excerpt(); ?>

The “Enable map filtering” button

When the “map filtering” is enabled with the button, the results will be refreshed whenever the map is zoomed or panned. So after clicking the button, then zooming or panning the map, only results within the map’s viewport are shown in the filtered listing. You can see this in action in the State Parks map demo.

To understand how map filtering works, you can think of the rectangular viewport of the map acting as a facet filter. When map filtering is enabled, you’ll see that the map viewport’s bottom-left, and top-right lat/lng coordinates are present in the URL variables as the active values of the map facet. These coordinates are updated when panning or zooming the map, just like any other facet updates its values when making selections.

Hide the “Enable map filtering” button

Currently, there is no setting to disable the ‘Enable map filtering’ button/functionality. If you don’t want this button to show, you can hide the button with CSS:

.facetwp-map-filtering { 
    display: none; 
}

Change the “Enable map filtering” button text

The text of the “Enable map filtering” button can be changed with this code:

add_filter( 'gettext', function ( $translated_text, $untranslated_text, $domain ) {
    if ( $translated_text == 'Enable map filtering' && 'facetwp-map-facet' == $domain ) {
        $translated_text = 'Your button text';
    }
    return $translated_text;
}, 10, 3 );

Enable map filtering on load of the map

It’s possible to enable map filtering by default on load of the map, with the following code.

However, be aware that having map filtering enabled will prevent other facets – like a Proximity facet – from automatically zooming or panning the map. This can be confusing for users, even more so if it is unclear that map filtering is enabled. So it’s not a good idea to combine this with hiding the “Enable map filtering” button.

<?php
    add_action( 'wp_footer', function () {
    ?>
    <script>
        (function ($) {
            $(document).on('facetwp-loaded', function () {
                if ('undefined' === typeof FWP_MAP) {
                    return;
                }
                var filterButton = $(".facetwp-map-filtering");
                if (!filterButton.hasClass('enabled') && 'undefined' == typeof FWP_MAP.enableFiltering) {
                    filterButton.text(FWP_JSON['map']['resetText']);
                    FWP_MAP.is_filtering = true;
                    filterButton.addClass('enabled');
                    FWP_MAP.enableFiltering = true;
                }
            });
        })(jQuery);
    </script>
    <?php
}, 100 );

Common issues with “Enable map filtering”

If the “Enable map filtering” button is not working, make sure you have not disabled auto_refresh. That also disables the map from auto-refreshing.

Advanced map customizations

Don’t miss our page with advanced map customizations, among which:

• Customize the map region and language localization, or add URL parameters
• Change the map type
• Customize the map controls
• Customize the map style/design
• Set a custom zoom level or location/center
• Customize the marker pins
• Customize marker clustering behavior
• Customize Overlapping Marker Spiderfier behavior
• How to use advanced map marker hooks and functions

See also

• Advanced Map customizations
• The Proximity facet type
• The Pager + Load more facet type
• Using FacetWP with Advanced Custom Fields
• Using FacetWP with WP Job Manager
• Using FacetWP with the Listify theme
• Using FacetWP with the Listable theme
• How to Disable Facet Auto-Refresh and Add a Submit Button
• State parks Map/Proximity facet demo