{"id":47007567,"url":"https://github.com/ikarthikng/postalcodes-india","last_synced_at":"2026-03-11T20:28:33.091Z","repository":{"id":278818956,"uuid":"936896649","full_name":"ikarthikng/postalcodes-india","owner":"ikarthikng","description":"Fast and lightweight Indian postal code (PIN) lookup library with hierarchical location data - states, districts, sub-districts, and coordinates. Zero dependencies and full TypeScript support.","archived":false,"fork":false,"pushed_at":"2025-11-06T22:32:44.000Z","size":9482,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-14T15:19:25.006Z","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/postalcodes-india","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-21T22:08:24.000Z","updated_at":"2025-11-06T22:24:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"805b1f08-7d65-4ba9-b864-97537d6f50d0","html_url":"https://github.com/ikarthikng/postalcodes-india","commit_stats":null,"previous_names":["ikarthikng/postalcodes-india"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/ikarthikng/postalcodes-india","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikarthikng%2Fpostalcodes-india","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikarthikng%2Fpostalcodes-india/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikarthikng%2Fpostalcodes-india/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikarthikng%2Fpostalcodes-india/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ikarthikng","download_url":"https://codeload.github.com/ikarthikng/postalcodes-india/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikarthikng%2Fpostalcodes-india/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30399134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T18:46:22.935Z","status":"ssl_error","status_checked_at":"2026-03-11T18:46:17.045Z","response_time":84,"last_error":"SSL_read: 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:28:32.521Z","updated_at":"2026-03-11T20:28:33.083Z","avatar_url":"https://github.com/ikarthikng.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# postalcodes-india\n\nA lightweight and efficient Indian postal code lookup library with no external dependencies. Compatible with both Node.js and browser/React environments.\n\n[![npm version](https://badge.fury.io/js/postalcodes-india.svg)](https://badge.fury.io/js/postalcodes-india.svg)\n[![Tests](https://github.com/ikarthikng/postalcodes-india/actions/workflows/test-and-publish.yml/badge.svg)](https://github.com/ikarthikng/postalcodes-india/actions?query=workflow%3A\"Test+and+Publish\")\n[![npm downloads](https://img.shields.io/npm/dm/postalcodes-india)](https://www.npmjs.com/package/postalcodes-india)\n[![license](https://img.shields.io/npm/l/postalcodes-india)](https://github.com/ikarthikng/postalcodes-india/blob/master/LICENSE)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/postalcodes-india)](https://bundlephobia.com/package/postalcodes-india)\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 postal code lookups\n- Multiple lookup methods for different use cases\n- Find postal codes by place, state, and district\n- Find postal codes within a radius of coordinates\n- Returns complete information including state, district, sub-district, and coordinates\n- TypeScript support with full type definitions\n- Zero runtime dependencies\n- **Universal compatibility**: Works in Node.js, browsers, and React applications\n- **Tree-shakable**: Import only what you need\n\n## Why Choose postalcodes-india?\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- **🇮🇳 Complete Coverage** - All 19,000+ Indian postal codes\n\n**Compared to alternatives:**\n\n- Unlike API-based solutions, no rate limits or network latency\n- Unlike other npm packages, we support both Node.js and browsers seamlessly\n- Tree-shakable design - import only what you need\n\n## 🚀 Try It Now\n\n**Live Demo:** [CodeSandbox Demo](https://codesandbox.io/p/sandbox/awesome-tree-swv4kn)\n\n**Quick Example:**\n\n```javascript\nimport postalcodes from \"postalcodes-india\"\n\n// One line to get complete postal code info\nconst info = postalcodes.find(\"560029\")\n// → { place: 'Bangalore', state: 'Karnataka', district: 'Bangalore', ... }\n```\n\n**Looking for US ZIP codes?** Check out [zipcodes-us](https://github.com/ikarthikng/zipcodes-us) 🇺🇸\n\n## Installation\n\n```bash\nnpm install postalcodes-india\n```\n\n## Usage\n\n### In Node.js (ESM)\n\n```javascript\nimport postalcodes from \"postalcodes-india\"\n\n// Complete lookup with validity check\nconst info = postalcodes.find(\"560029\")\nconsole.log(info)\n```\n\n### In Node.js (CommonJS)\n\n```javascript\nconst postalcodes = require(\"postalcodes-india\")\n\n// Complete lookup with validity check\nconst info = postalcodes.find(\"560029\")\nconsole.log(info)\n```\n\n### In React\n\n```jsx\nimport React, { useState } from \"react\"\nimport postalcodes from \"postalcodes-india\"\n\nfunction PostalCodeLookup() {\n  const [code, setCode] = useState(\"\")\n  const [result, setResult] = useState(null)\n\n  const handleLookup = () =\u003e {\n    const info = postalcodes.find(code)\n    setResult(info)\n  }\n\n  return (\n    \u003cdiv\u003e\n      \u003ch2\u003ePostal Code Lookup\u003c/h2\u003e\n      \u003cinput type=\"text\" value={code} onChange={(e) =\u003e setCode(e.target.value)} placeholder=\"Enter postal code\" /\u003e\n      \u003cbutton onClick={handleLookup}\u003eLookup\u003c/button\u003e\n\n      {result \u0026\u0026 (\n        \u003cdiv\u003e\n          \u003ch3\u003eResults:\u003c/h3\u003e\n          {result.isValid ? (\n            \u003cul\u003e\n              \u003cli\u003eState: {result.state}\u003c/li\u003e\n              \u003cli\u003eDistrict: {result.district}\u003c/li\u003e\n              \u003cli\u003eSub-District: {result.subDistrict}\u003c/li\u003e\n              \u003cli\u003ePlace: {result.place}\u003c/li\u003e\n              \u003cli\u003e\n                Coordinates: {result.latitude}, {result.longitude}\n              \u003c/li\u003e\n            \u003c/ul\u003e\n          ) : (\n            \u003cp\u003eInvalid postal code\u003c/p\u003e\n          )}\n        \u003c/div\u003e\n      )}\n    \u003c/div\u003e\n  )\n}\n\nexport default PostalCodeLookup\n```\n\n### In Browser (via CDN)\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/postalcodes-india/dist/index.umd.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  // The library is available as a global variable 'postalcodes'\n  const info = postalcodes.find(\"110001\")\n  console.log(info)\n\u003c/script\u003e\n```\n\n### Tree-shaking (Import only what you need)\n\n```javascript\nimport { find, findByRadius } from \"postalcodes-india\"\n\n// Use specific functions without importing the entire library\nconst info = find(\"400001\")\nconst nearby = findByRadius(19.076, 72.8777, 5) // 5km radius around Mumbai\n```\n\n## 💡 Common Use Cases\n\n### Validate Postal Codes\n\n```typescript\n// Check if a postal code is valid\nconst info = postalcodes.find(\"560029\")\nif (info.isValid) {\n  console.log(`Valid postal code in ${info.place}, ${info.state}`)\n}\n```\n\n### Auto-Complete Location from Postal Code\n\n```typescript\n// User enters postal code, auto-fill location details\nconst { place, district, state } = postalcodes.find(userPostalCode)\naddressForm.city.value = place\naddressForm.district.value = district\naddressForm.state.value = state\n```\n\n### Find All Postal Codes in a District\n\n```typescript\n// Get all postal codes for a specific district\nconst allBangalorePostals = postalcodes.findByDistrict(\"Bangalore\", \"29\")\nconsole.log(`Bangalore has ${allBangalorePostals.length} postal codes`)\n```\n\n### Geographic Proximity Search\n\n```typescript\n// Find postal codes within 20 kilometers of coordinates\nconst nearbyPostals = postalcodes.findByRadius(12.9716, 77.5946, 20)\n// Use these for location-based features\n```\n\n### Display Location Hierarchy\n\n```typescript\n// Show complete location hierarchy from postal code\nconst hierarchy = postalcodes.findHierarchy(\"560029\")\nconsole.log(`${hierarchy.place}, ${hierarchy.subDistrict}, ${hierarchy.district}, ${hierarchy.state}`)\n```\n\n## Examples\n\n```typescript\nimport postalcodes from \"postalcodes-india\"\n\n// Complete lookup with validity check\nconst info = postalcodes.find(\"744301\")\nconsole.log(info)\n/* Output:\n{\n  state: 'Andaman \u0026 Nicobar Islands',\n  stateCode: '01',\n  district: 'Nicobar',\n  subDistrict: 'Carnicobar',\n  place: 'Sawai',\n  latitude: 7.5166,\n  longitude: 93.6031,\n  isValid: true\n}\n*/\n\n// For invalid postal codes, returns empty values with isValid: false\nconst invalid = postalcodes.find(\"000000\")\nconsole.log(invalid)\n/* Output:\n{\n  state: '',\n  stateCode: '',\n  district: '',\n  subDistrict: '',\n  place: '',\n  latitude: 0,\n  longitude: 0,\n  isValid: false\n}\n*/\n\n// Get just the state information\nconst stateInfo = postalcodes.findState(\"744301\")\nconsole.log(stateInfo) // { state: 'Andaman \u0026 Nicobar Islands', stateCode: '01', isValid: true }\n\n// Get just the district information\nconst districtInfo = postalcodes.findDistrict(\"744301\")\nconsole.log(districtInfo) // { district: 'Nicobar', districtCode: '638', state: 'Andaman \u0026 Nicobar Islands', stateCode: '01', isValid: true }\n\n// Get just the place\nconst placeInfo = postalcodes.findPlace(\"744301\")\nconsole.log(placeInfo) // { place: 'Sawai', isValid: true }\n\n// Get just the coordinates\nconst coords = postalcodes.findCoordinates(\"744301\")\nconsole.log(coords) // { latitude: 7.5166, longitude: 93.6031, isValid: true }\n\n// Get complete location hierarchy\nconst hierarchy = postalcodes.findHierarchy(\"744301\")\nconsole.log(hierarchy)\n/* Output:\n{\n  state: 'Andaman \u0026 Nicobar Islands',\n  stateCode: '01',\n  district: 'Nicobar',\n  districtCode: '638',\n  subDistrict: 'Carnicobar',\n  place: 'Sawai',\n  isValid: true\n}\n*/\n\n// Find postal codes for a place and state\nconst placePostals = postalcodes.findByPlace(\"Sawai\", \"01\")\nconsole.log(`Found ${placePostals.length} postal codes`)\n\n// Find postal codes in a district\nconst districtPostals = postalcodes.findByDistrict(\"Nicobar\", \"01\")\nconsole.log(`Nicobar district has ${districtPostals.length} postal codes`)\n\n// Find postal codes within 10 kilometers of coordinates\nconst nearby = postalcodes.findByRadius(7.5166, 93.6031, 10)\nconsole.log(`Found ${nearby.length} postal codes within 10km radius`)\n\n// Get all states\nconst states = postalcodes.getStates()\nconsole.log(`India has ${states.length} states and union territories with postal codes`)\n```\n\n## API\n\n`find(postalCode: string): PostalLookupResult`\n\nReturns complete information for a postal code with an `isValid` flag. Always returns an object, even for invalid postal codes.\n\n```typescript\ninterface PostalLookupResult {\n  state: string // Full state/UT name\n  stateCode: string // State code\n  district: string // District name\n  subDistrict: string // Sub-district/tehsil name\n  place: string // Place name\n  latitude: number // Decimal latitude\n  longitude: number // Decimal longitude\n  isValid: boolean // Whether the postal code exists\n}\n\n// Internal PostalCodeInfo interface used by findByPlace, findByDistrict, and findByRadius methods\ninterface PostalCodeInfo {\n  postalCode: string // 6-digit postal code\n  placeName: string // Place name\n  stateName: string // Full state/UT name\n  stateCode: string // State code\n  districtName: string // District name\n  districtCode: string // District code\n  subDistrictName: string // Sub-district name\n  latitude: number // Latitude in decimal degrees\n  longitude: number // Longitude in decimal degrees\n}\n```\n\n`findState(postalCode: string): StateResult`\n\nReturns state information for a postal code with validity check.\n\n```typescript\ninterface StateResult {\n  state: string // Full state/UT name\n  stateCode: string // State code\n  isValid: boolean // Whether the postal code exists\n}\n```\n\n`findDistrict(postalCode: string): DistrictResult`\n\nReturns district information for a postal code with validity check.\n\n```typescript\ninterface DistrictResult {\n  district: string // District name\n  districtCode: string // District code\n  state: string // State name\n  stateCode: string // State code\n  isValid: boolean // Whether the postal code exists\n}\n```\n\n`findPlace(postalCode: string): { place: string; isValid: boolean }`\n\nReturns place name for a postal code with validity check.\n\n`findCoordinates(postalCode: string): Coordinates`\n\nReturns latitude and longitude for a postal code with validity check.\n\n```typescript\ninterface Coordinates {\n  latitude: number // Decimal latitude\n  longitude: number // Decimal longitude\n  isValid: boolean // Whether the postal code exists\n}\n```\n\n`findHierarchy(postalCode: string): LocationHierarchy`\n\nReturns complete location hierarchy for a postal code.\n\n```typescript\ninterface LocationHierarchy {\n  state: string // State name\n  stateCode: string // State code\n  district: string // District name\n  districtCode: string // District code\n  subDistrict: string // Sub-district name\n  place: string // Place name\n  isValid: boolean // Whether the postal code exists\n}\n```\n\n`findByPlace(place: string, stateCode: string): PostalCodeInfo[]`\n\nFinds all postal codes for a given place and state. Returns an array of PostalCodeInfo objects.\n\n`findByDistrict(districtName: string, stateCode: string): PostalCodeInfo[]`\n\nFinds all postal codes in a given district. Returns an array of PostalCodeInfo objects.\n\n`findByRadius(latitude: number, longitude: number, radiusKm: number): PostalCodeInfo[]`\n\nFinds postal codes within a radius of coordinates, sorted by distance. Returns an array of PostalCodeInfo objects.\n\n`getStates(): Array\u003c{ code: string, name: string }\u003e`\n\nReturns all states and union territories with their codes and names.\n\n## Related Projects\n\nLooking for US ZIP codes? Check out **[zipcodes-us](https://github.com/ikarthikng/zipcodes-us)** - the same functionality for the United States! 🇺🇸\n\n## Data Source\n\nThis package uses GeoNames postal 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%2Fpostalcodes-india","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fikarthikng%2Fpostalcodes-india","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikarthikng%2Fpostalcodes-india/lists"}