# Setting Up a Google Maps API Key

This guide walks you through getting a Google Maps API key for use with the Map – pins section. If you'd rather not deal with a Google account or billing, you can leave the section's "Map provider" set to OpenStreetMap — it's free, requires no setup, and works out of the box.

### Why use Google Maps?

Google Maps gives you:

* A look and feel that most shoppers immediately recognise
* Premium map styles (Silver, Retro, Dark, etc.)
* More detailed labels for businesses, transit, and landmarks
* Smoother panning and zooming in dense urban areas

The trade-off: Google requires a billing-enabled account and charges per map load above their free monthly credit.

***

### Costs at a glance

Google currently includes a **$200 monthly credit** on every Maps Platform account, which translates to roughly **28,000 free dynamic map loads per month**. Most small and mid-sized stores stay well within that.

You still have to attach a billing method to your Google Cloud account to activate the key — even if you never exceed the free credit. Google won't charge the card unless you go over.

For current pricing, see [Google Maps Platform Pricing](https://mapsplatform.google.com/pricing/).

***

### Step 1 — Create a Google Cloud project

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Sign in with your Google account (or create one).
3. In the top bar, click the project dropdown → **New Project**.
4. Give it a name like `My Store Maps` and click **Create**.
5. Once it's created, make sure that project is selected in the top bar.

***

### Step 2 — Enable the Maps JavaScript API

1. In the Cloud Console search bar at the top, type **Maps JavaScript API** and select it from the results.
2. Click **Enable**.

> If prompted to set up billing, do so now — see Step 3.

***

### Step 3 — Add a billing account

1. In the left sidebar, go to **Billing**.
2. Click **Link a billing account** (or **Create billing account** if you don't have one).
3. Follow the prompts to add a credit/debit card.
4. Link the billing account to your new project.

This is required even though you'll be inside the free tier — Google uses it as an identity check and to bill any overage.

***

### Step 4 — Create the API key

1. In the left sidebar, go to **APIs & Services → Credentials**.
2. Click **+ Create Credentials** → **API key**.
3. Google will generate a key that looks like `AIzaSy…`. **Copy it.**
4. Click **Edit API key** to open its settings — you'll restrict it in the next step.

***

### Step 5 — Restrict the key (important!)

An unrestricted key can be copied off your site and used by anyone, racking up charges on your account. Restrict it so it only works on your store.

In the API key's settings page:

#### Application restrictions

1. Select **Websites**.
2. Click **Add** and enter each of the following (replacing `yourstore.com` with your actual domain):
   * `https://yourstore.com/*`
   * `https://www.yourstore.com/*`
   * `https://yourstore.myshopify.com/*` (your `.myshopify.com` domain)
3. If you use a staging or preview environment, add those too.

#### API restrictions

1. Select **Restrict key**.
2. From the dropdown, choose **Maps JavaScript API**.
3. Click **Save**.

***

### Step 6 — Add the key to your section

1. In your Shopify admin, go to **Online Store → Themes → Customize**.
2. Navigate to a page containing the **Map – pins** section (or add it).
3. Open the section's settings.
4. Under **🗺 Map provider**, change **Map provider** to **Google Maps**.
5. Paste your key into the **Google Maps API key** field.
6. Pick a **Google Maps style** (Default, Grayscale, Silver, Retro, or Dark).
7. **Save**.

The map should refresh and display through Google Maps within a few seconds.

***

### Troubleshooting

#### "This page can't load Google Maps correctly" / grey map with watermark

* The API key is missing, wrong, or your project doesn't have **Maps JavaScript API** enabled.
* Double-check Step 2 and Step 4.

#### "RefererNotAllowedMapError" in the browser console

* Your storefront's domain isn't in the **Website restrictions** list for the key.
* Open the key's settings and add the exact domain (including the `https://` and trailing `/*`).
* Save and wait 1–2 minutes for changes to propagate.

#### "BillingNotEnabledMapError"

* The Google Cloud project doesn't have a billing account attached.
* Revisit Step 3.

#### "ApiNotActivatedMapError"

* **Maps JavaScript API** isn't enabled on this project.
* Revisit Step 2 — and make sure you're enabling it on the same project the key was created in.

#### The map shows but my pins or styles look off

* Make sure you've also selected a **Google Maps style** in the section settings.
* The **Color filter** setting only applies to OpenStreetMap — for Google Maps, use the **Google Maps style** dropdown instead.

***

### Optional — Monitor usage and set a budget

To avoid surprise charges:

1. In the Cloud Console, go to **Billing → Budgets & alerts**.
2. Click **Create budget**.
3. Set a monthly target (e.g. `$0` if you only want the free tier).
4. Add email alerts at 50%, 90%, and 100% of the budget.

You can also cap daily request quotas on the Maps JavaScript API under **APIs & Services → Maps JavaScript API → Quotas**.

***

### Reverting to OpenStreetMap

If you ever want to remove the Google Maps key:

1. Open the section's settings in the customizer.
2. Change **Map provider** back to **OpenStreetMap (free)**.
3. **Save**.

Your locations and search bar will continue to work — only the map tiles and styling change.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://design-packs.gitbook.io/docs/fundamentals/section-tutorials/setting-up-a-google-maps-api-key.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.