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:

1. URL query string
2. 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.

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:

1. Set "Results > Initial State" to Show None
2. Remove all elements from the Search Form
3. Set Layout > Show Map > No
4. Set Layout > Show List > No
5. 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:

1. Triggers the form to display on page load
2. 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

Updated on: 12/11/2026