My Geocode

Guides

Build a simple "nearest office" finder

· 3 min read · My Geocode · #forward-geocoding#distance#office-locator

A company with a handful of offices does not need anything elaborate to answer "which office is closest to me," just one geocoding request and a short comparison against a list that rarely changes.

Geocoding the input

Whether the visitor types an address or a postal code, geocode it to get coordinates.

GET /v1/forward?q=Berlin, Germany&limit=1
{
  "status": "ok",
  "results": [
    {"formatted": "Berlin, Germany", "lat": 52.5200, "lon": 13.4050, "type": "locality", "precision": "city", "confidence": 0.85, "place_id": "bl456", "components": {"city": "Berlin", "country": "DE"}}
  ]
}

Comparing against your office list

Keep your office coordinates as a small fixed list in your own code or configuration, since this rarely changes and does not need a lookup of its own each time.

offices = [
  {"name": "Berlin", "lat": 52.5170, "lon": 13.3888},
  {"name": "Paris", "lat": 48.8566, "lon": 2.3522},
  {"name": "London", "lat": 51.5074, "lon": -0.1278}
]

Calculate distance from the visitor's coordinates to each office using a standard haversine formula, then sort by distance and return the closest match.

A second example: adding a type-ahead field

Instead of a plain text box, backing the location field with /v1/autocomplete lets the visitor pick from suggested places as they type, reducing the chance of a typo producing an unexpected geocoding result. Once a suggestion is selected, resolving its place_id or its text through the same forward geocoding flow feeds straight into the same distance comparison already described.

Handling a city-level match

Notice the precision in the example above is "city" rather than "house", since the visitor only entered a city name. That is fine for an office finder, where the goal is picking the nearest office out of a handful of options, not pinpointing an exact building. A coarser precision here does not need special handling the way it might for a delivery address.

A common mistake to avoid

Do not forget to update the fixed office list in your own code when a physical office opens, closes, or moves. Because the list lives in your own configuration rather than in the API, it is easy for it to quietly go stale, silently pointing visitors toward a closed location or leaving a new one out of every comparison entirely. Treat that list as part of your regular content review, not a one-time setup step.

An edge case: an ambiguous place name

A short place name can occasionally match more than one real location, such as a place name shared between a country and an unrelated region elsewhere. Passing the countries parameter to restrict candidate matches to the countries where you actually operate offices avoids this kind of ambiguity resolving to the wrong side of the world entirely.

Displaying more than just the nearest one

Showing the two or three closest offices, rather than only the single nearest one, gives a visitor near a regional boundary the chance to pick the one that actually suits them, such as one with a language or time zone that fits better even if it is a little farther by distance.

What it costs

Each search is one geocoding request. The comparison against your office list happens entirely in your own code afterward and adds nothing further to your request count. A page like this, even with steady traffic, stays well inside the 2,500 free requests a day included with every key.

A nearest office finder built this way needs exactly one request per visitor search, with the actual comparison logic living entirely on your side. Details on the request format are in the forward geocoding docs.

More in Guides