Free place search, served as files
Every town and city, one small file away.
Free town and city search with no usage limits. The whole index is static JSON on a CDN, so there is no sign-up, no key, no rate limit, nothing to run and nothing to pay.
Install
Add it to your page
Install @chofter/geo from npm. It is about 1.5 KB compressed, has no
dependencies and reads the data from geo.chofter.com.
- Ask for a country first, then pass along what the user types.
- Each result has a name, region, country, latitude and longitude.
- Files are cached by the browser, so most keystrokes need no request.
- TypeScript types are included in the package.
import { createGeo, type Place } from "@chofter/geo";
const geo = createGeo();
const places: Place[] = await geo.search("IE", "dub");
// [{ name: "Dublin", region: "County Dublin", country: "Ireland",
// lat: 53.3331, lng: -6.2489, label: "Dublin, County Dublin, Ireland" }, …]
No build step? Import the module straight from
geo.chofter.com:
<script type="module">
import { createGeo } from "https://geo.chofter.com/geo.js";
const geo = createGeo();
const places = await geo.search("IE", "dub");
</script>
Not using modules? Load the classic script instead. It adds one global,
choftergeo.
<script src="https://geo.chofter.com/geo.global.min.js"></script>
<script>
var geo = choftergeo.createGeo();
geo.search("IE", "dub").then(function (places) {
console.log(places[0].label, places[0].lat, places[0].lng);
});
</script>
Limitations
What it does not do
-
Places, not streets
It finds towns, cities and suburbs. It does not know streets, house numbers, postcodes or businesses, so it cannot turn a full address into a point on the map. For that, use a street-level geocoding service.
-
One country at a time
Every search is within a single country, such as
geo.search("IE", "dub"). There is no worldwide search, so ask the user for their country first, or preselect it from their locale.
Code samples
Use it from anything that can fetch a file
In the browser, use the library. Everywhere else the scheme is small enough to write inline: read the country index, pick the longest listed prefix, filter.
import { createGeo, type Place } from "@chofter/geo";
const geo = createGeo(); // reads https://geo.chofter.com/v1
// Country first (ISO code), then whatever the user has typed so far.
const places: Place[] = await geo.search("IE", "dub", { limit: 3 });
for (const place of places) {
console.log(place.label, place.lat, place.lng);
}
// Dublin, County Dublin, Ireland 53.3331 -6.2489
How it works
A naming scheme instead of a server
-
One index per country
/v1/ie/_.jsonnames the country and lists its files. Most countries are small enough that this one file holds every place. -
Busy prefixes get their own file
Large countries are split by the first letters of the name, only as deep as needed:
/v1/us/sa.json,/v1/fr/saint-m.json. -
The client filters locally
It fetches the longest listed prefix of the query, then matches and ranks by population in memory. Accents and local-language names are handled.
Host it yourself
Prefer your own copy? Take it with you.
Because the whole index is plain files, you can serve it from your own domain just as easily as from ours. Download the latest build, put it on any static host or CDN, and point the library at it. Your code stays exactly the same.
A snapshot, not a subscription. The zip is the data as it stood on the day it was built. We rebuild from GeoNames every month, but your copy won't update itself, so download a fresh one from time to time to pick up new places and corrections. The link above always points to the latest build.
-
Unzip it into the root of your site, so that
/v1/countries.jsonloads. -
Serving the files from a different origin than your pages? Send
Access-Control-Allow-Originon them. - Keep crediting GeoNames: the data is licensed CC BY 4.0.
Then pass your own baseUrl. That is the only change:
import { createGeo } from "@chofter/geo";
const geo = createGeo({ baseUrl: "https://example.com/v1" });
To stay current, refresh your copy on a schedule, say once a month:
curl -fLO https://geo.chofter.com/chofter-geo-data.zip
rm -rf www/v1 && unzip -q chofter-geo-data.zip -d www/