Add a Google Maps API Key

A how-to guide to creating and restricting Google API keys.

We have detailed instructions below, but have also created a couple of outlines depending on if you are going to use

To use your own Google Maps API keys with Bullseye, you must create API key(s) through a Google developers account and enable APIs:

• Google Maps JavaScript API (required)
• Google Maps Geocoding API (required)
• If using Google Reviews or autofill, Google Places API (optional)
• If displaying Driving Distance, Google Distance Matrix API (optional)

API key(s) are required for Bullseye to display the map in the Admin or on an interface and geocode locations during uploads. Since there is potentially a cost associated with Google API keys we recommend creating 2 separate keys and securing each with restrictions to protect them from unauthorized usage. They can be secured with HTTP, IP, and API restrictions. Each key you will need performs a unique function, and requires a specific set of restrictions (if you choose to restrict your keys). The 3 ways a key can be restricted are via:

• HTTP referrers - One of the keys you use can be restricted to specific URLs where the map will be displayed. Bullseye uses the Google Maps Javascript API and the Google Geocoding API with this key to display the map on the Location Details page in the Bullseye Admin and the interface itself, so you would restrict this keys to *.bullseyelocations.com/*, as well as any of your own domains where the map would display. 
• IP addresses - The other key you will need can be restricted to specific IP addresses of the servers that will geocode locations during uploads. Bullseye uses the Google Geocoding API with this key to geocode locations during CSV and XML uploads, so you would restrict this key to our servers at 146.20.85.38 and 146.20.85.39.
• API services - Either key can be further restricted to allow only the Google API services required for the functionality required. For example, for these instructions that are typical for use with Bullseye, we’ll create one key that uses the Google Maps Javascript API and the Google Geocoding API to support displaying maps in the Admin and interface, and one key that uses the Google Geocoding API to support geocoding.

If you choose to use your own keys, we have a summary and detailed instructions below:

API Key Restriction Summary

Instructions

1. Create an Account
2. Create a Project
3. Enable APIs
4. Create API Key(s)
5. Restrict Keys (optional)
6. Add keys to Bullseye

Create an Account

You will need to have a Google account (gmail account) before you create your Developer's account/Cloud Console, which is necessary to create API keys. These instructions assume you have a paid developer's account and have provided billing information, and that you are using a standard Bullseye interface. 

Note:  If you have a trial account, you may upgrade in your Google Cloud Platform Console by clicking on the Activate button on the top of the page.  If you do not see Activate, click Free trial status in the upper-right of the page and Activate will appear. 

You will not be billed unless you exceed the quota for the Javascript API or Geocoding API. (At time of writing, the quota is 28,000 dynamic maps per month for the Javascript API and 40,000 geocodes per month for Geocoding your locations).

See these articles for Billing/Quota information and upgrading your account:

Direct link to Google Cloud Billing page https://console.cloud.google.com/projectselector2/billing/enable?pli=1

https://developers.google.com/maps/documentation/javascript/usage-and-billing

https://developers.google.com/maps/documentation/geocoding/usage-and-billing

https://cloud.google.com/maps-platform/pricing/sheet/

https://cloud.google.com/free/docs/gcp-free-tier#how-to-upgrade

Create a Project

Log in to the Google APIs manager at https://console.developers.google.com/apis with a valid Google account. (You may be asked to accept updated terms of service).

Select New Project:

You will see options to name your project, and choose an organization.  You also have the option of creating a project ID beneath the project name:

You may use the default names or IDs or enter your own.  Select Create when you are done.

When the project is created you’ll get a notification.

Click "View" to go to the Project page. Or click on the Project drop-down any time to select from your available projects:

Enable APIs

On the project page, scroll down and select Explore and enable APIs beneath the Getting Started heading on the left:

If this is the first time you are creating a project, it will say you don't have any APIs available, and you'll see a link to go to the API library.  Select to go to the API library, or select the Library from the API & Services menu from the main navigation.  You will see a page that looks similar to below. You’ll need to enable 2 or 3 APIs. You can find APIs to enable easily by searching for them. To begin,  search for or select Maps JavaScript API:

After selecting an API you'll see a page like this:

Select Enable.  You will see a page like below.  This page will display activity for the API when the API is used with a key.

Return to the API Library to enable the Geocoding API in the same way. Return to the API Library again to enable the Places API if your locator will use Google’s address autocomplete functionality.

Create API keys

The next steps will be to create your credentials (keys), and restrict access (assuming you want to set restrictions) to the Map JavaScript API to support maps for your Bullseye interface and the Admin, and restrict access to the Geocoding API which allow you to get lat/long coordinates for your locations to plot on the map. Optionally, you might restrict access to the Places API which will support Google’s autocomplete functionality. 

Select "Credentials" from the API & Services menu.  You'll see this screen:

Select "Create Credentials."  You will see the following:

Select "API key" from the drop down menu. You will see this screen:

If you don’t plan to restrict your key you can close this popup and you’re done creating keys! See “Add Keys to Bullseye” following “Restrict API Keys” for the next step.  If you want to restrict your keys, you will need to setup 2 API keys - one for mapping and one for geocoding. Repeat the steps above to create a second key. If you are ready to add restrictions now, select “Restrict Key” and continue with the following instructions.

Restrict API Keys (optional)

Google suggests setting restrictions on your key to prevent unauthorized use of your key. First we’ll show you how to set up Website Restrictions for the mapping key.

Website Restrictions

Select Credentials from the APIs & Services menu, then select the key you’ll use for mapping. You’ll see a screen like this:

Under "Application restrictions" select HTTP referrers.  Under Website restrictions, you'll need to enter *.bullseyelocations.com/*.  If you are using a custom locator instead of Bullseye standard Iframe-based, allow requests from the domain of the custom locator, or if your url has a subdomain, you'll need to allow requests from the entire url or use wildcard asteriks.

You don't need to enter https: when you enter these urls.

If you want to further restrict your key by API service, select Restrict Key under API restrictions.  Select the Maps Javascript API and the Geocoding API (and optionally the Places API if your custom locator uses Google’s autocomplete functionality or the Distance Matrix API if you're displaying driving distance on results)under the drop-down under Restrict Key.  Select Save. 

IP Restrictions

Select Credentials from the APIs & Services menu, then select the key you’ll use for geocoding. You’ll see a screen like this:

Under "Application Restrictions" select IP addresses.  You will enter 1 or 2 IP addresses.  Many clients enter locations by uploading them in a CSV file, or by typing them manually into the admin.  If that is the case for you, enter 146.20.85.38 under "Accept Requests from these server IP addresses." If your location maintenance will be done via automation via XML files, or automated through CMS automation with applications like Salesforce.com, then also enter (146.20.85.39) to that key's restriction list. 

Under API restrictions, select Restrict Key, and select the Geocoding API in the drop down menu.

Copy the Key, and select Save at the bottom.

Add Keys to Bullseye

Copy the keys from the Credentials page and paste the first API key we created for mapping under Settings > Set Up > Mapping in your Bullseye account. The key should be pasted in the Mapping API field, beneath the "Use Your Own Mapping" heading, into the Mapping API Key field.  Select "Save" at the bottom of the page.

Paste the second key we created for geocoding into your Bullseye account under Settings > Set Up > Mapping beneath the “User Your Own Mapping” heading, into the GeoCoding API Key field.

One more important step!

Make sure you Upgrade Your Trial Google Account to a Paid Account

It is common that clients will skip this step, and then in a year's time ask why their maps generate an error because they never upgraded their account.  We suggest taking care of this during your initial set up so that this step is not forgotten. Here's Google's instructions for upgrading: https://cloud.google.com/free/docs/gcp-free-tier#how-to-upgrade