Store Locator Javascript Automation API

Introduction

Our store locator has a powerful Javascript based API interface which includes the Public Functions described in this article. These functions allow you to do many things such as:

Retrieve the list of stores and use them locally
Completely customize how a store location is drawn by replacing the built in HTML store information function
Change the map position, address, search radius and language dynamically after the locator has loaded

Public Functions

storeLocatorGeolocateUser();

This function triggers the automatic geolocation feature of the locator. It's equivalent to what happens when the 'My Location' button is pressed in the locator and will usually trigger a browser prompt to request the user's permission to share their location. If permission is granted, the store locator will geolocate the user using HTML5 browser based geolocation, center the map on the user's position and update the address list to reflect the closest stores to this new location.

var data = storeLocatorGetData();

This function loads all the major store locator configuration and data structures into the data object. storeLocatorGetData() returns the following data structure:

{
  categories: Array(),
  custom_elements: Array(),
  filters: Array(),
  layout: {
    categories: [],
    filter_images: [],
    filter_order: [],
    location: Array(),
    map_double_left: Array(),
    map_double_right: Array(),
    map_single: Array(),
    store_editor: Array()
  },
  settings: {
  }
}

storeLocatorLoad(uid);

Calling this function reloads all locator data from our CDN and resets the locator, then loads it with the fresh data. The uid parameter is usually your unique account uid which can be found on your Account Details page under "Store Locator API key".

uid: Required (string) - your unique user id

storeLocatorReinitialize();

Similar to storeLocatorReset() but works at a lower level, rebuilding the store locator interface and reading all settings. This is useful when you have pushed a setting change using storeLocatorSetSetting() and need this setting to be applied to the locator. In this example, a call to storeLocatorReinitialize() would be required.

storeLocatorReset();

Reset the locator to it's original load state without requiring a page reload or call to storeLocatorLoad(). All Filter and Category selections are also reset to their defaults.

storeLocatorSetCategories(categories);

This function sets the Categories that are checked (for checkboxes) or selected (for a dropdown category selection).

categories: Required (String or Array) - either a single Category name as a string or an Array of Category strings that you would like applied.

storeLocatorSetCountries(countries, updateLocator);

This function sets the Countries that are displayed in the store locator. Any store which is not present in the list of defined countries will not be displayed in the store locator.

countries: Required (String or Array) - two digit ISO 3166 Country codes (https://www.iban.com/country-codes) either as a string for a single Country code or as an Array of Country codes that you would like to be displayed.

updateLocator: Required (boolean) - if this is set to true, the locator will update it's store list and map view based on the new Country list.

storeLocatorSetFilters(filters, updateLocator);

This function sets the Filters that are checked (for checkboxes) or selected (for a dropdown filter selection).

filters: Required (String or Array) - either a single Filter name as a string or an Array of Filter strings that you would like applied

updateLocator: Required (boolean) - if this is set to true, the locator will update it's store list and map view based on the new Filter settings that have been defined.

storeLocatorSetInitialSearchCompleted(initialSearchStatus);

Set whether an initial search has been completed. This is used by the locator to determine the correct operating state of elements such as the map and location list visibility.

initialSearchStatus: Required (boolean) - if set to true, this means that the locator will process events as if the user has conducted a search already. If set to false, it will process events as if the locator had just loaded before any searches are made.

storeLocatorSetLanguage(language);

Use this function to switch languages in your locator. An example of where this could be useful is if your web page has dynamic language switching without requiring a page refresh; in this case you could use storeLocatorSetLanguage() to set the store locator language instantly as well.

language: Required (string) - the name of the language as defined on the Text Labels page.

storeLocatorSetMapPosition(lat, lng, zoom);

The locator will center the map and update the store list based on the map coordinates that you enter here. Zoom can be set to zero if you want it to be unchanged from the current zoom level.

lat: Required (float) - latitudinal map coordinate

lng: Required (float) - longitudinal map coordinate

zoom: Required (int or float) - map zoom level - Google Maps only support integer zoom levels from 0 to 22. ExpressMaps and Mapbox both support floating point zoom levels from 0 to 22.

storeLocatorSetSearchRadius(radius);

Sets the search radius value.

radius: Required (integer or string) - the radius to set. It must be one of the search radius options defined in your list. Unlimited should be used to set an Unlimited radius.

storeLocatorSetSetting(settingName, settingValue);

This function can be used to set any parameter in the store locator. Some settings will require a call to storeLocatorReset() or even storeLocatorReinitialize() to apply. For example, a setting which changes the default search radius will only be applied when a full initialization takes place as the search radius HTML is only built when the locator first loads.

settingName: Required (string) - the name of the setting that you want to update

settingValue: Required (Mixed) - the new setting value

storeLocatorSetUserAddress(address);

Use this function to search for an address in the locator and center the locator on the coordinates of that address. It is almost equivalent to a user typing this address into the search bar in the locator and accepting one of the suggested matches.

address: Required (string) - the address that you want to search for

storeLocatorSetUserLocation(lat, lng, dropMarker, setAddress);

Use this function to set the map coordinates and update the store list based on the new location. It is equivalent to a user pressing the 'My Location' button to locate themselves on the map, with the difference being that in this case the function sets the new coordinates directly.

lat: Required (float) - latitudinal map coordinate

lng: Required (float) - longitudinal map coordinate

dropMarker: Required (boolean) - if set to true, drop a user marker at this map location

setAddress: Required (boolean) - if set to true, the map coordinates are reverse geocoded to identify the street address at that location and this address is inserted into the address search field.

storeLocatorSetUserStore(StoreNameAndAddress, refreshAddressList);

This function can be used to center the map on a particular store so that it's marker is in the center of the map and it is listed first in the store list. As stores, particularly chain stores, often have the same name, a combination of an exact match on the Store Name field and a partial match of the Address field can be used to uniquely identify a store.

StoreNameAndAddress: Required (string) - this string is in the format Store Name|Address. Note the | in between the Store Name and Address parts. If the store that you would like to set has a unique name then only the StoreName part is required. However, if many stores share the same name then part of the address must be used. You only need to provide a text string that is part of the store's address that uniquely identifies it. For example, a Walgreens store on Acacia Avenue might have a StoreNameAndAddress field of Walgreens|Acacia. As long as no other Walgreens stores have the word Acacia in their address, this will be sufficient.

refreshAddressList: Required (boolean) - if this is set to true, the locator will update it's store list as well as the map view.

storeLocatorShowAlertModal(title, message);

This displays an alert modal to the user. HTML content is supported.

title: Required (string) - the alert title

message: Required (string) - the alert body

storeLocatorShowDirections(storeID);

This function will show Google Maps or Mapbox directions from the current map center to the storeID specified.

storeID: Required (integer) - the unique storeID which can be found in a number of places:

From the data-idx parameter attached to the Store Name field in the store list.
From the index of the store in the stores list when extracted via the storeLocatorGetData() function.

storeLocatorUpdateAddressList();

This function recalculates based on current parameters, clears and renders the store list and updates the map markers if required.

storeLocatorZoomMap(searchZoom);

searchZoom: Required (string / integer) - this can be one of the following values:

AllListed - set the bounds of map to include the user's location and all stores in the store list
Integer value - set this zoom level
Zero (0) - set the bounds of the map to include the user's location and their closest store

Store Locator Javascript Automation API - Public Functions

Introduction

Public Functions