Mapping a spreadsheet of locations usually means sending every address to an online geocoding API — which is a privacy problem for customer, patient, or supplier lists. This tool instead carries an embedded gazetteer of major cities and country centroids, so it adds coordinates to your CSV entirely in your browser with no API call.
How it works
For each data row the geocoder runs a small matching pipeline:
- Normalize the city value (lowercase, collapse whitespace) and, if present, resolve the country column to an ISO country code, accepting names and common aliases like
UKorUSA. - City lookup. It searches the embedded city table, preferring a match in the stated country so that cities sharing a name are disambiguated.
- Country fallback. If no city matches, it returns the centroid (approximate geographic center) of the country. If even that fails, the row is marked
none.
It appends three columns — lat, lon, and geo_match — and produces a valid RFC 4180 CSV you can copy out.
Example
A row Acme Ltd, London, United Kingdom resolves to approximately 51.51, -0.13 with geo_match = city. A row whose city is unknown but whose country is Armenia falls back to the Armenia centroid with geo_match = country. A row like Atlantis, Nowhere yields empty coordinates and geo_match = none.
When offline geocoding is the right tool
Online geocoding APIs — Google, HERE, Mapbox, and others — are excellent for precise street-level results, but they have two drawbacks that make offline geocoding preferable for certain tasks:
Privacy. Every address you send to an external API becomes part of that company’s request logs, even if they commit to not storing it. For customer records, patient lists, supplier addresses, or research data, transmitting the list to a third party may be restricted by privacy regulations or internal policy. An offline geocoder eliminates this risk entirely.
Cost and rate limits. APIs typically charge per geocoded address and impose per-minute rate limits. Enriching a list of 50 000 customer cities through a paid API requires quota planning and can incur meaningful costs. This tool adds coordinates to the entire file instantly, for free, regardless of size.
The trade-off is accuracy: the embedded gazetteer covers major metros and capitals. Smaller towns may not match and fall back to the country centroid.
Understanding the geo_match column
| Value | Meaning |
|---|---|
city | The city name was found in the embedded city table, possibly scoped to the stated country |
country | No city match; the country centroid was used instead |
none | Neither the city nor the country could be identified |
The geo_match column lets you filter by confidence in your next step. For a choropleth map by country, country matches are perfectly usable. For clustering by metro area, you may want to exclude or manually fix country-matched rows before plotting.
Improving match rates
- Add a country column. Cities with common names — Lincoln, Victoria, Springfield — exist in dozens of countries. Without a country column the geocoder picks the most prominent match, which may be wrong. With a country column it preferentially matches in the stated country.
- Normalise names before pasting. The gazetteer uses normalised name forms. Names with unusual diacritics, historical spellings, or unofficial abbreviations may not match directly; correcting them in your source before geocoding improves the hit rate.
- Use the country fallback deliberately. For country-level analysis, a
geo_match = countryrow is just as useful as a city match — the centroid places the marker in the right country, which is all a world map view requires.
Notes
Because the dataset is embedded and compact, this is a regional-scale geocoder: ideal for clustering customers by metro, plotting a country breakdown, or sanity-checking a list — not for routing to a doorstep. The big advantage is that your address data never leaves the browser, making it safe for sensitive lists that an online API would expose.