postalcode-geocode

Resolve global postal / ZIP codes to latitude, longitude, and IANA timezone using GeoNames data.

The npm package is small. On first use (or postalcode-geocode setup) it downloads the GeoNames postal dump (~19 MB), builds a local SQLite cache, then works offline.

Install

npm install postalcode-geocode

Requires Node.js ≥ 18 (uses better-sqlite3 for the local postal cache).

Setup

npx postalcode-geocode setup

Or the first lookupPostalCode() call will download automatically.

Data directory:

• Windows: %LOCALAPPDATA%\postalcode-geocode\
• macOS/Linux: ~/.cache/postalcode-geocode/
• Override: POSTALCODE_GEOCODE_DATA_DIR

Usage

import { lookupPostalCode, toHebcalLocation } from 'postalcode-geocode';

const place = await lookupPostalCode('10952');
// {
//   postalCode: '10952',
//   countryCode: 'US',
//   placeName: 'Monsey',
//   admin1: 'New York',
//   latitude: 41.11…,
//   longitude: -74.08…,
//   tzid: 'America/New_York',
//   accuracy: …
// }

// Optional: convert for @hebcal/core zmanim
import '@hebcal/core'; // peer dependency
const location = await toHebcalLocation(place);

API

| Function | Description | |----------|-------------| | lookupPostalCode(code, countryCode?) | Look up a postal/ZIP. US 5-digit codes work without country. | | ensureData({ force? }) | Download + build cache | | getDataPath() / dataReady() | Cache location / readiness | | toHebcalLocation(result) | Build @hebcal/core Location (optional peer) |

CLI

postalcode-geocode setup
postalcode-geocode lookup 10952
postalcode-geocode lookup SW1A GB
postalcode-geocode path

Attribution

Postal code data © GeoNames under CC BY 4.0. Please credit GeoNames if you use this package.

Timezone resolution via geo-tz.

Notes

• UK / Canada / Netherlands entries in allCountries.zip may be outward codes only (not full unit-level postcodes). See the GeoNames postal readme.
• Coordinates are estimates from GeoNames (accuracy field 1–6).