Getting started
Map provider
Connecting Google Maps or Mapbox, and what each key needs.
Settings → Map providers.
The locator draws its map, and searches addresses on the storefront, with your own Google Maps or Mapbox account. You provide the key; it is yours, and the usage is billed to you by them.
Which one
Either works, and every app feature works with both. The map looks different and the pricing differs — that is the whole of the decision.
| Google Maps | Mapbox | |
|---|---|---|
| Map | The map most shoppers already know, with street-level detail worldwide | Clean, modern styles |
| Credential | An API key (AIza…) | An access token (pk.…) |
| Free tier | Monthly credit, then per request | Generous free tier, then per request |
You can switch later. Locations, filters and everything else are untouched by the change — only the map and the storefront's address search change hands.
Google Maps
- Open Credentials in Google Cloud and create an API key.
- Enable the services the locator calls:
- Maps JavaScript API — the map itself.
- Geocoding API — turning a shopper's typed address into a point.
- Places API — only if you turn on address suggestions.
- Under the key's website restrictions, add your store's domain, plus your custom domain if you have one. The settings page shows both, ready to copy.
- Paste the key into the app and save.
If the map loads but search finds nothing, Geocoding is usually the service that was missed.
Mapbox
- Open Access tokens in your Mapbox account.
- Use the default public token, or create one with the default public scopes.
- Add your store's domain to the token's URL restrictions.
- Paste the token into the app and save.
Public tokens start pk.. A secret token (sk.) will not work in a browser, and
should never be pasted into a theme or an app.
Where the key is used
On the storefront:
- Drawing the map, its pins and the shopper's own location.
- Turning what a shopper types into a point to search around.
- Suggesting addresses as they type, if you have turned that on.
And in the app, for the live preview in Customize — which is why that screen only appears once a provider is connected. A key restricted to your storefront's domains may be refused there, leaving the map area blank while the rest of the preview works.
Address lookup and importing don't use your key. The address suggestions on the location form and the coordinates filled in during an import run on our own mapping service, so you can load your whole catalog before you have a provider key, and an import never consumes your Google or Mapbox quota.
Keeping the bill down
- Restrict the key to your domains. An unrestricted key can be lifted off your storefront and used by anyone, at your expense. This is the one step not to skip.
- Leave address suggestions off unless you want them. Suggestions ask the provider as a shopper types, so they cost more requests per search than the plain search box, which asks once.
- Limit search to your countries. Fewer wasted searches, and better results — see Search & radius.