offline-city-search

Offline, zero-latency city search for Node.js using an embedded SQLite database.

What It Is

offline-city-search ships with a prebuilt cities.db (GeoNames-based SQLite database) and exposes synchronous lookup APIs:

• prefix city search (searchCity)
• lookup by city id (getCityById)
• nearest-city by coordinates (getNearestCity)

Runtime Support

• Node.js only (uses built-in node:sqlite)
• Requires Node.js >= 22.5.0
• Tested on Node.js 22 and 25
• Not intended for direct browser/frontend bundling
• Typical usage: call from your backend API and return results to frontend clients

Installation

npm install offline-city-search

Package note:

• Includes a prebuilt SQLite file (cities.db)
• Current tarball size is around 13-14MB (compressed)

Compatibility Notes (Important)

offline-city-search uses the built-in node:sqlite module (no native npm addon required). This avoids most install-time native binary issues.

Recommended for most users:

• Use Node.js LTS (22)
• Keep local and CI Node versions consistent

# with nvm
nvm install 22
nvm use 22
rm -rf node_modules package-lock.json
npm install

If your project must run on a newer Node major:

• Validate behavior in CI before release
• Keep this package in server-only runtime paths

Usage

import { searchCity, getCityById, getNearestCity } from "offline-city-search";

const top = searchCity("mum", { limit: 5, countryCode: "IN" });
const city = getCityById(1275339); // Mumbai
const near = getNearestCity(19.07283, 72.88261);

API

searchCity(query, options?)

• query: string prefix text (case-insensitive behavior via normalized ASCII-lower field)
• options.limit?: number max rows, default 5
• options.countryCode?: string ISO alpha-2 code, e.g. "IN"

Returns: City[]

getCityById(id)

• id: number GeoNames id

Returns: City | null

getNearestCity(lat, lng)

• lat: number
• lng: number

Returns: City | null

City

interface City {
  id: number;
  name: string;
  asciiName: string;
  state: string;
  countryCode: string;
  lat: number;
  lng: number;
  timezone: string;
  population: number;
}

Data Source

GeoNames cities1000 + admin1CodesASCII (state/province mapping):

• https://www.geonames.org/
• License: CC BY 4.0

Rebuilding Database (Maintainers)

npm install
npm run build:db
npm run build

The build pipeline:

• downloads GeoNames files
• inserts rows in batches
• creates indexes
• runs ANALYZE, integrity check, and VACUUM

Publish Checklist

See PUBLISHING.md.

License

MIT