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 last two 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 |
| Distance Matrix API (legacy) | The driving distance and drive time on each result, and ordering the results by drive time | Drive times |
| Directions API (legacy) | The route drawn on the map and the turn-by-turn steps behind Get Directions | In-page directions |
Google no longer offers the two legacy services to new Google Cloud projects. A project that doesn't list them in its API Library can't enable them, and the Store Locator then 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." |
| Distance Matrix API | Results appear nearest first, by straight-line distance, with straight-line miles and no drive times. |
| Directions API | 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 legacy Distance Matrix or Directions API is not enabled, which is expected on a new project |
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 Distance Matrix request for their drive times. 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 Directions request per route.
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.