In wpsolr, Geolocation search, also named proximity search or search by distance, consists of using the location of a visitor to improve the search results.

What is it ?

Imagine you are writing reviews of restaurants in your region (you’re living in France). It would be nice to show the restaurants close to your visitors, no ?

Well, with wpsolr, you can.

Basically, you just need to create a custom field on your review post type, and fill it with the latitude and longitude of the restaurant.

Easily done with wikipedia informations.

Then, you activate the Geolocation features of wpsolr, and that’s it. Wpsolr can now use the location of your visitor, with his agreement, to sort results by the closest restaurant reviews.

Description for a visitor

• (Optional) A visitor selects “search with distances” if it is configured (see wpsolr administrator setup below). If it is not configured, the next step applies directly.

  

• The visitor submits his search
• The visitor agrees, for once or for longer, to let the website know his location (this is asked by the browser, not by wpsolr). If the visitor does not agree, the search is performed without Geolocation, as usual.

  

• The visitor location, latitude and longitude, is added to the search parameters, and the search is started
• Wpsolr uses the location to perform a geolocation search, sorted and filtered by distance.

  

Activate the Geolocation Extension

This is your mandatory first step if you want to complete your geolocation setup.

Configure your Geolocation custom fields

Your location coordinates are probably contained in a custom field with a ‘lat,long’ format. If not, use our actions/filters to convert your coordinates format, or contact us to see what we can do for you.

To be treated as Geolocation fields, your custom field must be indexed, and searched, with a specific format in Apache Solr or Elasticsearch. For that, select a field type “LatLong”  as shown below (before indexing your data):

If your custom field is an ACF Google Map field type, you can use it too as shown below (you must activate and configure the ACF extension options first):

Use your Geolocation custom fields as a distance sort

Geolocation custom fields are sortable by default. The distance from each search result to the visitor (or any coordinates in the search url parameters) can be used to sort results.

You just have to add your Geolocation custom field to the sort fields. There is no difference with other ‘ordinary’ custom fields:

Select a default sort

You can select which sort to apply by default on geolocated searches, when none is selected by the user.

You can:
– Use the default sort used by all searches
– Override the default sort with another custom field (distance or not) when the search is localized

Create the text showing the distance in each search result

This is valid only for the Ajax template delivered with the plugin. To add the distance to your own theme’s search page template, follow the questions/answers at the end of this documentation.

You can decide how to show, or not to show at all, the distance to the visitor (or any other coordinates passed as url parameters) for every result.

Leave the field empty if you do not wish to show distance.

%1$s is replaced by the field label. %2$s is replaced by the distance. Use your theme/plugin .mo files or WPML string module to localize it.

Attach the Geolocation javascript to your own search form(s)

This option is for your theme’s search boxe(s). The Ajax default theme is already configured.

Enter a jQuery selector for your search box(es). The javascript will collect the visitor localization precisely when the search is submitted from the search box(es). Also, the submitted form is added the css class “wpsolr_geo_loading” while the browser is retrieving the visitor location. You can use this class to show some loading icon for instance.

Add a user agreement checkbox on your search form(s)

1. If you select this option, a checkbox will be added to the search form(s), wpsolr Ajax and your search form(s) defined above, asking the user to confirm his agreement to use his geolocation. If you do not select this option, the geolocation will be used without consent. (but the browser will ask anyway in both cases).
2. The user agreement checkbox is preselected, or not.
3. Text of the checkbox. Will be shown on the front-end (and translated in WPML/POLYLANG string modules if not empty. Else will show the localization translation).

Filter out results with no coordinates

If some of your post types does not contain geolocation coordinates, this option will filter them out from the results. It prevents showing messy wrong distances of 1000s of kilometers.

The browser does not ask visitors for their location ?

You should first check your browser javascript console logs, there are probably detailed explanations (unfortunately, the error is silent). But most recent browsers require websites to be protected by HTTPS to prompt visitors for their coordinates agreement.

How to add distance to your theme search results ?

WPSOLR adds a field ‘wpsolr_distance’ to the posts returned by the search. The field contains an array of distances, one by geolocalized custom field (you can have one, or more).

In your main loop, add code similar too:

<?php 
if ( ! empty( $post->wpsolr_distance ) ) {
foreach ( $post->wpsolr_distance as $field ) {
   echo sprintf( '%s km', $field->distance );
  } // foreach
} // if
?>