Creating a Mapbox key

Stockist supports using either Google Maps or Mapbox to power the map imagery in your store locator.
While Google Maps is well-known, setting up a license key to use Google Maps on your own site is a relatively challenging process and is prone to breaking later on.
As an alternative, Stockist supports powering your store locator’s map using Mapbox. Mapbox is another map company that focuses on providing maps to be used on your website. Their maps are similar to Google’s and offer a similar level of free monthly usage, but are much easier to set up.

Creating your key

Follow these steps to set up a Mapbox key:

  1. Sign up for an account with Mapbox on their website: https://account.mapbox.com/auth/signup/


    Choose a username (a good choice is your business name in lowercase without spaces, e.g. jennyscupcakes), enter your email address, and select a password.

    We suggest saving your account details in a secure place in case you need to access your account later on.


    If Mapbox offers the options "Start without a card" and "Add a card now", we recommend choosing Add a card now. Mapbox has a generous free tier that covers about 10,000 visits to your store locator map every month, so for most sites there's no separate cost.


    If you choose "Start without a card", this will create a demo account that supports around 1,000 views of your map in total before pausing. If you're just testing things out, you can start with this option and then return later to add a payment method if you'd like to continue with Mapbox.

  2. Once your account is created, you'll end up on the Account overview screen of the Mapbox dashboard. In the left menu, click Tokens:

  3. Click Create a token:

    If you created a demo account with Mapbox ("Start without a card"), you won't be able to create an extra token but can copy your "Default public token" into Stockist. If you decide to continue with Mapbox later on, we recommend creating a secure token with the steps below once you've updated your Mapbox account with a payment method.

  4. Enter a name for your key to remember what it's for - "Stockist Store Locator" is a good choice:

    Under Token scopes, leave everything as-is (no changes needed). All "public scopes" should be selected, and all "secret scopes" should be un-selected.

    Under Token restrictions, enter your website domain only, then click Add URL:

    Even though the field says URL, only enter your site's domain name alone. In particular:

    1. Don't include http:// or a suffix like /pages/stores
    2. Don't include wildcards like *
    3. Enter each website in lowercase letters only
  5. If your site is on one of the following platforms, add these extra entries to the URLs list:
    1. For Shopify sites, add your myshopify.com domain (e.g. example.myshopify.com) as well as shopifypreview.com. Please be sure to use lowercase letters.
    2. For Wix sites, add filesusr.com
    3. For GoDaddy sites, add about:srcdoc

  6. Once you've added all of the relevant domains, click Create token to finish creating your map key:

  7. Once your key is created, you'll be taken to the Access tokens page. Copy the key that was just created by clicking the clipboard icon next to the key in the list:

  8. Make sure you're copying the key that was just created, not the "Default public token".

  9. Add the token to your Stockist account on the Map provider page of the Stockist dashboard:

Troubleshooting

After you set up a Mapbox key, if the map on your website starts showing up gray (without the roads/imagery behind the pins), this indicates an issue with your key. In this case, please check:

  • That your key was copied correctly and fully into the Stockist dashboard
  • The the domain added in the URL field matches the address bar in your browser when viewing your map page
  • That the list of URLs contains just your domain in the allowed list (e.g. example.com only, not http://example.com/pages/store-locator)

We're also happy to help investigate any issues - feel free to get in touch through the Contact us page in the dashboard.

Related Articles