# Google Maps Platform

Google Maps Platform turns addresses into coordinates, looks up places and plans routes. Connect it and the addresses in your <Term id="table">tables</Term> can go on a map or be joined by location with your other data.

Your <Term id="studio">Studio</Term>'s AI prepares the connection; you finish it by pasting an API key from your own Google Cloud project.

## Before you start [#before-you-start]

- A <Term id="project">project</Term>. Its Studio's AI does the work. See [Create a project](/docs/projects/create-a-project).
- A Google Cloud project with billing set up and the Maps APIs you need turned on (for example geocoding, places or routes).
- An **API key** from that project. Restrict the key to just those APIs, so it cannot be used for anything else.
- A table with addresses, if you want to geocode them. Clean, complete addresses (street, city, country) give better results.

<Callout type="info" title="Usage is billed by Google">
  Requests made with your key are Google Maps Platform usage under your own Google account, billed by Google, not by Klarety. Check Google's pricing before you start. Ask the AI to geocode each address once and store the result, rather than calling Google every time.
</Callout>

## Connect it [#connect-it]

<Steps>
<Step>
### Open Google Maps Platform [#open-google-maps-platform]
Go to <AppLink to="connectors" />, search for **Google Maps Platform** and open it.
</Step>
<Step>
### Send the request to a project's AI [#send-the-request-to-a-projects-ai]
Under **Connect it with your Studio's AI**, choose the **Project** that should use Google Maps Platform. **What the AI is asked** starts as "Connect Google Maps Platform to this project so it can geocode addresses and get places and routes." Edit it to say exactly what you want, for example: "Geocode the address column of the customers table and add latitude and longitude columns". Then select **Send to AI**.

The AI starts at once if the Studio is open, or when it next opens. Select **Open Studio** to go there.

<Screenshot src="/docs/_media/connect-data-with-ai-in-dashboard-data-page.png" alt="Connecting Google Maps Platform with a project's AI from the Connectors page" />
</Step>
<Step>
### Finish the connection [#finish-the-connection]
The AI drafts the connection and never asks for a key in the chat. The draft shows as **Waiting for you**. Select **Connect** to open the **Connect Google Maps Platform** dialog.

The dialog lists the steps to get the key and has **Open the page with your key**, which opens Google Cloud in a new tab. Copy the key there and paste it into **Key**. The dialog shows the only site the key is ever sent to.
</Step>
<Step>
### Choose what the AI may do [#choose-what-the-ai-may-do]
Under **What the AI may do with it**, choose **Can read** (nothing there changes) or **Can read and change** (the AI may also add, change and remove things). Then select **Connect**.

<Screenshot src="/docs/_media/slack-connector-how-to-connect-in-ui.png" alt="The Connect Google Maps Platform dialog with the access choice" />
</Step>
<Step>
### Test it and tell the AI [#test-it-and-tell-the-ai]
The dialog says **Google Maps Platform is connected**. Select **Test it**, then **Tell the AI** so it carries on.
</Step>
</Steps>

You can also start inside a project: in **Settings**, **Keys**, describe it in **What do you want to connect?** and select **Ask AI to connect**.

**Can read** is enough here: looking up coordinates, places and routes does not change anything in your Google account.

## What you get [#what-you-get]

- **Coordinates in your tables.** Geocoded addresses are stored as columns in <Term id="nexus">Nexus</Term>, so you pay Google once per address.
- **Maps and joins by location.** Put rows on a map in an app, or join them with other data by place: nearest store, customers inside a region, deliveries per area.
- **Places and routes.** An app or an <Term id="agent">agent</Term> can look up a place's details or plan a route between points while it runs.

## Test, pause and reconnect [#test-pause-and-reconnect]

A project's connections are listed in its **Settings**, under **Keys**, with their status.

<Screenshot src="/docs/_media/manage-connections-by-toggle-on-off-per-project.png" alt="A project's connections in Settings, Keys" />

| Status | What it means |
| --- | --- |
| **Waiting for you** | Drafted by the AI. Select **Connect** to finish it. |
| **Works** | Connected and usable by the project. |
| **Needs reconnecting** | The key or sign-in stopped working. Select **Reconnect**. |
| **Paused** | Nobody can use it until you select **Resume**. |

From the same row: **Test**, **Pause**, **Turn off here** (this project stops using it) or **Remove** (deletes the key, and every Studio using it stops reaching Google Maps Platform).

A connection belongs to the project it was made in. Owners and admins see all of them under **Your connections** on <AppLink to="connectors" />. It stays off for other projects until an admin switches it on under **Projects that may use** it.

## If the test fails [#if-the-test-fails]

**Test** reports one of these:

- It works: the project reached the service.
- The key was rejected: select **Reconnect** and enter a new one.
- The service cannot be reached: check that it is up and accepts outside connections, then test again.
- Internet is off: the project's internet is **Off**. Turn it on in its **Settings**. With **Only allowed**, the Studio reaches only its connections and the sites you add.
- It is not connected yet: select **Connect**.

Specific to Google Maps Platform:

- **The key is refused.** The API you need is not turned on in the Google Cloud project, or the key's restrictions do not include it. Fix it in Google Cloud and test again.
- **Some addresses have no coordinates.** The address was incomplete or ambiguous. Ask the AI to list the rows it could not geocode so you can correct them.

## Where your key goes [#where-your-key-goes]

The key or sign-in is encrypted with a managed key service the moment you select **Connect**, and not even the AI can read it. The Studio never holds the key. If the one site it is sent to is not the service's own address, Klarety warns you and asks you to type the site to confirm.

## Next steps [#next-steps]

- [Google Sheets](/docs/connectors/google-sheets)
- [Tables](/docs/data/tables)
- [All connectors](/docs/connectors/catalog)