API keys & security

Get a key

To use any SmartMaps service you need an API key. Register for free and choose the plan that suits your needs.

Using your key

Most SmartMaps services authenticate with your key as the apiKey query parameter — or the apiKey option in the JavaScript libraries. Two services differ:

Service	Authentication
Maps, Static Maps, Geocoding, Routing, Area, Elevation, Weather, Timezone	`apiKey` query parameter / `apiKey` option
Autocomplete API	short-lived bearer token requested with your key (see Autocomplete → Token)
Address Search	HTTP Basic authentication

Key encoding

API keys may be issued in a URL-encoded form (containing %2F, %3D, …). When you build a request URL by hand, do not blindly run the key through encodeURIComponent — an already-encoded key would be double-encoded and rejected as invalid.

In the JavaScript libraries this is handled for you.
When hand-building URLs with SmartMaps GL loaded, use smartmapsgl.encodeString(apiKey) — it encodes a raw key but leaves an already-encoded key untouched.

Without the library, use the same idempotent logic:

const key = apiKey === decodeURIComponent(apiKey) ? encodeURIComponent(apiKey) : apiKey;

Secure your key

Because web maps run in the browser, your key is visible in page source. Protect it:

Restrict the key to your production domain(s) in your account at account.smartmaps.app so it cannot be reused on other sites.
Use separate keys for development and production.
Never commit an unrestricted key to a public repository.

Demo keys in this documentation

The keys shown in the live examples on this site are demo keys, restricted to the documentation/demo domain and to a low request limit. They will not work on your own domain — replace them with your own key.