📍 PinExplorer — India Pincode Intelligence

A full-stack web application for exploring Indian pincodes, built with React (frontend) and Express + MongoDB (backend). Search by pincode or city name, browse all states and districts, compare pincodes side-by-side, do bulk lookups, and view rich analytics — all in a sleek dark UI.

📸 Features at a Glance

Feature	Description
📍 Pincode Lookup	Search any 6-digit pincode for city, district, state, offices
🔍 Explore Pincodes	Browse and filter by state → district → taluk with paginated results
📊 Dashboard	Overview with stat cards, state-wise bar chart, delivery pie chart
🔍 City Search	Find pincodes by city, district or post office name
📋 Bulk Lookup	Look up up to 50 pincodes at once
⚖️ Compare	Side-by-side pincode comparison with match/mismatch highlight
🗺️ Browse States	Explore all states → districts → cities
📊 Analytics	Charts and stats — offices per state, office types, delivery status
ℹ️ About	Feature overview, tech stack, and API endpoint reference
🔁 Autocomplete	Live suggestions as you type
📍 Nearby Pincodes	Find pincodes in the same district
⬇️ CSV Export	Export any result set as a CSV file
🔗 Share Links	Copy a shareable URL for any pincode
🌙 Dark / Light Mode	Toggle and persists across sessions
🕓 Search History	Recent pincode searches saved locally

🗂️ Project Structure

pinexplorer/
├── server.js                      # Express entry point
├── config/
│   └── db.js                      # MongoDB connection configuration
├── models/
│   └── Pincode.js                 # Mongoose schema and model
├── controllers/
│   └── pincodeController.js       # All route handler logic
├── routes/
│   └── pincodeRoutes.js           # API route definitions
├── frontend/                      # React + Vite frontend
├── package.json
└── README.md

⚙️ Prerequisites

Make sure you have the following installed:

Node.js v18 or above
MongoDB running locally on port 27017
A MongoDB database named Pincode1 with a collection named pincodes populated with Indian pincode data

MongoDB Document Schema

Each document in the pincodes collection should look like this:

{
  "officeName": "Andheri S.O",
  "pincode": 400053,
  "officeType": "Sub Post Office",
  "deliveryStatus": "Delivery",
  "divisionName": "Mumbai City",
  "regionName": "Mumbai",
  "circleName": "Maharashtra",
  "taluk": "Andheri",
  "districtName": "Mumbai",
  "stateName": "MAHARASHTRA"
}

You can find free Indian pincode datasets on data.gov.in or GitHub.

🚀 Getting Started

1. Clone the repository

git clone https://github.com/yourusername/pinexplorer.git
cd pinexplorer

2. Install dependencies

cd Project
npm install

3. Set up environment variables (optional)

Create a .env file in the Project/ directory:

PORT=5000
MONGODB_URI=your_mongodb_connection_string

If MONGODB_URI is not provided, the app uses the default MongoDB Atlas connection.

4. Start the backend server

npm start

Or for development:

npm run dev

You should see:

MongoDB Connected
Server running on port 5000

5. Start the React frontend

cd frontend
npm install
npm run dev

The frontend will be available at http://localhost:5173.

🌐 API Reference

Base URL: http://localhost:5000

`GET /api/pincode`

Look up a single pincode.

Query Parameters

Param	Type	Required	Description
`code`	number	✅	6-digit Indian pincode

Example Request

GET /api/pincode?code=400001

Example Response

{
  "success": true,
  "cityDetails": {
    "pincode": 400001,
    "city": "Mumbai",
    "district": "Mumbai",
    "state": "MAHARASHTRA",
    "region": "Mumbai",
    "division": "Mumbai City",
    "circle": "Maharashtra",
    "totalOffices": 5,
    "offices": [
      { "name": "Fort S.O", "type": "Sub Post Office", "deliveryStatus": "Delivery" }
    ]
  }
}

`GET /api/search`

Search for pincodes by city name, district, or post office name.

Query Parameters

Param	Type	Required	Description
`q`	string	✅	Search query (min 2 characters)
`type`	string	❌	`all` (default), `city`, `district`, or `office`

Example Request

GET /api/search?q=Bandra&type=city

Example Response

{
  "success": true,
  "query": "Bandra",
  "total": 3,
  "results": [
    {
      "pincode": 400050,
      "city": "Bandra",
      "district": "Mumbai",
      "state": "MAHARASHTRA",
      "region": "Mumbai",
      "officeCount": 4
    }
  ]
}

`GET /api/autocomplete`

Get live autocomplete suggestions for city and district names.

Query Parameters

Param	Type	Required	Description
`q`	string	✅	Partial query (min 2 characters)

Example Request

GET /api/autocomplete?q=Pune

Example Response

{
  "success": true,
  "suggestions": [
    { "label": "Pune", "type": "city" },
    { "label": "Pune City", "type": "district" }
  ]
}

`GET /api/nearby`

Find other pincodes in the same district as the given pincode.

Query Parameters

Param	Type	Required	Description
`pincode`	number	✅	The base 6-digit pincode

Example Request

GET /api/nearby?pincode=400001

Example Response

{
  "success": true,
  "basePincode": 400001,
  "baseDistrict": "Mumbai",
  "total": 12,
  "nearby": [
    { "pincode": 400002, "city": "Kalbadevi", "district": "Mumbai", "state": "MAHARASHTRA", "officeCount": 3 }
  ]
}

`POST /api/bulk`

Look up multiple pincodes in a single request.

Request Body

{
  "pincodes": [400001, 110001, 600001]
}

Maximum 50 pincodes per request.

Example Response

{
  "success": true,
  "found": [
    {
      "pincode": 400001,
      "city": "Mumbai",
      "district": "Mumbai",
      "state": "MAHARASHTRA",
      "region": "Mumbai",
      "division": "Mumbai City",
      "officeCount": 5,
      "offices": ["Fort S.O", "GPO"]
    }
  ],
  "notFound": [999999]
}

`GET /api/stats`

Get aggregated analytics across all pincodes in the database.

Example Response

{
  "success": true,
  "summary": {
    "totalOffices": 154000,
    "totalPincodes": 19000,
    "totalStates": 36,
    "totalDistricts": 720
  },
  "stateStats": [
    { "state": "UTTAR PRADESH", "totalOffices": 18000, "uniquePincodes": 2200, "uniqueDistricts": 75 }
  ],
  "officeTypes": [
    { "type": "Sub Post Office", "count": 130000 },
    { "type": "Head Post Office", "count": 900 }
  ],
  "deliveryStatus": [
    { "status": "Delivery", "count": 90000 },
    { "status": "Non-Delivery", "count": 64000 }
  ]
}

`GET /states`

Get a sorted list of all states in the database.

Example Response

{
  "success": true,
  "totalStates": 36,
  "states": ["ANDHRA PRADESH", "ASSAM", "BIHAR", ...]
}

`GET /states/:state_name`

Get all districts and cities for a given state.

URL Parameters

Param	Type	Description
`state_name`	string	State name (case-insensitive)

Example Request

GET /states/MAHARASHTRA

Example Response

{
  "success": true,
  "state": "MAHARASHTRA",
  "totalDistricts": 36,
  "districts": [
    {
      "district": "Mumbai",
      "cities": ["Andheri", "Bandra", "Colaba", "Kurla"]
    }
  ]
}

`GET /api/states`

Get a sorted array of all unique state names.

Example Request

GET /api/states

Example Response

[
  "ANDHRA PRADESH",
  "GUJARAT",
  "MAHARASHTRA",
  "TAMIL NADU"
]

`GET /api/states/:state/districts`

Get all districts for a given state.

URL Parameters

Param	Type	Description
`state`	string	State name (case-insensitive)

Example Request

GET /api/states/GUJARAT/districts

Example Response

[
  "AHMEDABAD",
  "SURAT",
  "VADODARA"
]

`GET /api/states/:state/districts/:district/taluks`

Get all taluks for a given state and district.

URL Parameters

Param	Type	Description
`state`	string	State name
`district`	string	District name

Example Request

GET /api/states/GUJARAT/districts/AHMEDABAD/taluks

Example Response

[
  "AHMEDABAD CITY",
  "DASKROI",
  "SANAND"
]

`GET /api/pincodes`

Get filtered and paginated pincode data.

Query Parameters

Param	Type	Required	Description
`state`	string	❌	Filter by state
`district`	string	❌	Filter by district
`taluk`	string	❌	Filter by taluk
`page`	number	❌	Page number (default: 1)
`limit`	number	❌	Results per page (default: 20)

Example Request

GET /api/pincodes?state=GUJARAT&district=AHMEDABAD&taluk=DASKROI&page=1&limit=20

Example Response

{
  "data": [
    {
      "pincode": 382425,
      "officeName": "Daskroi S.O",
      "officeType": "Sub Post Office",
      "deliveryStatus": "Delivery",
      "taluk": "DASKROI",
      "district": "AHMEDABAD",
      "state": "GUJARAT",
      "division": "Ahmedabad",
      "region": "Rajkot",
      "circle": "Gujarat"
    }
  ],
  "total": 120,
  "page": 1,
  "limit": 20
}

`GET /api/pincode/:pincode`

Look up a single pincode by path parameter.

URL Parameters

Param	Type	Description
`pincode`	number	6-digit Indian pincode

Example Request

GET /api/pincode/400001

Example Response

{
  "success": true,
  "cityDetails": {
    "pincode": 400001,
    "city": "Mumbai",
    "district": "Mumbai",
    "state": "MAHARASHTRA",
    "region": "Mumbai",
    "division": "Mumbai City",
    "circle": "Maharashtra",
    "totalOffices": 5,
    "offices": [
      { "name": "Fort S.O", "type": "Sub Post Office", "deliveryStatus": "Delivery" }
    ]
  }
}

`GET /api/stats/state-distribution`

Get state-wise office count distribution for bar charts.

Example Request

GET /api/stats/state-distribution

Example Response

[
  { "state": "GUJARAT", "count": 12000 },
  { "state": "MAHARASHTRA", "count": 20000 },
  { "state": "TAMIL NADU", "count": 15000 }
]

`GET /api/stats/delivery-distribution`

Get delivery vs non-delivery office counts for pie charts.

Example Request

GET /api/stats/delivery-distribution

Example Response

{
  "delivery": 120000,
  "nonDelivery": 34000
}

`GET /api/export`

Export pincode data as a CSV file.

Query Parameters

Param	Type	Required	Description
`state`	string	❌	Filter by state
`district`	string	❌	Filter by district
`taluk`	string	❌	Filter by taluk

Example Request

GET /api/export?state=GUJARAT

Returns a CSV file download with columns: Pincode, Office Name, Office Type, Delivery Status, Taluk, District, State, Division, Region, Circle.

🧱 Tech Stack

Backend (MVC Architecture)

Node.js — Runtime
Express.js — Web framework
Mongoose — MongoDB ODM
CORS — Cross-origin requests

Backend Architecture

The backend follows the MVC (Model-View-Controller) pattern:

Directory	Purpose
`config/`	Database connection and app configuration
`models/`	Mongoose schemas and models
`controllers/`	Business logic and request handlers
`routes/`	API route definitions mapped to controllers
`server.js`	Express app entry point and middleware setup

Frontend

React — UI framework
Recharts — Charts and data visualizations
Google Fonts — Clash Display + Cabinet Grotesk
CSS Variables — Theming (dark/light mode)
localStorage — Persistent search history and theme preference

📦 npm Dependencies

Backend

npm install express mongoose cors

Frontend

cd frontend
npm install

No other third-party UI libraries are used in the frontend — the entire UI is hand-crafted with CSS.

🗄️ Database Indexes

The backend creates the following MongoDB indexes automatically on startup for fast queries:

pincodeSchema.index({ pincode: 1 });
pincodeSchema.index({ stateName: 1 });
pincodeSchema.index({ districtName: 1 });
pincodeSchema.index({ taluk: 1 });
pincodeSchema.index({ officeName: "text", taluk: "text", districtName: "text" });

🔧 Environment & Configuration

The app uses these environment variables. Create a .env file in the Project/ directory:

Variable	Default	Description
`MONGODB_URI`	MongoDB Atlas connection string	Database connection
`PORT`	`5000`	Express server port

Example .env:

PORT=5000
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/Pincode

The database connection is managed in config/db.js and the server listens on the configured port via server.js.

🚧 Known Limitations

The map view links out to OpenStreetMap rather than embedding an interactive map. To embed a real interactive map, integrate Leaflet.js with geocoding via the Nominatim API.
The /api/stats endpoint queries the full collection — on large datasets (150k+ documents) it may be slow on first load. Consider adding a Redis cache or pre-computing stats on a schedule.
Bulk lookup is capped at 50 pincodes per request to protect server performance.
Search autocomplete triggers on 2+ characters; very short queries may return many results.

🛠️ Possible Enhancements

Add Redis caching for /api/stats and /states
Add pagination to /api/search results
Embed Leaflet.js for a real interactive map with markers
Add a PWA manifest + service worker for offline support
Implement rate limiting with express-rate-limit
Add input sanitization and helmet.js for security headers
Write unit tests with Jest (backend) and React Testing Library (frontend)
Deploy backend to Railway or Render; frontend to Vercel or Netlify

📄 License

MIT — free to use, modify and distribute.

🙌 Acknowledgements

Indian pincode data sourced from India Post / data.gov.in
Charts powered by Recharts
Map links powered by OpenStreetMap
Typography: Clash Display + Cabinet Grotesk via Google Fonts

Name		Name	Last commit message	Last commit date
Project		Project
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

📍 PinExplorer — India Pincode Intelligence

📸 Features at a Glance

🗂️ Project Structure

⚙️ Prerequisites

MongoDB Document Schema

🚀 Getting Started

1. Clone the repository

2. Install dependencies

3. Set up environment variables (optional)

4. Start the backend server

5. Start the React frontend

🌐 API Reference

GET /api/pincode

GET /api/search

GET /api/autocomplete

GET /api/nearby

POST /api/bulk

GET /api/stats

GET /states

GET /states/:state_name

GET /api/states

GET /api/states/:state/districts

GET /api/states/:state/districts/:district/taluks

GET /api/pincodes

GET /api/pincode/:pincode

GET /api/stats/state-distribution

GET /api/stats/delivery-distribution

GET /api/export

🧱 Tech Stack

Backend (MVC Architecture)

Backend Architecture

Frontend

📦 npm Dependencies

Backend

Frontend

🗄️ Database Indexes

🔧 Environment & Configuration

🚧 Known Limitations

🛠️ Possible Enhancements

📄 License

🙌 Acknowledgements

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`GET /api/pincode`

`GET /api/search`

`GET /api/autocomplete`

`GET /api/nearby`

`POST /api/bulk`

`GET /api/stats`

`GET /states`

`GET /states/:state_name`

`GET /api/states`

`GET /api/states/:state/districts`

`GET /api/states/:state/districts/:district/taluks`

`GET /api/pincodes`

`GET /api/pincode/:pincode`

`GET /api/stats/state-distribution`

`GET /api/stats/delivery-distribution`

`GET /api/export`