Store Locator Google Maps Services

Overview

The Store Locator page calls four Google Maps services through your Google Maps API key. Each one powers a different part of the page, and the page keeps working when some of them are missing: it falls back to a simpler result instead of breaking. This page lists what each service does, what shoppers see without it, and the message the browser's developer console shows, so you can match a symptom to its cause.

Setting up the key itself is covered in Connect Google Maps.

Services the Store Locator uses

The page needs the first two services for its core job, and the Routes API for drive times and directions. The names are the ones in the Google Cloud console's API Library.

Google Cloud API	What the Store Locator uses it for	Needed for
Maps JavaScript API	The map, the location markers and the "You are here" marker	Everything on the page
Geocoding API	Turning a typed ZIP code or address into a map position, and turning the shopper's shared location into the ZIP code or city shown in the search box	Searching by ZIP code or address
Routes API	The driving distance and drive time on each result, ordering the results by drive time, and the route and numbered turn-by-turn steps behind Get Directions	Drive times and in-page directions
Distance Matrix API and Directions API (legacy)	The same drive times and directions, on an older project where they are enabled and the Routes API isn't	Older projects only

The Store Locator asks the Routes API first. If the project refuses it, the Store Locator asks the legacy service once, then uses whichever one answered for the rest of the visit. Google no longer offers the legacy services to new Google Cloud projects, so a new project needs the Routes API for drive times and directions. Without either, the Store Locator runs with the fallbacks below.

The page also loads Google's places library, but the Store Locator never calls the Places API, so the Places API is not needed. The Places API key used for checkout address autocomplete is a separate setting.

What shoppers see when a service is unavailable

A service counts as unavailable when it is not enabled on the project, not allowed on the key, refused by Google, or doesn't answer. The page waits about 5 seconds for an answer before it falls back.

Unavailable	What the shopper sees
The whole key (no key on your own domain, an invalid key, billing off, or the page's address not allowed)	The map area shows Google's "Oops! Something went wrong" message. The results list still appears after about 5 seconds, nearest first, with straight-line miles. With the shopper's location shared, the search runs from there, but the search box stays empty. A typed address shows "Unable to determine the location of the address you entered. Please adjust your search above."
Geocoding API	The map and markers work. With the shopper's location shared, the search runs from there, but the search box is not filled in. A typed ZIP code or address shows "Unable to determine the location of the address you entered. Please adjust your search above."
Routes API (and no legacy Distance Matrix)	Results appear nearest first, by straight-line distance, with straight-line miles and no drive times.
Routes API (and no legacy Directions)	Get Directions keeps the markers on the map and shows "Directions aren't available here." with an Open in Google Maps link. The link opens Google Maps driving directions from the shopper's search point to the location in a new tab, with no key needed.

Dragging the "You are here" marker needs only the Maps JavaScript API, so it keeps working without the other three.

Console messages

Each unavailable service leaves a recognizable message in the browser's developer console.

Console message	Cause
RefererNotAllowedMapError	The key's website restriction doesn't include the address the page is on, or the pattern lacks the /* path wildcard
InvalidKeyMapError	The key in the Store Locator settings is not a valid key
This API key is not authorized to use this service or API	The service is enabled on the project but not ticked in the key's API restrictions
Geocoding Service: This API is not activated on your API project	The Geocoding API is not enabled on the key's project
You're calling a legacy API, which is not enabled for your project (from the Distance Matrix or Directions Service)	The Routes API was refused, and the legacy Distance Matrix or Directions API is not enabled either. Enable the Routes API
Store locator: the Routes API distance request failed … Routes API has not been used in project … or it is disabled	The Routes API is not enabled on the key's project. On an older project that has the legacy services, drive times and directions still work through them
Store locator: the Routes API distance request failed … Requests to this API routes.googleapis.com method … are blocked (API_KEY_SERVICE_BLOCKED)	The Routes API is enabled on the project but not ticked in the key's API restrictions. Add it to the key. As above, the legacy services take over if they're enabled
REQUEST_DENIED	Google refused the request; the message beside it names the reason
Deprecation warnings for DirectionsService, DirectionsRenderer, DistanceMatrix or Marker	Google's notice that these will be replaced. They don't affect how the page behaves.

Requests per search

One search makes one Geocoding request (for a typed ZIP code or address), one request to UltraCart for the matching locations, and one drive-time request (Routes API, or Distance Matrix on an older project). Changing only the distance or the number of results reuses the last address lookup, so it makes no new Geocoding request. Get Directions makes one route request per route. On a project with only the legacy services, the first search of a visit also makes one refused Routes API request before it switches to them.

Related

• StoreFront Locations covers adding locations and setting up the Google Maps API key.
• Google Maps Platform pricing lists what Google charges for each service.