Google Maps Platform
Connect Google Maps Platform so the AI can geocode addresses, search places, compute routes and look up weather while it builds, and so your published app can show interactive maps and address autocomplete.
You connect it with your own Google keys — Berrybell doesn't provide Maps keys — and Google bills the calls to your own Google Cloud account.
Connecting
Before you start
In the Google Cloud project your keys belong to:
- Turn on billing.
- Enable each API you want, one by one. Enabling one doesn't enable the others: a key that geocodes is still refused by Weather until the Weather API is enabled too. If you restrict the server key by API, add each one to its allowed list as well.
- Create the keys: a server key, and a browser key if your app will show maps or autocomplete. How to restrict each one is described below.
Adding the keys
- Open Integrations in the dashboard, or App connectors in the Studio, and choose Google Maps Platform.
- Choose Connect Google Maps Platform. The form opens with a short summary of the setup, Use two Google Maps API keys, and a link to Google's key-restriction guide.
- Optionally give the connection a Display name. It only identifies the connection inside Berrybell and defaults to Google Maps Platform.
- Paste your keys into Server API Key and, if you have one, Browser API Key.
- If you added a browser key, tick the apps that should get it under Publish the public key to (see below).
- Choose Connect.
The connection belongs to your workspace, so every member can use it and the AI can use it in any project.
The two keys
| Server API Key | Browser API Key | |
|---|---|---|
| Required | Yes | No |
| Visibility | Private — it stays in Berrybell | Public — anyone who uses your app can read it |
| Used by | The AI, while it builds | Your app's maps and autocomplete, in the browser |
| Restrict it in Google Cloud by | Allowed APIs, not referrer | Website referrer |
The Server API Key is private. Berrybell stores it encrypted and attaches it to the AI's Maps calls on the server, so it's never sent to the browser and the AI never sees it either (the Integrations overview explains how). It's used only for the AI's calls: your published app doesn't receive it. Restrict it by the APIs it may call rather than by referrer, because its calls come from Berrybell's servers, not from a web page.
The Browser API Key is public by design — the browser needs it to draw maps, so anyone using your app can read it. The form shows it unmasked with a Public tag and warns: This value will be publicly visible in your published app. What protects it is the website-referrer restriction you set in Google Cloud, which Berrybell can't check for you. List every address the app is served from: its published address, any custom domains, and, if you want maps to work there too, the live preview and any other environments.
The two keys must be different. Both are AIza… strings, so pasting the same one
into both boxes is an easy mistake, and it would publish your private key into
the app. The form won't submit while they match, and Berrybell refuses the
connection if the same value arrives in both fields anyway.
Berrybell doesn't contact Google when you connect, and the connection's Test connectivity check only confirms that Berrybell holds the server key. An API that isn't enabled, billing that isn't on or a wrong restriction shows up as an error from Google the first time a call is made.
Publishing the browser key to your apps
The browser key only reaches the apps you choose. Publish the public key to lists the apps in your workspace as checkboxes; tick every app that should get it. One key can serve several apps. If the workspace has no apps yet, create the app first. The form lets you connect without one and says you can publish later, but the only way to publish the key afterwards is to remove the connection and connect again (see the warning below).
- The key is published to each app as a project-wide variable,
VITE_GOOGLE_MAPS_BROWSER_KEY, and the code the AI writes reads it from there. - It reaches the published app from that app's next publish, like any other variable change.
- It's project-wide, so it applies to every environment of the app and to the live preview as well.
- Berrybell sets the variable for you: it isn't listed on the app's Variables page, and you can't edit or override it there.
- If the app already has a
VITE_GOOGLE_MAPS_BROWSER_KEYvariable of its own, publishing replaces its value and Berrybell takes it over, so it no longer appears on the Variables page.
Until you pick an app, maps in the browser won't render — the key has nowhere to be published. The AI's own Maps calls don't depend on this, because they use the server key.
If you publish one key to several apps, its referrer list in Google Cloud must include every one of their domains, or Google rejects the key on the ones you missed.
Publishing the key needs the Editor role or above (see Team & roles).
A workspace has one Google Maps connection. Once it exists, choosing Google Maps Platform in the catalog opens it instead of a new form, so every app you publish a browser key to gets the same key.
You can't change a connection's keys, or the apps its browser key is published to, after you connect. To rotate a key or change the apps, Remove the connection and connect again — which also puts its permissions back to Ask each time.
Removing the connection deletes the browser key from every app it was published to, and each app stops shipping it from its next publish. It doesn't revoke anything at Google, so if you're replacing a key that leaked, delete or regenerate it in Google Cloud as well.
What the AI can reach
With the server key, the AI can call these Google Maps Platform APIs: Maps Web Services, Geolocation, Places (New), Routes, Address Validation, Roads, Geocoding, Air Quality, Pollen, Solar, Weather, Aerial View, Places Aggregate and Map Tiles. Each one still has to be enabled in your Google Cloud project and, if you restricted the server key by API, added to its allowed APIs. A Maps API that isn't in this list can't be reached at all.
Route Optimization and Street View Publish don't work with this connection. Google requires a signed-in Google account (OAuth) for them instead of an API key, so Google refuses Street View Publish calls even though Berrybell forwards them.
Permissions
Like every integration, the AI's use of Google Maps follows the permissions you set on the connection's page. Under Manage my agent's permissions, the Enable row (Enable Google Maps Platform, unless you gave the connection another Display name) sets the default for the whole connection — Always allow, Ask each time or Never allow — and Fine-grained permissions refine it for eight buckets.
The buckets are grouped by what the calls cost on your Google bill, not by whether they read or write:
| Bucket | What it covers |
|---|---|
| Geocode and look up coordinates | Forward and reverse geocoding, time zones, elevation, roads and geolocation. The cheapest Maps calls. |
| Validate addresses | Address Validation, billed per address at more than geocoding. |
| Search places and fetch details | Places search, details, autocomplete and area insights. Asking for more fields can move a call to a more expensive rate. |
| Compute routes and ETAs | Routes and arrival times between an origin and a destination, including standard traffic-aware routes. |
| Compute traffic-aware and matrix routes | Distance matrices, waypoint optimisation and the most precise traffic-aware routing (traffic-aware optimal). A matrix is billed per origin–destination pair, so a small matrix can be a large bill. |
| Fetch map imagery | Static Maps, Street View, map tiles, aerial views and place photos, billed per image. |
| Read environment data | Air quality, pollen, solar and weather. Solar data layers are billed at a premium rate. |
| Other Maps APIs | Any endpoint of the APIs in What the AI can reach that Berrybell doesn't recognise, including ones Google adds later, at unknown cost. |
Everything starts at Ask each time: the connection defaults to it, and each bucket reads Default (Ask each time) until you choose otherwise. Never allow on the connection always wins over a bucket's setting. Changing permissions needs the Editor role or above.
Keep Other Maps APIs at least as strict as the buckets above. It's a catch-all, so setting it to Always allow would let the AI call any endpoint Berrybell can't classify, at a cost it can't estimate.
These permissions govern the AI's calls with the server key. They don't apply to your published app, which calls Google directly with the browser key — there, the referrer restriction in Google Cloud is what limits use.
What it costs
Google bills every Maps call — the AI's, made with the server key, and your app's, made with the browser key — to your own Google Cloud account, at Google's rates. Berrybell doesn't charge for them. To watch that spend, use billing reports and budget alerts in Google Cloud; to cap it, set quotas on each API.
The AI's own work isn't free, though: the build runs in which it makes those calls use your AI credits as usual (see Plans & credits).
Next steps
- See all integrations: Integrations overview
- How your app's variables work: Variables & secrets