Proximity Search

There are many scenarios where you may want to conduct a proximity search...

A store locator - See which franchise locations are nearest to a customer.
A real estate tool - Show houses or apartments within a given search area.
A general resource finder - Display a list of parks, playgrounds, or schools nearby.

Give your users the ability to find the nearest location. You can conduct a proximity search to get the distance to each location, and sort them from nearest to farthest.

Twig
PHP

{# Conduct a proximity search #}
{% set entries = craft.entries.myAddressField(options).orderBy('distance').all() %}

TL;DR

Add these two parameters to an otherwise normal Element Query...

    .myAddressField(options)
    .orderBy('distance')

This turns a normal query into a proximity search. The two parameters will respectively...

Conduct a proximity search with the specified options.
Sort the results from nearest to farthest.

You can specify whatever options are necessary in order to further configure the proximity search. To see what's possible, check out the full list of options...

# Simple Example

# Find all locations within 50 miles of Seattle

Twig
PHP

{# example.com/search?near=Seattle #}

{# Get proximity search target from user query #}
{% set target = craft.app.request.getParam('near') ?? null %}

{# Configure the proximity search #}
{% set options = {
    'target': target,
    'range': 50
} %}

{# Run the proximity search #}
{% set entries = craft.entries
    .section('locations')
    .myAddressField(options)
    .orderBy('distance')
    .all() %}

Just as in a typical element query, the results will be an array of Entries. However, it will also be sorted by distance from the specified target. In this particular example, locations over 50 miles away will be excluded from the results.

# Query Parameters

As you've already noticed, there are two special query parameters which are responsible for turning the element query into a proximity search. To see the complete details of how each parameter works, check out the Query Parameters page.

# myAddressField(options)

In order to conduct a proximity search, specify your Address field handle with whatever options are appropriate. Check out the full list of options...

Use your real Address Field Handle

Use your real Address field handle instead of "myAddressField".

# orderBy('distance')

You will almost certainly want to sort your query by closest matches. Adding this parameter will ensure that the results are sorted from nearest to farthest.

Sorting by Distance

The distance "column" is not a real column in the database. It is dynamically generated on-the-fly, and the values are then accessible via the resulting Address Models.

# The `distance` property

When conducting a proximity search, you will end up with a normal array of elements. Per usual, each Address field will be accessible as an Address Model. However, when conducting a proximity search, each Address Model will also contain an additional property... distance.

The distance property of each Address Model will contain the relative distance to the specified search target. It is automatically populated if the element was retrieved as part of a proximity search. If the element was not retrieved as part of a proximity search, then distance will return a null value instead.

Query Parameters →