zip-coords-us

A super-efficient, lightweight, and lazy-loaded JavaScript library for converting 5-digit US ZIP Codes (ZCTAs) to their central latitude and longitude coordinates.

The library is compatible with Node.js (via NPM) and Vanilla JavaScript (via CDN). It uses a pre-indexed JSON map for O(1) lookup time, ensuring near-instantaneous retrieval after the first load.

✨ Features

• ⚡ O(1) Lookup Speed: Uses a JSON dictionary where the ZIP code is the key, allowing for instant access once the map is loaded.
• 😴 Lazy Loading: The data map is only loaded from the file into memory when the convert() function is called for the very first time, minimizing application startup time and memory footprint.
• 📦 Dual Compatibility: Works as a CommonJS module in Node.js and as a global variable script via CDN.
• 🗺️ ZCTA Based: Coordinates are derived from U.S. Census Bureau ZCTAs (ZIP Code Tabulation Areas).

⬇️ Installation

1. For Node.js / Module Bundlers

Install via npm:

npm install zip-coords-us

2. For Vanilla JavaScript / CDN

You can load the minified file directly in your HTML via a CDN (like Unpkg or jsDelivr), making the library available as the global variable ZipCoordsUS:

<script src="[https://unpkg.com/zip-coords-us/dist/zip-coords-us.min.js](https://unpkg.com/zip-coords-us/dist/zip-coords-us.min.js)"></script>

🚀 Usage

1. Node.js / NPM Module

Require the package and destructure the convert function:

// index.js (Node.js)

const { convert } = require('zip-coords-us');

// First call loads the data, subsequent calls are instant
const coords = convert('10001'); 
console.log(`ZIP 10001: Lat ${coords.latitude}, Lng ${coords.longitude}`);

2. CDN / Vanilla JavaScript

After loading the script via CDN, the function is available globally under the variable name ZipCoordsUS.

<script>
    // Access the convert method from the global variable
    const coords = ZipCoordsUS.convert(90210);

    if (coords) {
        console.log(`ZIP 90210: Lat ${coords.latitude}, Lng ${coords.longitude}`);
    } else {
        console.log("ZIP code not found.");
    }
</script>

📚 API Reference

convert(zip_code)

| Parameter | Type | Description | | :--- | :--- | :--- | | zip_code | string or number | The 5-digit US ZIP code (will be padded with zeros if necessary, e.g., 601 becomes "00601"). |

| Returns | Type | Description | | :--- | :--- | :--- | | Found | object | { latitude: number, longitude: number } | | Not Found | null | Returns null if the ZIP code is not in the map. |

🛠️ Data Source & Methodology

The underlying JSON data map (us_zip_to_coords_map.json) was generated from the U.S. Census Bureau's ZCTA Gazetteer Files.

If you wish to download the raw CSV file to update the library's data yourself, you can find the files at the official source page:

👉 Download the ZCTA Gazetteer File CSV/TXT (U.S. Census Bureau)

Note on ZCTAs: The Census Bureau uses ZIP Code Tabulation Areas (ZCTAs) for statistical mapping, which are approximations of the general boundaries of USPS ZIP Codes.

🤝 Contributing & License

Contributing

We welcome contributions! Please feel free to submit issues or pull requests to improve the library or update the data.

License

Distributed under the ISC License. Copyright (c) 2025 Shishir Raven.