Justin Kruit

<p>Address Lookup field for ACF adds an address lookup field type to Advanced Custom Fields. Users can search for addresses directly within the editor, and the field returns structured address data including coordinates.</p>
<p>The plugin uses <a href="https://nominatim.openstreetmap.org/" rel="nofollow ugc">Nominatim (OpenStreetMap)</a> as the default lookup provider, and supports registering custom providers.</p>
<p>The plugin also includes support for the <a href="https://photon.komoot.io/" rel="nofollow ugc">Photon</a> geocoding provider out of the box. You can choose between Nominatim and Photon, or register your own providers.</p>
<h4>Features</h4>
<ul>
<li><strong>Live address search</strong> — AJAX-powered search as you type, using Select2.</li>
<li><strong>Structured data</strong> — Returns a normalized array with display name, coordinates (lat/lon), house number, road, city, state, postcode, and country.</li>
<li><strong>Country code filtering</strong> — Limit search results to specific countries.</li>
<li><strong>Language support</strong> — Set the preferred language for results.</li>
<li><strong>Extensible provider system</strong> — Register your own address lookup providers via the <code>address_lookup_for_acf/register_providers</code> action.</li>
<li><strong>REST API support</strong> — Field values are exposed in the REST API.</li>
<li><strong>Photon provider</strong> — Use the Photon geocoding service as an alternative to Nominatim.</li>
</ul>
<h4>Usage</h4>
<ol>
<li>Install and activate the plugin.</li>
<li>Create or edit an ACF field group.</li>
<li>Add a new field and select the <strong>Address</strong> field type.</li>
<li>Optionally configure country code filtering and language.</li>
<li>Use <code>get_field()</code> or <code>the_field()</code> in your templates — the value is returned as an associative array.</li>
</ol>
<h4>Template example</h4>
<pre><code>$address = get_field('my_address_field');
</code></pre>
<p>The returned array has the following structure:</p>
<pre><code>[
    'display_name'  => 'Example Street 1, City, Country',
    'coordinates'   => ['lat' => '52.370216', 'lon' => '4.895168'],
    'house_number'  => '1',
    'street'        => 'Example Street',
    'city'          => 'City',
    'state'         => 'State',
    'postcode'      => '1234 AB',
    'country'       => 'Country',
]
</code></pre>
<h4>Custom providers</h4>
<p>You can register a custom address lookup provider by hooking into the <code>jk_address_lookup_for_acf/register_providers</code> action:</p>
<pre><code>add_action('jk_address_lookup_for_acf/register_providers', function ($registry) {
    $registry->register(new MyCustomProvider());
});
</code></pre>
<p>Your provider must extend <code>justinkruit\AddressLookupForAcf\Providers\AbstractProvider</code> and implement the <code>name()</code>, <code>label()</code>, and <code>search()</code> methods.</p>
<h4>Filters</h4>
<ul>
<li><code>jk_address_lookup_for_acf/nominatim_url</code> — Override the Nominatim API base URL (e.g. to use a self-hosted instance).</li>
<li><code>jk_address_lookup_for_acf/nominatim_url_vars</code> — Modify the query parameters sent to the Nominatim API.</li>
<li><code>jk_address_lookup_for_acf/photon_url</code> — Override the Photon API base URL (e.g. to use a self-hosted instance).</li>
<li><code>jk_address_lookup_for_acf/photon_url_vars</code> — Modify the query parameters sent to the Photon API.</li>
</ul>
<p>Both filters also support ACF’s field-specific variations by type, name, and key.</p>
<h3>External services</h3>
<p>This plugin connects to third-party external services to perform address lookups. No data is sent automatically; requests are only made when an admin user actively searches for an address in the ACF field editor. The search query text is sent to the configured provider’s API.</p>
<p>Below is a list of each provider, what additional data is sent, how to override the API URL, and links to their terms and privacy policies.</p>
<h4>Nominatim (OpenStreetMap)</h4>
<p>Service: <a href="https://nominatim.openstreetmap.org/" rel="nofollow ugc">Nominatim</a> by the OpenStreetMap Foundation: used for geocoding address searches.</p>
<p>Additional data sent: configured country code(s) and language preference (if set in the field settings).</p>
<p>Override URL: use the <code>jk_address_lookup_for_acf/nominatim_url</code> filter to point to a self-hosted instance.</p>
<p>Policies:</p>
<ul>
<li><a href="https://operations.osmfoundation.org/policies/nominatim/" rel="nofollow ugc">Nominatim Usage Policy</a></li>
<li><a href="https://osmfoundation.org/wiki/Terms_of_Use" rel="nofollow ugc">OpenStreetMap Foundation Terms of Use</a></li>
<li><a href="https://osmfoundation.org/wiki/Privacy_Policy" rel="nofollow ugc">OpenStreetMap Foundation Privacy Policy</a></li>
</ul>
<h4>Photon</h4>
<p>Service: <a href="https://photon.komoot.io/" rel="nofollow ugc">Photon</a> by Komoot: used for geocoding address searches, powered by OpenStreetMap data.</p>
<p>Additional data sent: configured country code(s) and language preference (if set in the field settings).</p>
<p>Override URL: use the <code>jk_address_lookup_for_acf/photon_url</code> filter to point to a self-hosted instance.</p>
<p>Policies:</p>
<ul>
<li><a href="https://photon.komoot.io/" rel="nofollow ugc">Photon Terms of Service</a></li>
<li><a href="https://www.komoot.com/privacy" rel="nofollow ugc">Komoot Privacy Policy</a></li>
</ul>


Address Lookup field for ACF

ACF field integration for address lookup providers.

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>


WP Geo search

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.

Address Lookup field for ACF vs WP Geo search