🇮🇳 pincode-india

Fast, offline Indian Pincode & Current Location library for Node.js, React, React Native, Next.js and modern browsers.

A production-ready TypeScript library for working with Indian PIN Codes and device location.

pincode-india provides offline pincode lookup, native current location support for React Native, browser geolocation, and zero API-key reverse geocoding using the operating system's built-in services.

Perfect for:

• E-commerce
• Quick Commerce
• Logistics
• Food Delivery
• Grocery Apps
• FinTech
• Banking
• Healthcare
• Government Portals
• CRM & ERP
• Address Forms
• React Native Apps

✨ Features

📦 Offline Pincode Database

• 19,500+ Indian PIN Codes
• 165,000+ India Post Offices
• State
• District
• City
• Latitude
• Longitude
• Delivery Status

Works completely offline.

No API calls.

No internet required.

📍 Native Current Location

Android

• Google Fused Location Provider
• Android Geocoder
• Runtime Permissions

iOS

• CoreLocation
• CLGeocoder
• Native Swift implementation

Browser

• navigator.geolocation support

Node.js

Lookup APIs supported.

Location APIs gracefully report unsupported.

🚀 Installation

npm

npm install pincode-india

Yarn

yarn add pincode-india

pnpm

pnpm add pincode-india

📱 React Native Installation

iOS

cd ios
pod install

Android

No additional setup required.

Autolinking is supported.

🔐 Permissions

Android

Add to AndroidManifest.xml

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

iOS

Add to Info.plist

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app uses your location to detect your current pincode.</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app uses your location to detect your current pincode.</string>

📖 Import

import {
  lookup,
  lookupMany,
  isValid,
  isDeliverable,
  getState,
  getDistrict,
  getCity,
  getCoordinates,
  getPostOffices,
  getByState,
  getByDistrict,
  searchByCity,
  getDistricts,
  getAllStates,
  preload,

  requestLocationPermission,
  isLocationEnabled,
  getCurrentLocation,
  getCurrentPincode,
  watchLocation,
  stopWatchingLocation
} from "pincode-india";

📌 Offline Lookup

const data = lookup("110001");

console.log(data);

Returns

{
  pincode: "110001",
  city: "New Delhi",
  district: "Central Delhi",
  state: "Delhi",
  latitude: 28.6328,
  longitude: 77.2197,
  deliverable: true,
  postOffices: [...]
}

📍 Get Current Location

const location = await getCurrentLocation();

console.log(location);

Returns

{
  latitude: 28.6139,
  longitude: 77.2090,
  accuracy: 8.5,
  altitude: 214,
  speed: 0,
  heading: 0,
  timestamp: 1719393000
}

📮 Get Current Pincode

const address = await getCurrentPincode();

console.log(address);

Returns

{
  pincode: "110001",
  city: "New Delhi",
  district: "Central Delhi",
  state: "Delhi",
  country: "India",
  latitude: 28.6139,
  longitude: 77.2090,
  deliverable: true,
  postOffices: [...]
}

🔑 Request Permission

const granted = await requestLocationPermission();

if (!granted) {
  console.log("Permission denied");
}

📡 Check GPS

const enabled = await isLocationEnabled();

console.log(enabled);

👀 Watch Location

const watchId = watchLocation((location) => {
  console.log(location);
});

Stop watching

stopWatchingLocation(watchId);

📚 API Reference

lookup(pin)

Returns complete information about a pincode.

lookup("560001");

lookupMany()

Lookup multiple pincodes.

lookupMany([
  "110001",
  "560001",
  "400001"
]);

isValid()

isValid("110001");

Returns

true

isDeliverable()

isDeliverable("110001");

getState()

getState("560001");

getDistrict()

getDistrict("560001");

getCity()

getCity("560001");

getCoordinates()

getCoordinates("560001");

getPostOffices()

getPostOffices("560001");

getByState()

getByState("Maharashtra");

getByDistrict()

getByDistrict(
  "Maharashtra",
  "Mumbai"
);

searchByCity()

searchByCity("Bandra");

getDistricts()

getDistricts("Punjab");

getAllStates()

getAllStates();

preload()

preload();

Recommended for backend servers.

⚛️ React Example

const data = lookup(pin);

<Text>{data.city}</Text>

📱 React Native Example

useEffect(() => {
  async function init() {
    await requestLocationPermission();

    const address = await getCurrentPincode();

    console.log(address);
  }

  init();
}, []);

🌐 Browser Example

const location = await getCurrentLocation();

console.log(location);

Browser returns coordinates only.

Reverse geocoding is not performed in browsers.

🖥 Node.js Example

const data = lookup("110001");

Location APIs throw an unsupported platform error.

⚡ Performance

| Feature | Performance | | ---------------- | ----------- | | Offline Lookup | < 1 ms | | Dependencies | 0 | | Offline Database | ~1.5 MB | | TypeScript | ✅ | | Tree Shakeable | ✅ | | React Native | ✅ | | Browser | ✅ | | Node.js | ✅ |

🏗 Platform Support

| Platform | Lookup | Current Location | | -------------------- | ------ | ------------------- | | Node.js | ✅ | ❌ | | Browser | ✅ | ✅ Coordinates Only | | React | ✅ | Browser Geolocation | | React Native Android | ✅ | ✅ | | React Native iOS | ✅ | ✅ | | Next.js | ✅ | Client Only |

⚠️ Errors

The library may throw:

• PermissionDeniedError
• LocationDisabledError
• LocationUnavailableError
• GeocoderError
• TimeoutError

Always wrap location methods in try/catch.

📂 Data Source

The offline database is generated from publicly available India Post postal data.

Includes:

• PIN Code
• City
• District
• State
• Latitude
• Longitude
• Delivery Status
• Post Office Information

🧪 Testing

npm install

npm run lint

npm run build

npm test

🤝 Contributing

Contributions are welcome.

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push your branch
5. Open a Pull Request

📄 License

MIT License

❤️ Author

Made with ❤️ for the Indian developer community.

If you find this package useful, please consider giving it a ⭐ on GitHub.

Contact Developer (for any issue or updation request)

• Portfolio Link

• Send Email