Link to your locator with a pre-filled search

A link that lands on results

A regional call to action, an email to customers in one city, an ad for one product line, a landing page for one type of dealer: each of these wants the visitor to arrive on the locator with the right search already done. Add a few characters to the locator page's address and that is what happens.

Nothing needs switching on. The locator reads these parameters whenever they are present.

Link to a search near a place

Add ?loc_near= and a town, postcode, region or anything else the search box accepts.

https://example.com/locations?loc_near=90210
https://example.com/locations?loc_near=Chicago
https://example.com/locations?loc_near=Manchester,%20UK
https://example.com/locations?loc_near=Ontario,%20Canada

The place is geocoded on arrival, exactly as if it had been typed, and the nearest locations are listed. Spaces are written as %20; most tools that build links do that for you.

Link to a filtered view

Add ?loc_tags= and a tag slug: the tag's name in lower case with hyphens for spaces. "Authorized Dealer" is authorized-dealer.

https://example.com/locations?loc_tags=authorized-dealer
https://example.com/locations?loc_tags=authorized-dealer,service-center

Several tags are separated by commas. A tag the locator does not recognise is ignored and the rest still apply.

Link to a keyword search

Add ?loc_q= and a term. It fills the keyword box and matches location names and addresses.

https://example.com/locations?loc_q=Nordstrom

Set the radius

Add ?loc_radius= and a number in the units your locator shows. It only has an effect together with a place, since a radius is measured from somewhere.

https://example.com/locations?loc_near=Denver&loc_radius=10

Combine them

Join parameters with &. A regional page for one product line looks like this:

https://example.com/locations?loc_near=Austin,%20TX&loc_tags=habanero-reserve&loc_radius=25

Links visitors share

The same parameters are what the locator writes into the address bar as a visitor searches, when the URL state setting is on (it is on by default; see customize layout and results). A visitor who copies the address after searching gets a link that reproduces their view, which is why the format is readable slugs rather than ids.

Only typed places are written into the URL. A search from the visitor's browser position stays out of it, so a shared link never carries someone's coordinates.

A page locked to some locations

A link pre-fills a filter the visitor can clear. A page that should only ever show some locations, a product page listing its stockists or a services page listing the service team, needs the lock on the embed itself. Two attributes on the embed script do that, and the Embed & Install builder writes them for you:

<div id="biz-locator-root"></div>
<script src="https://cdn.handledlocal.com/widget.js"
data-site-id="your-site-id"
data-tags="habanero-reserve"
data-near="Austin, TX" async></script>

• data-tags keeps the embed to locations carrying any of the listed tags, by name, slug or id, comma-separated. They are applied before anything is shown and stay applied whatever the visitor clears, and those tags are not offered as filters since every location shown already has them.
• data-near opens the page with a place search already made. A loc_near parameter on the page URL wins over it.

One locator, as many embeds as your site has pages.

The same thing from code

When the link target is the page the visitor is already on, or the state has to change without a reload, the JavaScript API does the same job: searchNear, setFilters and search map one to one onto these parameters. A search bar on another page is a plain form that builds one of these links.