🗺️ Maps: Add Your Google Maps Key #

How to turn the Google Maps page from static previews into interactive maps with your own API key.

Overview #

The Google Maps page (chart/map-gmap.html, menu: Maps → Gmaps) ships without an API key. Until you add one, each example shows a static SVG preview of the same area with this notice:

Preview — add your Google Maps API key in src/assets/js/config.js to load the interactive map

The preview coastlines come from Natural Earth (public domain), so nothing is requested from Google and no key is exposed in the demo.

Once a key is set, the page loads the Maps JavaScript API and replaces each preview with a live map:

The vector maps page (chart/map-vector.html, jsvectormap) needs no key and is not affected.

See both pages in the live demo: Google Maps previews and Vector Maps.

Files Involved #

The build copies src/assets/js/config.js to dist/assets/js/config.js.

Step 1: Create an API Key #

1. Open the Google Cloud console and select (or create) a project. Google Maps Platform requires a billing account on the project.
2. Go to APIs & Services → Library and enable Maps JavaScript API.
3. Go to APIs & Services → Credentials and click Create credentials → API key.

Step 2: Restrict the Key #

A Maps JavaScript API key is always visible in the page source, so restrict it before you use it:

1. Open the key in APIs & Services → Credentials.
2. Under Application restrictions, choose Websites (HTTP referrers) and add the sites that may use it, for example:

   https://www.example.com/*
   http://localhost:4173/*

3. Under API restrictions, choose Restrict key and select Maps JavaScript API.

Step 3: Add the Key to config.js #

Open src/assets/js/config.js and paste your key:

// Google Maps (chart/map-gmap.html)
window.AdmindekConfig.googleMapsApiKey = 'YOUR_KEY';
 
// Map ID used by the advanced marker example. 'DEMO_MAP_ID' is Google's
// documented test ID; replace it with a Map ID from your Cloud project.
window.AdmindekConfig.googleMapsMapId = 'DEMO_MAP_ID';

Then rebuild (npm run build) so the file is copied to dist/assets/js/config.js.

Already deployed a built site? Edit assets/js/config.js on the server directly; no rebuild is needed.

Step 4: Set Your Own Map ID (Optional) #

The marker example uses an advanced marker, which needs a Map ID. DEMO_MAP_ID is Google's documented test ID and works for trying things out. For production, create a Map ID in the Cloud console (Google Maps Platform → Map management) and set it as googleMapsMapId.

How It Works #

map-gmap.html loads the settings and the page script at the bottom of the page:

<!-- Google Maps: the key lives in assets/js/config.js (previews are shown while it is empty) -->
<script src="../assets/js/config.js"></script>
<script src="../assets/js/chart_maps/map-google.js"></script>

map-google.js does nothing while googleMapsApiKey is empty, so the previews stay. With a key, it adds Google's documented script tag:

<script
  async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_KEY&libraries=marker&loading=async&callback=admindekInitGoogleMaps&v=weekly"
></script>

When the API is ready, admindekInitGoogleMaps() builds a map inside each example's .gmap-canvas and adds the is-live class to the example, which hides the SVG preview and the notice.

Adding Your Own Map #

Each example is a block with a data-gmap-example name:

<div class="gmap-example" data-gmap-example="office">
  <div class="gmap-canvas"></div>
  <!-- optional: an <svg class="map-preview-svg"> preview and a .gmap-notice for visitors without a key -->
</div>

Add a builder with the same name to the builders object in map-google.js:

var builders = {
  // ...basic and marker examples...
  office: function (el) {
    new google.maps.Map(el, {
      center: { lat: 51.5072, lng: -0.1276 },
      zoom: 13
    });
  }
};

Security Checklist #

• ✅ Restrict the key by HTTP referrer and to the Maps JavaScript API only
• ✅ Keep separate keys for development and production if your team shares a repository
• ❌ Never commit a real key to a public repository. Keep googleMapsApiKey empty in version control and set it at deploy time
• ✅ Set a quota or budget alert in the Cloud console so a leaked key cannot run up costs

Troubleshooting #

The preview is still shown after adding the key

• Check that the built site has the key: open assets/js/config.js in the browser and confirm googleMapsApiKey is not empty.
• Hard-refresh the page to bypass the browser cache.

The map area is grey or shows "This page can't load Google Maps correctly" Open the browser console. Google reports the cause by name:

Console shows "Google Maps could not be loaded: check googleMapsApiKey in assets/js/config.js." The script request itself failed (blocked by an extension, offline, or a malformed key). Check the Network tab for the maps.googleapis.com request.

The marker example loads but the marker is missing Advanced markers need a valid Map ID. Use DEMO_MAP_ID or a Map ID from the same Cloud project as the key.

Summary #

• Without a key, chart/map-gmap.html shows static previews and makes no requests to Google
• Add your key in src/assets/js/config.js (or assets/js/config.js on a built site) to get interactive maps
• Restrict the key by HTTP referrer and never commit a real key
• The vector maps need no key