chofter/geo

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.

Pick a place
237,212towns, cities and suburbs
246countries
0API keys or rate limits
≤ 25 KBper file, compressed

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.
app.tsnpm install @chofter/geo
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:

index.html
<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.

index.html
<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

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.

sample.tsnpm install @chofter/geo
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

  1. One index per country

    /v1/ie/_.json names the country and lists its files. Most countries are small enough that this one file holds every place.

  2. 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.

  3. 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.

Download the data 8.8 MB, built 18 November 2026

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.json loads.
  • Serving the files from a different origin than your pages? Send Access-Control-Allow-Origin on them.
  • Keep crediting GeoNames: the data is licensed CC BY 4.0.

Then pass your own baseUrl. That is the only change:

app.ts
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:

update.sh
curl -fLO https://geo.chofter.com/chofter-geo-data.zip
rm -rf www/v1 && unzip -q chofter-geo-data.zip -d www/