Super efficient, lazy-loaded library for converting US ZIP Codes (ZCTAs) to latitude and longitude.
npm install zip-coords-us
convert() function is called for the very first time, minimizing application startup time and memory footprint.
bash
npm install zip-coords-us
``
$3
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:
`html
`
-----
π Usage
$3
Require the package and destructure the convert function:
`javascript
// 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});
`
$3
After loading the script via CDN, the function is available globally under the variable name ZipCoordsUS.
`html
`
-----
π API Reference
$3
| 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
$3
We welcome contributions\! Please feel free to submit issues or pull requests to improve the library or update the data.
$3
Distributed under the ISC License. Copyright (c) 2025 Shishir Raven.
``