A visitor lands on your locations page with one question in their head: which one of these is closest to me? A lot of HubSpot sites answer it with a column of addresses and a quiet hope that the reader knows their own geography well enough to work it out.
They usually don't. They open a map app in another tab, paste in three of your addresses, compare, and half of them give up somewhere in the middle of that.
A store locator closes that gap. It is one of those features that looks like a small design job and turns out to be four separate technical decisions wearing a trench coat. Here is what each of them is, and how to get them right on HubSpot CMS.
What does a store locator have to do?
Strip away the styling and the job comes down to four things:
- Show every location on a map, with a marker a visitor can click.
- Narrow the list — by search term, by category, or by distance from wherever the visitor is standing.
- Sort by nearest, and say how far each one is in a unit the visitor recognises.
- Hand the visitor off to whichever navigation app they already use, with the destination filled in.
Everything else — photographs, opening hours, a phone number, a note about parking — is detail hung on that frame. Get the frame wrong and no amount of detail rescues it.
Where should the location data live?
This is the first fork in the road, and it decides who can update your locations later.
HubDB is the answer most developers reach for. A table of locations, one row each, rendered through HubL. It works, and it is the right call when you have hundreds of locations, or when the list is fed by another system. It has two costs: HubDB needs Content Hub Professional or Enterprise, and every edit means someone opening a database table rather than a page. If that person is a marketer with twelve locations to keep current, you have handed them a chore they will avoid.
A CRM object makes sense when locations are already records your sales team maintains. Same tradeoff, heavier.
Editor rows inside the module means the locations live on the page itself. Someone opens the page editor, clicks add, fills in a name and an address, and publishes. No table, no permissions conversation, no developer. That is the right shape for the case most businesses are in — a couple of dozen locations that change a few times a year.
Be honest about which situation you are in before you build. A shop chain with four hundred branches and a nightly feed wants HubDB. A clinic group with nine sites wants the rows on the page. Building the first shape for the second situation is how a locator ends up out of date within a year.
Every location needs a latitude and longitude
Here is the part that catches people out. A map cannot draw a pin from a street address. It needs coordinates, and turning one into the other is called geocoding.
You have two options, and only one of them is sensible for a fixed list of shops.
Geocode at page load and every visitor triggers a lookup for every address, every time. You pay for it, it is slow, and it can fail silently and leave your map empty.
Geocode once, by hand, and store the result. Open a map, right-click your shop, copy the two numbers, paste them into the location. It takes about twenty seconds per site, you do it once, and it never costs anything again. For a list that changes a few times a year this is simply the correct answer.
Store the coordinates alongside the human-readable address. The address is what the visitor reads on the card. The coordinates are what the map, the distance sort and the directions link all run on.
Do you need a Google Maps API key?
If you want the map to look like Google Maps, yes — your own key, from your own Google Cloud project.
Two things people skip, and regret:
- Restrict the key to your own domains. An unrestricted key sitting in your page source is a key anyone can lift and spend against your billing account.
- Set a daily quota cap. This is the difference between a surprise and a capped surprise.
On cost: Google's Dynamic Maps allowance covers 10,000 map loads a month at no charge, and it is $7.00 per 1,000 after that. Billing has to be switched on for the Cloud project either way, even if you never expect to cross the threshold. For a locations page on a normal business site, staying inside the free allowance is the usual outcome — but you should know the number before you commit, not after.
The alternative is a street map drawn with Leaflet, an open-source mapping library, against a tile provider. Several basemaps draw with no key pasted anywhere under terms written for low-volume use, and a commercial site takes an account with a tile provider. It is the same locations, the same search, the same distance sorting. What changes is the look of the map underneath and who you have an account with.
Whichever you choose, make sure the page degrades sensibly. A locator that renders a grey box because a key expired is worse than one that quietly falls back to a plain map and keeps working. In Store Locator Pro, setting the mode to Google and leaving the key empty draws the street map instead, so a published page always shows something real.
How does "near me" work, and what does it cost you?
The near-me button is the feature that makes a locator feel like a tool rather than a page. The mechanics are simpler than people expect.
The browser has a geolocation API. You ask it for a position, the browser asks the visitor for permission, and if they agree you get a latitude and longitude back. From there you measure the straight-line distance to each of your locations, sort, and render.
Three things decide whether it feels good:
- Handle the refusal. Plenty of people decline, and plenty of browsers time out. Say so in a line of text and leave the list usable. A spinner that never resolves reads as a broken site.
- Offer a radius, then ignore it when it is unhelpful. "Within 10 km" is useful in a city and useless in a rural county. When nothing falls inside the radius, showing the closest few with their real distances beats an empty state that tells someone there is nothing near them.
- Say straight-line distance, and mean it. The number you can calculate in the browser is as-the-crow-flies. Driving distance needs a routing API and a bill attached. Give the honest number, and let the visitor's own map app work out the route.
All of that runs against the locations already rendered on the page, so filtering and sorting cost you nothing and touch no service.
Directions links that open in the right app
The last step is the one people over-engineer. You do not need an integration to send someone to a location. Every major map app accepts a plain URL with coordinates in it:
- Google Maps:
google.com/maps/dir/?api=1&destination=LAT,LNG - Apple Maps:
maps.apple.com/?daddr=LAT,LNG - Waze:
waze.com/ul?ll=LAT,LNG&navigate=yes - OpenStreetMap:
openstreetmap.org/directions?to=LAT,LNG
No account, no key, no SDK. On a phone, these open the installed app directly. Pick the one that matches where your audience is — Apple Maps for a mostly-iPhone consumer audience, Waze in markets where it dominates — and put it on every card.
What breaks on a phone
A locator is a two-panel layout, and two panels do not fit on a phone. This is where most builds fall apart.
The failure mode is a map squeezed to a hundred pixels tall above a list, which is a map you cannot read sitting on top of a list you have to scroll past it to reach. Decide deliberately:
- Does the map or the list come first on a small screen?
- How tall is the map allowed to be, on a phone specifically rather than as a percentage of something?
- Can the visitor collapse the map to get more list, or the other way around?
- Does clicking a card scroll the map into view, or does it silently update a map that is off-screen?
That last one is the bug people ship most often. A visitor taps a location, something happens above the fold they cannot see, and nothing appears to have worked.
A checklist before you publish
- Every location has coordinates, and you have spot-checked three of them against a map.
- The API key is restricted to your domains and has a daily cap.
- The page still renders a map if the key stops working.
- Declining the location permission leaves a usable page.
- An empty search result says something helpful.
- A directions link opens the app you expect, tested on a real phone.
- Tab and arrow keys reach the cards, the filters and the map controls.
- The person who will maintain this has opened it and added a location without calling you.
That last line is the one worth sitting with. The technical decisions above are all reversible. Choosing a data shape that only a developer can edit is the one that quietly decides your locations page will be wrong eighteen months from now.
The visitor's question never changes. Which one of these is closest to me? Everything here is in service of answering it in one screen, without them opening another tab.
Related reading: how to add a mega menu to a HubSpot theme covers the mechanics of installing a standalone module on a theme you did not build, and managing property listings on HubSpot CMS works through the same data-shape decision for a larger, faster-moving set of records.