You can display links on your Website that link directly to specific searches of your interface. To do this, you can add URL parameters to the page on which the MetaLocator code is hosted. These special URL parameters will be passed into the MetaLocator interface code on that page and interpreted as part of the search.

In this example, an interface is displayed on https://www.yourwebsite.com/locations.html using the provided installation code.

If we want the page behavior to automatically pre-populate the postal code field in the postal code search box, we can add a URL parameter as follows:

https://www.yourwebsite.com/locations.html?ml___postal_code=98421

Deep Link Generator

The Deep Link Generator allows you to create links that open your locator with pre-selected searches, filters, and behaviors. These links can be used on your website, in emails, ads, or integrations to send users directly into a specific locator experience.

You can also generate an equivalent JavaScript configuration, which is useful when embedding parameters directly into your page.

Accessing the Tool

Navigate to:

Tools → Deep Link Generator

This tool provides a guided interface to create deep links without manually writing URL parameters.

How Deep Linking Works

MetaLocator accepts special parameters prefixed with:

ml___

These parameters:

Control the initial state of the locator
Can trigger searches automatically
Can filter results, open specific views, or enable features

You can pass these parameters in two ways:

URL query string
JavaScript (ml___params)

Step 1: Add Your Host Page URL

Enter the page where your locator is installed.

Example:

https://www.yoursite.com/locations.html

Step 2: Add Deep Linking Parameters

Click “Add Parameter” and configure one or more filters.

As you add parameters:

The Generated URL updates automatically
The JavaScript Output updates automatically

Parameter Types

System Parameters

These control core search and behavior.

Parameter	Description
`postal_code`	Geographic search term
`radius`	Search radius (numeric)
`task=search_zip`	Triggers search execution
`id`	Specific location ID
`view`	`directory` (default) or `location`
`limit`	Max results
`limitstart`	Result offset
`keyword`	Global keyword search
`lang`	Language file
`user_group_id`	Filter by user group
`user_lat`, `user_lng`	Pass known user location
`type`	Filter by system type field

Categories (tags[])

Filter by categories using their ID values.

Example:

ml___tags[]=99&ml___tags[]=100

Field Filters

Filter any field using its safe name (found under Data → Fields).

Example:

ml___city=Milwaukee

Related Table Filters

Used when filtering relational data (e.g., products, styles).

Format:

ml___field[table]=value

Example:

ml___sku[products]=TX2341

Special Flags & Triggers

Examples include:

Showing the Buy Online tab
Login / Claim forms
Registration triggers
Skip interstitial screens
Privacy opt-out (_opt_out=1)

Generated URL

The tool builds a complete URL like:

https://www.yoursite.com/locations.html?ml___postal_code=98421&ml___radius=200&ml___task=search_zip

Important Notes

The ml___ prefix is required
Multiple parameters can be combined
Parameters are appended to your URL, leaving any existing parameters intact

JavaScript Output

You can also use a JavaScript configuration instead of URL parameters.

Example:

<script> 
var ml___params = {
   "postal_code": "98421",
   "radius": 200,
   "task": "search_zip" 
}; 
</script>

When to Use JavaScript

Embedding behavior directly into a page
Avoiding URL manipulation
Building dynamic experiences

Common Use Cases

1. Auto-Search by Postal Code

https://www.yoursite.com/locations.html?ml___postal_code=98421&ml___task=search_zip&ml___radius=200

A radius and task=search_zip are required to auto-run the search

2. Open a Specific Location

https://www.yoursite.com/locations.html?ml___id=12&ml___view=location

3. Search for a Single Location

https://www.yoursite.com/locations.html?ml___task=search_zip&ml___id=12

4. Filter by Categories

https://www.yoursite.com/locations.html?ml___tags[]=99&ml___tags[]=100

5. Filter by Product SKU

https://www.yoursite.com/locations.html?ml___sku[products]=TX2341

6. Load a Language

https://www.yoursite.com/locations.html?ml___lang=en-US

7. Filter by User Group (Teams Feature)

https://www.yoursite.com/locations.html?ml___user_group_id=1

Advanced Usage

Substring Field Searches

To search within a field using partial matches:

<script> 

var ml___params = {
"favoritecolor": "red",
"favoritecolor_textfield": 1 
}; </script>

Without _textfield, the match is exact.

Override Interface Settings

You can override interface settings dynamically:

<script> 
var ml___options = {
"theme_color_primary": "#ff7bff",
"theme_font_size": "2" 
}; 
</script>

In the above example, the primary color has been set as well as the font size. To discover the allowable names for these settings, check the tooltip in the setting as shown:

Acceptable values are commonly apparent, however; exporting the interface settings can also assist in providing example values for a given setting.

Passing User Location

<script> 
var ml___params = 
{
"user_lat": 37.066889,     
"user_lng": -90.126482 
}; 
</script>

user_lat and user_lng can also be provided as base64 encoded values.

<script> 
var ml___params = 
{
"user_lat": 'NDkuNTIxMQ==',     
"user_lng": 'LTEwMi4yMzQ=' 
}; 
</script>

Persisting Parameters

Some filters (like categories) persist automatically.

For custom fields:

Add the field to the search form
Optionally hide it to prevent user changes

Custom Search Forms

You can build your own search UI:

<input id="postal_code" type="text" /> <input type="button" onclick="window.location.href='locator.html?ml___task=search_zip&ml___radius=200&ml___postal_code=' + document.getElementById('postal_code').value;" value="Submit" />

Standalone Lead Forms

A MetaLocator interface can be configured to display only a lead form. This is useful for creating standalone Lead Capture forms that are installed on external location pages. The Leads captured are saved in MetaLocator just as any other Lead.

To create an Interface suitable for embed as a stand-alone Lead form, follow these essential steps:

Set "Results > Initial State" to Show None
Remove all elements from the Search Form
Set Layout > Show Map > No
Set Layout > Show List > No
Configure your Lead form as desired

This creates an interface that only displays a lead form. The next step is to install the interface in a way that:

Triggers the form to display on page load
Passes in a location ID or an External Key to identify which location should receive the lead.

To do that, place the following script *above* the standard MetaLocator installation code. However, the value of the "id" should be modified to indicate the target location ID.

<script>
 var ml___params = {
'ml_trigger_cb_contact_form_template': 1,
'ml_standalone':1,
 'id': '1',
 'task':'search_zip'
 };
</script>

This code can also use an External Key to identify the target location, for example, if the External Key was "Storenum", and the target location was Storenum = 1234, use the following installation code:

<script>
 var ml___params = {
'ml_trigger_cb_contact_form_template': 1,
'ml_standalone':1,
 'storenum': '1234',
 'task':'search_zip'
 };
</script>

ml_standalone:1

This parameter prevents the modal from being closed and also removes the usual modal border. Use this when embedding only the form without a locator behind it.

Privacy Opt-Out

Disable tracking and cookies:

_opt_out=1

Example:

https://www.yoursite.com/locations.html?_opt_out=1

This prevents analytics tracking and cookie storage.

Tips & Best Practices

Always include task=search_zip when triggering a search
Combine parameters for advanced filtering
Use JavaScript for embedded or dynamic experiences
Test links before publishing
Use the Deep Link Generator instead of manually writing URLs

Troubleshooting

Search does not run

Ensure task=search_zip is included
Ensure radius is provided for geographic searches

No results

Verify category IDs, field names, and values

Parameters not persisting

Ensure the field exists in the search form

Summary

The Deep Link Generator simplifies creating powerful, parameter-driven links into your locator. It supports both URL-based and JavaScript-based configurations, allowing you to fully control the locator experience from outside the application.

Use it to:

Drive users to targeted results
Customize experiences per campaign or page
Integrate MetaLocator into custom workflows and UI components

Nearby Widget

Crowdsourcing Campaigns & Deep Links

Tracking Lead campaign effectiveness with UTM Codes

Can I limit the zip code field to 5 digits?

Scoping Categories by Country

Deep Linking and Dynamic Options

Deep Link Generator

Accessing the Tool

How Deep Linking Works

Step 1: Add Your Host Page URL

Step 2: Add Deep Linking Parameters

Parameter Types

System Parameters

Categories (tags[])

Field Filters

Related Table Filters

Special Flags & Triggers

Generated URL

Important Notes

JavaScript Output

When to Use JavaScript

Common Use Cases

1. Auto-Search by Postal Code

2. Open a Specific Location

3. Search for a Single Location

4. Filter by Categories

5. Filter by Product SKU

6. Load a Language

7. Filter by User Group (Teams Feature)

Advanced Usage

Substring Field Searches

Override Interface Settings

Passing User Location

Persisting Parameters

Custom Search Forms

Standalone Lead Forms

Privacy Opt-Out

Tips & Best Practices

Troubleshooting

Summary