Offline city and place search
canvas-globe/places is an optional browser-side place index. It contains 6,772 populated places across 226 countries, including every national and admin-1 capital in the source data.
It makes no network request and needs no geocoding API key.
import { searchPlaces, placePoint } from "canvas-globe/places";
searchPlaces("sao paulo", { limit: 5 });
// [{ name: "Sao Paulo", country: "BR", lon, lat, population, label, ... }]
placePoint("Ahmedabad");
// { lon: 72.58, lat: 23.03 }
API
| Export | Purpose |
|---|---|
searchPlaces(query, options) | Returns ranked matching places |
placePoint(name, options) | Returns one coordinate or null |
placeSource(options) | Creates a resolver for searchAndFly() |
placeCount() | Returns the bundled place count |
fold(text) | Lowercases text and removes accents for matching |
Ranking and filtering
Prefix matches are returned before substring matches, then ordered by population. Use a country code when the same city name exists in several countries.
searchPlaces("springfield", { country: "US", limit: 10 });
searchPlaces("york", { contains: false });
Accent folding works in both directions. A visitor can type sao paulo for Sao Paulo or zurich for Zurich without matching the exact accents in the dataset.
Connect search to the globe
import { searchAndFly } from "canvas-globe/controls";
import { placeSource } from "canvas-globe/places";
const unbind = searchAndFly(globe, input, {
source: placeSource({ limit: 8, contains: true }),
zoom: 3,
});
Package size and data source
The place module is about 94 KB gzipped and is not part of the core entry point. Import it only when broader city search is needed. The data is generated from Natural Earth populated places, a public-domain source. See the package's THIRD_PARTY_NOTICES.md for source details.
For a much larger village-level index, provide your own asynchronous source to searchAndFly() instead of shipping it to every browser.