{"id":47004897,"url":"https://github.com/ikarthikng/zipcodes-us","last_synced_at":"2026-03-11T20:03:31.612Z","repository":{"id":278481484,"uuid":"935745177","full_name":"ikarthikng/zipcodes-us","owner":"ikarthikng","description":"Fast, lightweight US ZIP code lookup library providing city, state, county, and geographic coordinates with TypeScript support","archived":false,"fork":false,"pushed_at":"2025-12-18T20:24:59.000Z","size":1719,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-21T21:56:53.962Z","etag":null,"topics":["geocoding","javascript","nodejs","npm-package","postal-code","postal-codes","typescript","zipcode","zipcodes"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/zipcodes-us","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ikarthikng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-20T00:22:48.000Z","updated_at":"2025-12-18T20:25:02.000Z","dependencies_parsed_at":"2025-04-08T14:31:49.427Z","dependency_job_id":"c7733b1c-059a-49e7-91e6-b00c0691c0e2","html_url":"https://github.com/ikarthikng/zipcodes-us","commit_stats":null,"previous_names":["ikarthikng/us-zipcodes","ikarthikng/zipcodes-usa"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ikarthikng/zipcodes-us","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikarthikng%2Fzipcodes-us","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikarthikng%2Fzipcodes-us/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikarthikng%2Fzipcodes-us/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikarthikng%2Fzipcodes-us/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ikarthikng","download_url":"https://codeload.github.com/ikarthikng/zipcodes-us/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikarthikng%2Fzipcodes-us/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30393026,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T16:28:32.059Z","status":"ssl_error","status_checked_at":"2026-03-11T16:28:30.024Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geocoding","javascript","nodejs","npm-package","postal-code","postal-codes","typescript","zipcode","zipcodes"],"created_at":"2026-03-11T20:03:29.391Z","updated_at":"2026-03-11T20:03:31.607Z","avatar_url":"https://github.com/ikarthikng.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zipcodes-us\n\nA lightweight and efficient US ZIP code lookup library with no external dependencies.\n\n[![npm version](https://badge.fury.io/js/zipcodes-us.svg)](https://badge.fury.io/js/zipcodes-us.svg)\n[![Tests](https://github.com/ikarthikng/zipcodes-us/actions/workflows/test-and-publish.yml/badge.svg)](https://github.com/ikarthikng/zipcodes-us/actions?query=workflow%3A\"Test+and+Publish\")\n[![npm downloads](https://img.shields.io/npm/dm/zipcodes-us)](https://www.npmjs.com/package/zipcodes-us)\n[![license](https://img.shields.io/npm/l/zipcodes-us)](https://github.com/ikarthikng/zipcodes-us/blob/master/LICENSE)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/zipcodes-us)](https://bundlephobia.com/package/zipcodes-us)\n\n\u003e I try my best to monitor the required dependencies daily and publish updates to the npm package whenever changes are detected.\n\n## 🔄 **Data Last Checked/Updated:** _11th March 2026_\n\n## Features\n\n- Fast in-memory ZIP code lookups\n- Multiple lookup methods for different use cases\n- Find ZIP codes by city, state, and county\n- Find ZIP codes within a radius of coordinates\n- Returns complete information including state, city, county, and coordinates\n- **Universal compatibility** - works in both Node.js and browser/React environments\n- TypeScript support with full type definitions\n- Zero runtime dependencies\n\n## Why Choose zipcodes-us?\n\n- **🚀 Zero Dependencies** - No bloat, just pure functionality\n- **⚡ Lightning Fast** - In-memory lookups with instant results\n- **🌐 Universal** - Same code works in Node.js, React, Next.js, and browsers\n- **📦 Tiny Bundle** - Minimal impact on your bundle size\n- **🔄 Always Up-to-Date** - Data checked and updated daily\n- **💪 Type-Safe** - Full TypeScript support out of the box\n- **🎯 Battle-Tested** - Reliable and production-ready\n\n**Compared to alternatives:**\n\n- Unlike `zipcode-to-timezone`, we provide complete geographic data\n- Unlike `zipcodes`, we support both Node.js and browsers seamlessly\n- Unlike manual API calls, no rate limits or network latency\n\n## 🚀 Try It Now\n\n**Live Demo:** [CodeSandbox Demo](https://codesandbox.io/p/sandbox/little-haze-cc7h58)\n\n**Quick Example:**\n\n```javascript\nimport zipcodes from \"zipcodes-us\"\n\n// One line to get complete ZIP code info\nconst info = zipcodes.find(\"90210\")\n// → { city: 'Beverly Hills', state: 'California', ... }\n```\n\n## Installation\n\n```bash\nnpm install zipcodes-us\n```\n\n## Usage\n\nThis library works seamlessly in both Node.js and browser/React environments with no configuration needed.\n\n### Basic Usage\n\n```typescript\nimport zipcodes from \"zipcodes-us\"\n\n// Complete lookup with validity check\nconst info = zipcodes.find(\"90210\")\nconsole.log(info)\n/* Output:\n{\n  state: 'California',\n  stateCode: 'CA',\n  city: 'Beverly Hills',\n  county: 'Los Angeles',\n  latitude: 34.0901,\n  longitude: -118.4065,\n  isValid: true\n}\n*/\n\n// For invalid ZIP codes, returns empty values with isValid: false\nconst invalid = zipcodes.find(\"00000\")\nconsole.log(invalid)\n/* Output:\n{\n  state: '',\n  stateCode: '',\n  city: '',\n  county: '',\n  latitude: 0,\n  longitude: 0,\n  isValid: false\n}\n*/\n\n// Get just the state information\nconst stateInfo = zipcodes.findState(\"10001\")\nconsole.log(stateInfo) // { state: 'New York', stateCode: 'NY', isValid: true }\n\n// Get just the city\nconst cityInfo = zipcodes.findCity(\"60601\")\nconsole.log(cityInfo) // { city: 'Chicago', isValid: true }\n\n// Get just the county\nconst countyInfo = zipcodes.findCounty(\"94105\")\nconsole.log(countyInfo) // { county: 'San Francisco', isValid: true }\n\n// Get just the coordinates\nconst coords = zipcodes.findCoordinates(\"02108\")\nconsole.log(coords) // { latitude: 42.3588, longitude: -71.0707, isValid: true }\n\n// Find ZIP codes for a city\nconst bostonZips = zipcodes.findByCity(\"Boston\", \"MA\")\nconsole.log(`Boston has ${bostonZips.length} ZIP codes`)\n\n// Find ZIP codes in a county\nconst kingCountyZips = zipcodes.findByCounty(\"King\", \"WA\")\nconsole.log(`King County has ${kingCountyZips.length} ZIP codes`)\n\n// Find ZIP codes within 10 miles of coordinates\nconst nearby = zipcodes.findByRadius(37.7749, -122.4194, 10)\nconsole.log(`Found ${nearby.length} ZIP codes within 10 miles of San Francisco`)\n\n// Get all states\nconst states = zipcodes.getStates()\nconsole.log(`The US has ${states.length} states and territories with ZIP codes`)\n```\n\n### Node.js Example\n\n```typescript\nimport zipcodes from \"zipcodes-us\"\nimport fs from \"fs\"\n\n// Find all ZIP codes for a specific city\nconst bostonZips = zipcodes.findByCity(\"Boston\", \"MA\")\n\n// Save the data to a file\nfs.writeFileSync(\"boston-zips.json\", JSON.stringify(bostonZips, null, 2))\n\nconsole.log(`Saved ${bostonZips.length} Boston ZIP codes to file`)\n```\n\n### React/Browser Example\n\n```jsx\nimport React, { useState } from \"react\"\nimport zipcodes from \"zipcodes-us\"\n\nfunction ZipCodeLookup() {\n  const [zipCode, setZipCode] = useState(\"\")\n  const [result, setResult] = useState(null)\n  const [error, setError] = useState(\"\")\n\n  const handleLookup = () =\u003e {\n    setError(\"\")\n    const info = zipcodes.find(zipCode)\n\n    if (info.isValid) {\n      setResult(info)\n    } else {\n      setError(\"Invalid ZIP code\")\n      setResult(null)\n    }\n  }\n\n  return (\n    \u003cdiv\u003e\n      \u003ch2\u003eZIP Code Lookup\u003c/h2\u003e\n      \u003cdiv\u003e\n        \u003cinput\n          type=\"text\"\n          value={zipCode}\n          onChange={(e) =\u003e setZipCode(e.target.value)}\n          placeholder=\"Enter ZIP code\"\n          maxLength={5}\n        /\u003e\n        \u003cbutton onClick={handleLookup}\u003eLookup\u003c/button\u003e\n      \u003c/div\u003e\n\n      {error \u0026\u0026 \u003cdiv style={{ color: \"red\" }}\u003e{error}\u003c/div\u003e}\n\n      {result \u0026\u0026 (\n        \u003cdiv\u003e\n          \u003ch3\u003eResults for {zipCode}\u003c/h3\u003e\n          \u003cp\u003e\n            \u003cstrong\u003eCity:\u003c/strong\u003e {result.city}\n          \u003c/p\u003e\n          \u003cp\u003e\n            \u003cstrong\u003eState:\u003c/strong\u003e {result.state} ({result.stateCode})\n          \u003c/p\u003e\n          \u003cp\u003e\n            \u003cstrong\u003eCounty:\u003c/strong\u003e {result.county}\n          \u003c/p\u003e\n          \u003cp\u003e\n            \u003cstrong\u003eCoordinates:\u003c/strong\u003e {result.latitude}, {result.longitude}\n          \u003c/p\u003e\n        \u003c/div\u003e\n      )}\n    \u003c/div\u003e\n  )\n}\n\nexport default ZipCodeLookup\n```\n\n## 💡 Common Use Cases\n\n### Validate ZIP Codes\n\n```typescript\n// Check if a ZIP code is valid\nconst info = zipcodes.find(\"90210\")\nif (info.isValid) {\n  console.log(`Valid ZIP in ${info.city}, ${info.state}`)\n}\n```\n\n### Auto-Complete City/State from ZIP\n\n```typescript\n// User enters ZIP, auto-fill city and state\nconst { city, state } = zipcodes.find(userZipCode)\naddressForm.city.value = city\naddressForm.state.value = state\n```\n\n### Find All ZIP Codes in a City\n\n```typescript\n// Get all ZIP codes for a specific city\nconst allBostonZips = zipcodes.findByCity(\"Boston\", \"MA\")\nconsole.log(`Boston has ${allBostonZips.length} ZIP codes`)\n```\n\n### Geographic Proximity Search\n\n```typescript\n// Find ZIP codes within 50 miles of coordinates\nconst nearbyZips = zipcodes.findByRadius(37.7749, -122.4194, 50)\n// Use these for location-based features\n```\n\n### Display Location Information\n\n```typescript\n// Show detailed location info from just a ZIP code\nconst info = zipcodes.find(\"10001\")\ndisplayMap(info.latitude, info.longitude)\nshowDetails(`${info.city}, ${info.county} County, ${info.state}`)\n```\n\n## API\n\n`find(zipCode: string): ZipLookupResult`\n\nReturns complete information for a ZIP code with an `isValid` flag. Always returns an object, even for invalid ZIP codes.\n\n```typescript\ninterface ZipLookupResult {\n  state: string // Full state name\n  stateCode: string // Two-letter state code\n  city: string // City/place name\n  county: string // County name\n  latitude: number // Decimal latitude\n  longitude: number // Decimal longitude\n  isValid: boolean // Whether the ZIP code exists\n}\n\n// Internal ZipCodeInfo interface used by findByCity, findByCounty, and findByRadius methods\ninterface ZipCodeInfo {\n  zipCode: string // 5-digit ZIP code\n  placeName: string // City or place name\n  stateName: string // Full state name\n  stateCode: string // Two-letter state code\n  countyName: string // County name\n  countyCode: string // FIPS county code\n  communityName?: string // Optional community name\n  communityCode?: string // Optional community code\n  latitude: number // Latitude in decimal degrees\n  longitude: number // Longitude in decimal degrees\n}\n```\n\n`findState(zipCode: string): StateResult`\n\nReturns state information for a ZIP code with validity check.\n\n```typescript\ninterface StateResult {\n  state: string // Full state name\n  stateCode: string // Two-letter state code\n  isValid: boolean // Whether the ZIP code exists\n}\n```\n\n`findCity(zipCode: string): { city: string; isValid: boolean }`\n\nReturns city name for a ZIP code with validity check.\n\n`findCounty(zipCode: string): { county: string; isValid: boolean }`\n\nReturns county name for a ZIP code with validity check.\n\n`findCoordinates(zipCode: string): Coordinates`\n\nReturns latitude and longitude for a ZIP code with validity check.\n\n```typescript\ninterface Coordinates {\n  latitude: number // Decimal latitude\n  longitude: number // Decimal longitude\n  isValid: boolean // Whether the ZIP code exists\n}\n```\n\n`findByCity(city: string, stateCode: string): ZipCodeInfo[]`\n\nFinds all ZIP codes for a given city and state. Returns an array of ZipCodeInfo objects.\n\n`findByCounty(countyName: string, stateCode: string): ZipCodeInfo[]`\n\nFinds all ZIP codes in a given county. Returns an array of ZipCodeInfo objects.\n\n`findByRadius(latitude: number, longitude: number, radiusMiles: number): ZipCodeInfo[]`\n\nFinds ZIP codes within a radius of coordinates, sorted by distance. Returns an array of ZipCodeInfo objects.\n\n`getStates(): Array\u003c{ code: string, name: string }\u003e`\n\nReturns all states with their codes and names.\n\n## How Browser Compatibility Works\n\nThe library automatically determines the environment it's running in:\n\n- **In browsers/React**: Uses pre-processed bundled data for optimal performance\n- **In Node.js**: Can fall back to reading the data file directly if needed\n\nThis dual-loading strategy ensures the package works efficiently in any JavaScript environment without any additional configuration.\n\n## Related Projects\n\nLooking for Indian postal codes? Check out **[postalcodes-india](https://github.com/ikarthikng/postalcodes-india)** - the same functionality for India! 🇮🇳\n\n## Data Source\n\nThis package uses GeoNames ZIP code data (under Creative Commons Attribution 4.0 License).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikarthikng%2Fzipcodes-us","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fikarthikng%2Fzipcodes-us","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikarthikng%2Fzipcodes-us/lists"}