Add location-aware geographical search to WP_Query. You can use it to power location-aware apps, such as showing a user results near them.

jhackett1

<p>A plugin to add location-aware geographical search to <a href="https://developer.wordpress.org/reference/classes/wp_query/" rel="nofollow ugc">WP_Query</a>.</p>
<p>You can use it to power location-aware apps, such as showing a user results near them.</p>
<h3>🔎 Using it in a query</h3>
<p>Adding a <code>geo_query</code> parameter to WP_Query will add a “distance” column to the returned results, provided they have the right metadata.</p>
<p>You can then display this in your templates.</p>
<p>You can use a location search parameter, which will be <a href="#geocoding" rel="nofollow ugc">geocoded</a> or directly provide latitude and longitude values:</p>
<pre><code>$query = new WP_Query(array(
    "geo_query" => array(
            "location" => "London"
    )
))

$query = new WP_Query(array(
    "geo_query" => array(
            "latitude" => -52.005,
            "longitude" => 0.005,
    )
))
</code></pre>
<p>Optionally, you can then filter by search radius.</p>
<p>By default, distances are given in miles. You can provide <code>"units" => "km"</code> if you need kilometres.</p>
<pre><code>$query = new WP_Query(array(
    "geo_query" => array(
            "latitude" => -52.005,
            "longitude" => 0.005,
            "radius" => 10
    )
))
</code></pre>
<p>Or order by nearness:</p>
<pre><code>$query = new WP_Query(array(
    "geo_query" => array(
            "latitude" => -52.005,
            "longitude" => 0.005
    ),
    "orderby" => "geo"
))
</code></pre>
<h3>Displaying distance in templates</h3>
<p>In a <code>WP_Query</code> loop that includes a <code>geo_query</code>, you can use two extra functions to show distance away:</p>
<ul>
<li><code>jhgs_get_the_distance(object $post)</code> – which returns a rounded integer for the distance away, similar to <code>get_the_title()</code></li>
<li>
<p><code>jhgs_the_distance(string $less_than_one, string $one, string $more_than_one)</code> – which displays an approximate human-readable string, similar to <code>the_title()</code></p>
<p>jhgs_the_distance will show one of three messages depending on whether the rounded distance is less than one, one, or greater than one. By default these are:</p>
</li>
<li>
<p>“Less than a mile away”</p>
</li>
<li>“About a mile away”</li>
<li>“About %s miles away”</li>
</ul>
<p>If you need to use different units or translations, can pass three <a href="https://www.php.net/manual/en/function.printf.php" rel="nofollow ugc">printf-formatted</a> strings to <code>jhgs_the_distance()</code> to override these messages. Put <code>%s</code> where you want the value.</p>
<p>If you need the <em>exact</em>, unrounded value, you can use <code>$post->distance</code>.</p>
<h3>Geocoding</h3>
<p><a href="https://nominatim.org/" rel="nofollow ugc">Nominatim</a>‘s service is used for geocoding location searches.</p>
<p>Using it is subject to an <a href="https://operations.osmfoundation.org/policies/nominatim/" rel="nofollow ugc">acceptable use policy</a> – if you use case will involve lots of API calls, you should replace it with a paid alternative, like <a href="https://developers.google.com/maps/documentation/geocoding/overview" rel="nofollow ugc">Google</a>‘s.</p>
<h3>📍 Populating latitude and longitude data</h3>
<p>It looks for two <a href="https://wordpress.org/support/article/custom-fields/" rel="ugc">custom field</a> values with the keys <code>latitude</code> and <code>longitude</code> on your posts.</p>
<p>It’s agnostic about how you supply this data. The simplest thing to do is type it in using WordPress’s built-in custom field editor.</p>
<p>You could also hook into the <code>save_post</code> action to populate meta whenever you create or change a post, by adding a snippet like this to your theme’s <code>functions.php</code>:</p>
<pre><code>function example_update_latlngs($post){
    $location = get_field("location", $post);
    if(isset($location)){
        update_post_meta($post, "longitude", $location["lng"]);
        update_post_meta($post, "latitude", $location["lat"]);
    }
}

add_action("save_post", "example_update_latlngs", 10, 3);
</code></pre>
<p>This example assumes you are using an <a href="https://www.advancedcustomfields.com/resources/google-map/" rel="nofollow ugc">ACF Google Map</a> field called “location”, but the data could come from anywhere, including a custom meta box you code yourself, so long as the post meta keys are right.</p>
<h3>Bulk-updating existing posts</h3>
<p>If you have many posts that you need to add longitude and latitude meta to in bulk, you could add something like this to <code>functions.php</code>, which will run on <a href="https://developer.wordpress.org/reference/hooks/after_switch_theme/" rel="nofollow ugc">theme activation</a>:</p>
<pre><code>function example_update_all_latlngs(){
    $query = new WP_Query(array(
        "posts_per_page" => -1
    ));
    foreach($query->get_posts() as $post){
        // Function from above
        example_update_latlngs($post);
    }
}

add_action('after_switch_theme', 'example_update_all_latlngs');
</code></pre>


Alternatives to WP Geo search

Top alternatives