pincodes-finder

Lookup city, district, state and country by postal code (PIN/ZIP/postcode) for 🇮🇳 India, 🇺🇸 US, 🇬🇧 UK, 🇨🇦 Canada, 🇦🇺 Australia, 🇩🇪 Germany and 🇫🇷 France — offline, zero dependencies.

Data is bundled at build time from GeoNames, so lookups are fully local (no network calls).

Install

npm install pincodes-finder

Requires Node.js 16+. This is an ES Module package (import, not require).

Usage

import { lookup, lookupByCountry } from "pincodes-finder";

// Auto-detect the country
lookup("110001");
// → {
//     pincode: "110001",
//     city: "Patiala House",
//     district: "Central Delhi",
//     state: "Delhi",
//     country: "India"
//   }

// Target a specific country (faster — skips the other datasets)
lookupByCountry("90210", "us");
// → { pincode: "90210", city: "Beverly Hills", district: "Los Angeles",
//     state: "California", country: "United States" }

// Unknown code → null
lookup("00000"); // → null

Notes

• Input is normalized (trimmed, upper-cased, spaces stripped), so "sw1a 1aa", "SW1A1AA" and "SW1A 1AA" are treated the same.
• UK data uses GeoNames outward codes only (e.g. "BN91", "M9"), not full postcodes like "SW1A 1AA".

API

lookup(pincode)

Searches all countries (India → US → UK → Canada → Australia → Germany → France) and returns the first match, or null if none. Because some numeric codes are valid in more than one country (e.g. 75001 is both a US ZIP and a Paris postcode), auto-detect returns the first match in that order — use lookupByCountry when you know the country.

• pincode — string (required). Throws if empty or not a string.
• Returns { pincode, city, district, state, country } | null.

lookupByCountry(pincode, country)

Searches a single country's dataset. Faster when you already know the country.

• pincode — string (required).
• country — one of "india", "us", "uk", "canada", "australia", "germany", "france" (case-insensitive). Throws on an unknown or missing country.
• Returns { pincode, city, district, state, country } | null.

Rebuilding the data (maintainers)

The datasets in src/data/ are generated from GeoNames zips in scripts/:

npm run build:data

This extracts each *.zip and regenerates src/data/<country>.js. To refresh the data, download the latest country zips from https://download.geonames.org/export/zip/ into scripts/ first.

License

MIT