Maps and geolocation features in Bubble rely on Google APIs. Once your app uses your own domain, it will need your own Google API keys, added in the Settings tab, in the General section, under General services API keys. This guide covers how to obtain those keys, whether you're building for web, native mobile, or both.
Tip: The Google API is used for timezones as well as geographic addresses. If you use Current user's timezone or any addresses anywhere in your app, it's worth setting up these keys.
Our Academy tutorial on how to set up Google API keys
Which keys you need
Which keys you set up depends on where your app runs. Each platform authenticates with Google using its own key, so a project that ships to web, iOS, and Android uses a separate key for each. You'll find all of them in the Settings tab, in the General section under General services API keys:
Field | Platform | Used for |
Google Maps API key | Web | Maps and location features in your web app. |
Google Geocode API key | Web | Server-side geocoding, such as converting addresses to coordinates. |
Google Maps API key for iOS | iOS | Maps and location features in your native iOS app. |
Google Maps API key for Android | Android | Maps and location features in your native Android app. |
Set up the keys for the platforms you're publishing to. A web-only app uses the first two, a mobile app uses a key for each mobile platform it ships to, and an app that runs everywhere uses all four. The project and enabled APIs are shared across platforms, so most of the setup below you do once, no matter how many platforms you're building for.
Set up your project in the Google Cloud Console
First, you'll set up your app in the Google Cloud Console. This tells Google about your app and is how it knows which APIs your app is allowed to call.
Visit the Google Cloud Console. You'll need to log in, and you may also have to provide billing details, which Google requires.
Start by creating a project in Google that corresponds to your Bubble app.
In the Google Cloud Console, click New project to create a project for your app.
We recommend creating one project per app you are working on to keep your API keys, usage, and billing cleanly separated. That way, you can track each app's costs on its own, and a change to one app's keys won't affect any of your others.
With that project active (its name shows in the top bar), open the navigation menu in the upper-left corner and go to APIs & Services, then Library.
Search the API Library for each API by name, then select it to enable it. Here we're searching for the Geocoding API.
Enable the APIs
In the library, search for each of the following APIs and enable them one at a time. These power the core maps and location features across every platform.
Geocoding API
Converts addresses into geographic coordinates (latitude and longitude), and coordinates back into readable addresses. This is what lets your app turn a typed address into a point on a map, or work out an address from a location.
Places API
Provides information about places, like businesses and points of interest, and powers address autocomplete as users type. This is what lets your app suggest and identify real-world locations.
Geolocation API
Determines a device's approximate location based on nearby cell towers and Wi-Fi signals, rather than a typed address. This is what lets your app work out where a user is.
Maps JavaScript API
Renders the interactive map in the browser. This is what actually draws the map, its tiles, and its markers in your web app.
Time Zone API
Returns the time zone for a given location. This is what lets your app work with a user's local time, including the Current user's timezone value.
If you're building a native mobile app, also enable the Maps SDK for iOS, the Maps SDK for Android, or both, depending on which platforms you're publishing to. These render the map on each native platform, the same way the Maps JavaScript API does on web.
Create your keys
With your APIs enabled, you'll create a key for each platform you're building for. Every key is created the same way, from the Credentials page. What differs between them is how each one is restricted, since each platform proves it's allowed to use the key in a different way.
Web keys
A web app uses two keys: a Client key for requests made from the browser, and a Server key for requests made server-side.
Client key
Create the key
On the Credentials page, click + Create credentials and select API key. Rename the key to Client.
To create your keys, open the navigation menu and go to APIs & Services, then Credentials.
Add API restrictions
Under the key's API restrictions, select Restrict key and choose the Geocoding API, Places API, Geolocation API, Maps JavaScript API, and Time Zone API.
Add website restrictions
Under application restrictions, select Websites and add referrers in a format like the ones below, depending on your setup.
For a Bubble-hosted app:
*.appname.bubbleapps.io/*appname.bubbleapps.io/*https://appname.bubbleapps.io/*https://www.appname.bubbleapps.io/*
For a custom domain:
*.yourdomain.com/*yourdomain.com/*https://yourdomain.com/*https://www.yourdomain.com/*
For a subdomain:
*.subapp.yourdomain.com/*subapp.yourdomain.com/*https://subapp.yourdomain.com/*https://www.subapp.yourdomain.com/*
Save the key
Click Save to finish creating the Client key.
Website restrictions have limited wildcard support. You can use a wildcard (*) in place of a subdomain or path, such as *.example.com, but not in the middle of a URL.
Server key
Create the key
Click + Create credentials again and select API key. Rename this one to Server.
Add API restrictions
Under the key's API restrictions, select Restrict key and choose the same APIs as the Client key.
Save the key
Click Save. The Server key doesn't need website restrictions, since it's used for server-side requests rather than requests from a browser.
iOS key
A native iOS app uses its own key, restricted to your app by its bundle ID, the same identifier you set when publishing to the App Store. A native app doesn't run on a web domain, so it's restricted this way instead of by website.
Create the key
On the Credentials page, click + Create credentials and select API key. Rename it to iOS.
Restrict the key to iOS
Under application restrictions, select iOS apps and add your app's bundle ID.
Save the key
Click Save to finish creating the iOS key.
Android key
A native Android app uses its own key, restricted to your app by its package name and signing certificate. As with iOS, a native app isn't restricted by website.
Create the key
On the Credentials page, click + Create credentials and select API key. Rename it to Android.
Restrict the key to Android
Under application restrictions, select Android apps and add your app's package name and SHA-1 signing certificate fingerprint.
Save the key
Click Save to finish creating the Android key.
Add your keys to Bubble
Your keys are now ready to use. In your Bubble editor, go to the Settings tab, in the General section, and find General services API keys. Add each key to the field that matches its platform.
Add each key to its matching field in the General services API keys section of the Settings tab.
Key | Field |
Client | Google Maps API key |
Server | Google Geocode API key |
iOS | Google Maps API key for iOS |
Android | Google Maps API key for Android |
Further notes on the Google side
Google's own instructions for setting up an API key are here for Maps and here for Geocoding. Since Google updates its interface from time to time, refer to their official documentation if anything looks different.
To use these APIs, you may need to set up a billing account with Google Cloud and connect your Google project to it.
Changes to a Google project's configuration can take a minute or so to take effect.
Because Bubble uses the Google Maps API, some inconsistencies in Google Maps data will show up in your app. For example, for some non-US addresses, the city field is actually the name of the neighbourhood or area. To help with this, try adding a map element (even a hidden one) that takes its value from a SearchBox input. The map places the pin correctly, and its center may then yield more accurate data about that location.