Get maps working with a Google Maps API key

  • troubleshooting
  • maps
  • google-maps
  • api-key
  • locations

Updated

To get a Google Maps API key, create a project in the Google Cloud Console, link a billing account, turn on Maps JavaScript API (and Geocoding API if you look up addresses), then click Create credentials → API key on the Credentials page. Restrict the key to your website and those APIs, then paste it into your map plugin's or theme's settings.

Without a key, or without billing, a Google Map on your site stays blank or shows an error instead of the map.

A map pasted in as Google's own embed code (Share → Embed a map on Google Maps) doesn't use your key. Dirigible's Map block works this way. This guide is for maps a plugin or theme draws for you, such as store locators.

How to get a Google Maps API key

  1. Sign in to the Google Cloud Console with the Google account you want to own the key. Use an account your business keeps, not a developer's personal one.
  2. Create a project, or select one you already use for this site.
  3. Link a billing account to the project. Google asks for payment details even if you stay within the free usage (see What a Google Maps API key costs).
  4. Open the Maps API library (under Google Maps Platform, or APIs & Services → Library). Click each API your site needs, then Enable. Most sites need Maps JavaScript API and Geocoding API. See Which APIs to turn on.
  5. Open Google Maps Platform → Credentials and click Create credentials → API key.
  6. Copy the key. It's a long string of letters and numbers.
  7. Restrict the key before you use it on your site (next section).

Google renames console menus from time to time. If a label doesn't match, look for Credentials and API key. Google's own steps: Set up your Google Cloud project.

A new key can take a few minutes to start working.

Which APIs to turn on

API What it does on your site
Maps JavaScript API Draws every interactive Google map. Always turn this on.
Geocoding API Turns an address or zip code into a point on the map. Store-locator searches and address lookups use it.
Places API Suggests addresses as you type in some map fields. Only needed if your project already has it (see below).

On a Dirigible site:

  • The Location Map, Locations, and Single Location blocks, and each location's own page, use Maps JavaScript API.
  • Location Search also uses Geocoding API to find the zip code a visitor types.
  • When you edit a location, the Google Map field finds the address you type with Geocoding API. Type the address and click the search icon, or click the map to drop the pin.

Google no longer lets new projects turn on Places API (Legacy), which powers the as-you-type address suggestions in that field. Without it, the field still works: you just don't get suggestions. If an older project already has it on, include it when you restrict the key.

Restrict your key to your website

Anyone can copy a map key from your site's pages. An unrestricted key can be used on other sites and run up charges on your account. Restrict it two ways:

  1. Open Google Maps Platform → Credentials and click the key's name.
  2. Under Application restrictions (or Set an application restriction), choose Websites. Add each address your site loads from, including https://:
    • https://yourdomain.com
    • https://*.yourdomain.com (covers www and subdomains, such as a staging site at staging.yourdomain.com)
    • A staging or temporary address on another domain, if you use one
  3. Under API restrictions, choose Restrict key and select only the APIs you enabled, such as Maps JavaScript API and Geocoding API.
  4. Click Save. Changes can take a few minutes to apply.

Don't add page paths. Browsers usually send Google only your domain, so a path like https://yourdomain.com/contact blocks the map. Google's guide: API security best practices.

If you move the site to a new domain, add the new address to the key before you switch. See Move a site or make a staging copy.

Add the key to WordPress

If your site runs on Dirigible

Dirigible Locations draws the maps. OpenStreetMap maps work without a Google key. These steps are for when Map Provider is set to Google Maps, its default.

  1. Go to Locations → Settings and find Maps.
  2. Turn on Enable Mapping.
  3. Set Map Provider to Google Maps.
  4. Paste the key into Google Maps API Key.
  5. Select Save Settings.

Check a page with a map in a private window. See Fix WordPress changes not showing on your site.

If the GDPR Banner is on, Google maps wait until the visitor accepts cookies. Write the message they see in Cookie Prompt, in the same Maps section. See Set up a GDPR cookie consent banner.

The Stadia API Key and Carto API Key fields are for OpenStreetMap tile styles, not Google. All the Maps settings: Locations Maps Settings.

Once the key is in, add maps to your pages with Add locations and a store locator map.

On other WordPress sites

Paste the key into the Google Maps API key field of whichever plugin or theme draws your maps. Each one has its own field, usually on its settings screen. Check its help pages for which APIs it uses, and enable those on your key.

What a Google Maps API key costs

The key itself is free. You pay for usage above Google's free monthly amount, and a billing account must be linked even if you never go over it.

  • Google gives a free number of uses each month for each kind of request. For example, Dynamic Maps (each interactive map load) and Geocoding each include 10,000 free a month.
  • The free amount resets on the first of each month. Usage above it is billed per 1,000.
  • New Google Cloud accounts may also get a free trial credit.

Most small business sites stay within the free usage. A busy store locator, or a key someone else is using, can go over it.

To avoid surprises:

  • Restrict your key (above). It's the best protection against someone else's usage.
  • Set a budget alert in the console's Billing section. It emails you as spending nears an amount you choose. A budget doesn't stop usage on its own. Google's steps: Create a budget.
  • Cap usage in Google Maps Platform → Quotas. Select the API, tick a quota, click Edit, and lower it. Requests stop when the cap is reached. The map stops loading too, so set it above your normal traffic.

Google changes these numbers. Check the current figures on Google's pricing page and cost management guide.

Map not showing? Common causes

Open a page with the map, then open your browser's console: right-click the page, choose Inspect, then the Console tab. Google reports the cause as Google Maps JavaScript API error: followed by a name.

What you see What it means Fix
"This page can't load Google Maps correctly." Google rejected the key. The console says why. Check the console and match the error below.
A dark map marked "For development purposes only" A key or billing problem. Check billing and the key.
RefererNotAllowedMapError The page's address isn't on the key's Websites list. Add the address exactly, with https://. Add https://*.yourdomain.com for www.
ApiNotActivatedMapError Maps JavaScript API isn't enabled on the project. Enable it.
ApiTargetBlockedMapError The key's API restrictions leave the API out. Add it under Restrict key.
BillingNotEnabledMapError The project has no working billing account. Link a billing account, or update the card.
InvalidKeyMapError Google doesn't recognise the key. Copy it again with no spaces, from the same project.
MissingKeyMapError The page loaded Google Maps with no key. Paste the key and publish.
ExpiredKeyMapError The key is new, deleted, or not recognised yet. Wait a few minutes. If it continues, create a new key.

Other things to check:

  • Zip search finds nothing, or the location field says "Location not found: REQUEST_DENIED". Geocoding API isn't enabled, or the key's API restrictions leave it out. Location Search needs it to look up zip codes.
  • The map loads but a location is missing. Locations show on a map only once their Google Map field has a pin. Edit the location and set it.
  • No map and no error. On Dirigible, make sure Enable Mapping is on, Map Provider is Google Maps, and the key is saved. If the GDPR banner is on, accept cookies first.
  • It works for you but not visitors. Your site's cache may still show an old copy. Purge it, then check in a private window.
  • It worked, then stopped. Billing may have lapsed, a quota may be reached, or the site moved to a new address that isn't on the key.

Google's full list: Maps JavaScript API error messages.

Other options

  • Google's embed code needs no key in your site settings. It shows one map with Google's own pin and controls. On Dirigible, use the Map block or Map and Text block.
  • OpenStreetMap needs no Google key or billing account. On Dirigible, set Map Provider to OpenStreetMap. The location field and Location Search then use OpenStreetMap's address lookup.

Keep your key with your other site logins. If a developer set it up in their own Google account, see Get your domain, hosting, and logins from a former web developer.

Built by Dirigible Studio. Get in touch