Place search, served as files
Every town and city, one small file away.
Town and city search without an API. The whole index is static JSON on a CDN, so there is no key, no rate limit and nothing to run.
Install
Add it to your page
The client library is hosted next to the data. Import it straight from
geo.chofter.com: it is about 2 KB compressed and has no dependencies.
- 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 at
geo.chofter.com/geo.d.ts.
<script type="module">
import { createGeo } from "https://geo.chofter.com/geo.js";
const geo = createGeo({ baseUrl: "https://geo.chofter.com/v1" });
const places = await geo.search("IE", "dub");
// [{ name: "Dublin", region: "Leinster", country: "Ireland",
// lat: 53.3331, lng: -6.2489, label: "Dublin, Leinster, Ireland" }, …]
</script>
Not using modules? Load the classic script instead. It adds one global, choftergeo.
<script src="https://geo.chofter.com/geo.global.js"></script>
<script>
var geo = choftergeo.createGeo({ baseUrl: "https://geo.chofter.com/v1" });
geo.search("IE", "dub").then(function (places) {
console.log(places[0].label, places[0].lat, places[0].lng);
});
</script>
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.
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.