Connect a map provider

Choose a provider

Handled supports Mapbox and Google Maps. The provider changes the map renderer and available styles; it does not change the embed snippet, location records, result cards or Handled subscription. Both providers include Streets, Light, Dark and Satellite starting styles.

Create a browser key

Create a public browser token in the provider account that should receive map-usage billing. Mapbox browser tokens usually begin with pk.. Google Maps browser keys usually begin with AIza and need the Maps JavaScript API enabled.

Restrict the key

A browser key is visible to anyone who views your page. That is true of every map provider and is not a flaw in how Handled stores it: the visitor's browser has to send the key to draw a map. The restriction, not secrecy, is what stops another website using your key and billing you for it.

An unrestricted token works for requests from any website on the internet.

Mapbox

1. 1

   Open your access tokens

   Go to console.mapbox.com/account/access-tokens and click the token you gave to Handled.
2. 2

   Find Token restrictions

   Scroll to Token restrictions. If it reads 0 URLs and "This token will work for requests originating from any URL", the token is unrestricted.
3. 3

   Add your storefront URL

   In the URL box enter the site visitors actually load, scheme included, for example https://example.com. Click Add URL.
4. 4

   Add any other host that really serves the page

   Only add a second entry if a visitor's browser can actually end up there. Most sites redirect www to the bare domain or the other way round, and a redirect means the browser lands on one address, so one entry is enough. Add a staging or preview domain only if the locator genuinely runs on it.
5. 5

   Save and check the map

   Click Save changes, then reload your public locator page and confirm tiles still draw. A missing map here means a URL is missing from the list, not that the restriction was wrong.

Google Maps

1. 1

   Open your credentials

   Go to console.cloud.google.com/apis/credentials, select the project that owns the key and click the key.
2. 2

   Set the application restriction

   Under Application restrictions choose Websites.
3. 3

   Add your storefront

   Add an entry per host, for example https://example.com/*. Google matches referrers as patterns, so the trailing /* matters.
4. 4

   Restrict the APIs too

   Under API restrictions choose Restrict key and select only Maps JavaScript API. A key that can call every API in the project is worth far more to whoever takes it.
5. 5

   Save and check the map

   Save, then reload your public locator page. Google's changes can take a few minutes to apply.

Cap the spend

A domain restriction stops another website using your key. It does not put a ceiling on what your own locator can cost, and those are different problems. A page that gets scraped, linked from somewhere busy, or hit by a bot draws real map loads on a correctly restricted key.

Set a usage limit or a billing alert in the provider account, so a bad week arrives as a notification rather than as an invoice. Mapbox offers usage-based billing alerts on the account's billing page. Google Cloud offers budget alerts, and separately a daily quota cap per API under APIs & Services → Quotas, which is the harder stop of the two.

Handled rate-limits the searches that go through us, and address lookups use your key only through our own capped endpoint. Map tiles are drawn by the visitor's browser talking to your provider directly, so those never pass through Handled and only the provider can bound them.

Save and verify

1. 1

   Choose the provider

   Open Configure → Map and save Mapbox or Google Maps.
2. 2

   Add the matching key

   Open Embed & Install, paste the key and save it. Keys are provider-specific.
3. 3

   Open the public page

   Publish the embed and confirm that map tiles, markers and directions load on the restricted domain.

If the key is missing or rejected, the live locator keeps the results list available and shows a clear map setup message rather than substituting an unlicensed fallback map.

After the provider works, you can keep a built-in theme or connect a design from your own provider account. Mapbox accepts a published Mapbox Studio Style URL. Google Maps accepts a published cloud Map ID. Follow Customize maps, markers and clusters for the exact workflow and fallback behavior.