Gksoft

Google Maps API Setup Guide

Google Maps API Key Setup & Domain Restriction Guide

This section provides the same guide in English for international customers using GKSoft plugins such as CityCourier and Executive VIP Transfer Service.

1. Introduction

With this guide, you can:

  • Create a Google Maps API Key
  • Enable required Google Maps APIs
  • Restrict the key by domain (HTTP referrers)
  • Understand common errors such as RefererNotAllowedMapError and gm_authFailure

The guide is compatible with:

  • CityCourier – Delivery & Courier Plugin
  • Executive VIP Transfer Service Plugin
  • Address Autocomplete / Places-based integrations
  • Any custom GKSoft solution using Distance Matrix API

2. How to Generate a Google Maps API Key

2.1. Create a Google Cloud Project

  1. Go to https://console.cloud.google.com.
  2. Click on New Project.
  3. Enter a project name (e.g., CityCourier Maps) and click Create.

2.2. Enable Billing

  1. Open the Billing section in the left menu.
  2. Add a payment method (credit card).
  3. Attach your project to this billing account.

2.3. Enable Required APIs

Make sure the following APIs are enabled:

  • Maps JavaScript API
  • Places API (for address autocomplete)
  • Geocoding API
  • Distance Matrix API
  1. Go to APIs & Services → Library.
  2. Search for each API by name.
  3. Click Enable for each one.

2.4. Create Your API Key

  1. Go to APIs & Services → Credentials.
  2. Click Create credentials → API Key.
  3. Copy your newly generated key (AIza...).
  4. Click Restrict key to secure it.

3. Restricting the API Key by Domain (HTTP Referrers)

3.1. Application Restrictions

  1. In the key settings, find Application restrictions.
  2. Select Web sites (HTTP referrers).

3.2. Allowed Referrers

Assuming your domain is example.com, add the following patterns:

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

Tips:

  • Include both www and non-www versions.
  • Use wildcard (*) to cover all pages.
  • Include localhost entries for development environments.

3.3. API Restrictions

  1. Scroll down to API restrictions.
  2. Select Restrict key.
  3. Allow only:
    • Maps JavaScript API
    • Places API
    • Geocoding API
    • Distance Matrix API
  4. Click Save.

4. Common Errors & Fixes

4.1. RefererNotAllowedMapError

If you see this error in the browser console:

RefererNotAllowedMapError: The current URL loading the Google Maps JavaScript API has not been added to the list of allowed referrers...

Possible reasons:

  • Your domain is not added or is added incorrectly.
  • You only added https://www.example.com/*, but the site runs on https://example.com.
  • No wildcard (*) at the end of the URL.

Fix: Add both of the following:

https://example.com/*
https://www.example.com/*

4.2. gm_authFailure

gm_authFailure indicates that Google Maps could not authenticate your key.

  • Check that your API key is valid.
  • Verify domain restrictions.
  • Make sure billing is enabled and active.

5. Recommended Usage for GKSoft Plugins

  • Add a “Google Maps Setup Guide” link in the plugin settings page.
  • Share this documentation URL with your customers for quick setup.
  • Include this page in your public Documentation / Help menu.