postalcode-global

A lightweight, dependency-free utility to validate postal codes and fetch city/state information for supported countries — usable in Node.js, React, Next.js, and browser environments.

🚀 What’s New in v4.0.0 (Breaking Change)

Version 4.0.0 introduces a major architectural improvement.

✅ Removed Python Runtime Dependency Previous versions relied on a Python server (pgeocode) running locally to resolve postal codes. This made the package difficult to use in client-side environments and increased setup complexity. v4.0.0 removes Python entirely.

✅ Preprocessed, Embedded Dataset Postal code data is now: 1. Preprocessed at build time 2. Stored as country-specific JSON files 3. Shipped directly with the npm package This means: 1. No external services 2. No servers 3. No native dependencies 4. Fully deterministic lookups

✅ Client-Side Compatible The package now works out of the box in: React | Next.js | Vite | Node.js | Browser environments

Installation

npm install postalcode-global

or

yarn add postalcode-global

🌍 Supported Countries

You can programmatically check which countries are supported:

import { supportedCountries } from "postalcode-global";

console.log(supportedCountries);
// ["US", "CA", "GB", "AU", ...]

This list is derived from the same dataset used for lookups and validation.

🧩 Usage

1. Fetch Location Details

import { getLocation } from "postalcode-global";

  const result = await getLocation({
    postalCode: "10001",
    country: "US"
  });

  console.log(result);

Example Response

  {
    postalCode: "10001",
    country: "US",
    city: ["New York"],
    state: "New York"
  }

If the postal code is invalid or unsupported:

  {
    postalCode: "00000",
    country: "US",
    error: "No postal code match found for the country"
  }

2. Validate a Postal Code Format

  import { validatePostalCode } from "postalcode-global";

  validatePostalCode({
    countryCode: "CA",
    postalCode: "M5V 3L9"
  }); // true

3. Check if a Country Is Supported

  import { postalCodeExistForCountry } from "postalcode-global";
  postalCodeExistForCountry({ countryCode: "JP" }); // true / false

🧠 How It Works (High Level)

Postal code datasets are sourced from GeoNames Data is normalized and compiled into country-specific JSON files at build time Runtime lookups are fast, synchronous, and deterministic No network calls are made at runtime

📚 Attribution & Data Sources

This project uses postal code data from: GeoNames => https://www.geonames.org/ Data is redistributed in processed form in accordance with their usage guidelines.

See Geonames Database for more information.

Can you contribute?

Yes please.! Please pull a request into the bug/fix branch if you come across any issues in the response, if any regex expression is filtering wrong pattern or anything that needs a fix. If you like to add up a feature or improve an existing feature, please pull a request in the develop branch. Please specify the reason, implementation, reference (if any) and effect of the change in the PR. Thank you and I appreciate your contributions..!