# Link to your locator with a pre-filled search

Source: https://locator.handledlocal.com/docs/link-to-pre-filled-search

URL parameters that open the locator on a place, a filter, a keyword or a radius, for campaigns, ads and landing pages.

## 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.

Examples:

```
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`.

Examples:

```
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.

Example:

```
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.

Example:

```
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:

Example:

```
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](https://locator.handledlocal.com/docs/customize-layout-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.

> **Renaming a tag changes its slug**
>
> Slugs come from tag names. A link built for `service-center` stops matching if the tag is renamed to "Service Centre". Rename with care once links are out in emails and ads, or keep the old tag and add the new one.

## 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:

Locked embed:

```
<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](https://locator.handledlocal.com/docs/widget-javascript-api) does the same job: `searchNear`, `setFilters` and `search` map one to one onto these parameters. A [search bar on another page](https://locator.handledlocal.com/docs/external-search-bar) is a plain form that builds one of these links.
