My Geocode

Guides

Add a distance-from-store calculator to a landing page

· 3 min read · My Geocode · #forward-geocoding#distance#landing-page#retail

"How far is your nearest location from me" is a question a landing page can answer directly instead of sending a visitor off to a separate map to figure out themselves.

Geocoding the visitor's input

Take whatever address or postal code the visitor types into a simple form field and geocode it.

GET /v1/forward?q=350 Fifth Avenue, New York&limit=1
{
  "status": "ok",
  "results": [
    {"formatted": "350 Fifth Avenue, New York, NY", "lat": 40.7484, "lon": -73.9857, "type": "address", "precision": "house", "confidence": 0.96, "place_id": "es234", "components": {}}
  ]
}

Calculating distance to each store

With the visitor's coordinates in hand, calculate the straight-line distance from that point to each of your store locations, which you keep as a fixed list of coordinates in your own code, using a standard haversine formula.

for store in stores:
    store.distance_km = haversine(store.lat, store.lon, 40.7484, -73.9857)

Showing the result

Sort your store list by the calculated distance and show the closest one, or the closest few, along with the distance figure. Since this all runs server-side on form submission, there is no need for any client-side script, the page simply renders the result on the next page load.

A second example: showing the three nearest instead of one

Rather than reporting only the single nearest store, sorting the full list and showing the top three gives the visitor a genuine choice, particularly useful when the very nearest store might have different hours or stock than a slightly farther one the visitor would actually prefer. This costs nothing extra, since the sort happens against the same coordinates from the same single request.

Handling a low-confidence match

If the visitor's typed address comes back with a low confidence score, show the formatted result back to them for confirmation before running the distance calculation, rather than confidently reporting a distance based on a guess about what they meant.

A common mistake to avoid

Do not run the distance calculation against a query that resolved at a much coarser precision than the visitor probably intended, such as a bare city or region name matching a "locality" type result, without flagging that to the visitor first. A distance calculated from a city center rather than the visitor's actual street can be off by several kilometers in either direction, enough to change which store looks nearest. Checking the precision field before reporting a confident-sounding distance figure avoids presenting a rough estimate as an exact one.

Letting the visitor pick among ambiguous matches

Raising limit above 1 on the geocoding request returns several candidate matches when the typed input is genuinely ambiguous, such as a street name that exists in more than one town. Showing that short list and letting the visitor pick the right one before running the distance calculation is a better outcome than silently committing to whichever candidate happened to rank first.

What it costs

Each calculation is one geocoding request, regardless of how many stores you compare the resulting coordinates against, since the store list itself does not require any further API calls once you have the visitor's coordinates. A landing page with meaningful traffic still uses this feature at a rate of one request per visitor calculation, well inside the 2,500 free requests a day included with every key.

A distance calculator like this answers a specific, common question directly on the page instead of pushing the visitor elsewhere to find out. Full request parameters are on the forward geocoding docs.

More in Guides