Bharat API: A Free & Open-Source Indian Pincode & Location API

🇮🇳 Introduction

Bharat API is a high-performance, easy-to-use REST API that provides detailed information about Indian cities and states based on a 6-digit pincode. Built for developers, this project solves the common challenge of retrieving accurate location data for use in e-commerce, logistics, and form validation applications.

🎯 The Problem It Solves

Developers building applications for the Indian market frequently need to translate a postal pincode into its corresponding city and state. Finding a reliable, free, and easy-to-integrate data source for this can be challenging. This project provides a straightforward and dependable solution, removing a common development hurdle.

✨ Key Features

• 🔍 Pincode Lookup: Get location details instantly with a simple API call to a pincode endpoint
• 🏙️ City & State Search: Find all pincodes associated with a particular city or state
• 📊 Structured JSON Responses: Receive clean, predictable, and easy-to-parse JSON data
• 👨‍💻 Developer-Friendly: Designed with a focus on ease of use and quick integration
• 🐳 Containerized & Portable: Packaged with Docker for consistent development and deployment
• ⚡ High Performance: Built with Express.js and SQLite for fast response times
• 🔄 Hot Reload Development: Nodemon-powered development environment

🛠️ Tech Stack & Architecture

This project demonstrates modern backend development practices with a robust technology stack:

• Backend Framework: Node.js with Express.js (TypeScript)
• Database: SQLite with Knex.js ORM for migrations and queries
• Development: Hot reload with Nodemon, TypeScript compilation
• Containerization: Docker & Docker Compose for consistent environments
• Data Import: CSV parsing and bulk import capabilities
• Cloud-Ready: Designed for easy deployment on Google Cloud, AWS, or Azure

📡 API Endpoints

Get Location by Pincode

Get detailed location information for a specific pincode.

Request:

GET /api/pincode/110001

Success Response (200 OK):

{
  "pincode": "110001",
  "location": "New Delhi",
  "state": "Delhi"
}

Search by City/Location Name

Find all pincodes associated with a particular city or location.

Request:

GET /api/search?city=Delhi

Success Response (200 OK):

[
  {
    "pincode": "110001",
    "location": "New Delhi",
    "state": "Delhi"
  },
  {
    "pincode": "110002",
    "location": "Delhi Gpo",
    "state": "Delhi"
  }
]

Search by State

Find all pincodes in a specific state.

Request:

GET /api/search?state=Maharashtra

Health Check

Check API status and uptime.

Request:

GET /health

Response:

{
  "status": "OK",
  "timestamp": "2025-06-08T10:30:00.000Z",
  "uptime": 1234.567,
  "environment": "development"
}

🚀 Getting Started

Option 1: Using Docker (Recommended)

The fastest way to get started with full environment isolation:

# Clone the repository
git clone https://github.com/your-username/bharat-api.git
cd bharat-api

# Setup environment variables
cp .env.example .env

# Launch with Docker (includes automatic data import)
docker-compose up -d

The Docker setup automatically:

• ✅ Runs database migrations
• ✅ Imports the included india-pincodes.csv file
• ✅ Starts the API server

Option 2: Local Development

For direct local development without Docker:

# Clone and navigate
git clone https://github.com/your-username/bharat-api.git
cd bharat-api

# Install dependencies
npm install

# Setup environment
cp .env.example .env

# Setup database and import data
npm run setup

# Start development server with hot reload
npm run dev

🐳 Docker Commands

# Development (with hot reload)
npm run docker:dev

# Production
npm run docker:prod

# View logs
npm run docker:logs

# Stop containers
npm run docker:stop

# Complete reset (removes data and rebuilds)
npm run docker:reset

# Access container shell
npm run docker:shell

🧪 Testing the API

Once the server is running (default: http://localhost:3000):

# Check if API is running
curl http://localhost:3000/health

# Test pincode lookup
curl http://localhost:3000/api/pincode/110001

# Test city search
curl "http://localhost:3000/api/search?city=Delhi"

# Test state search
curl "http://localhost:3000/api/search?state=Maharashtra"

📁 Project Structure

bharat-api/
├── src/
│   ├── app.ts                 # Express app configuration
│   ├── index.ts              # Server entry point
│   ├── config/
│   │   ├── database.ts       # Database configuration
│   │   └── environment.ts    # Environment variables
│   ├── controllers/
│   │   └── pincodeController.ts
│   ├── routes/
│   │   └── pincode.ts
│   ├── middleware/
│   │   └── rateLimiter.ts
│   └── scripts/
│       └── importCsv.ts      # CSV import utility
├── migrations/
│   └── 001_create_pincodes_table.ts
├── data/                     # SQLite database files
├── docker-compose.yml        # Production Docker setup
├── docker-compose.dev.yml    # Development Docker setup
├── Dockerfile               # Production container
├── Dockerfile.dev          # Development container
├── india-pincodes.csv      # Pincode data
└── nodemon.json           # Nodemon configuration

🔧 Available Scripts

# Development
npm run dev          # Start development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm start           # Start production server

# Database
npm run migrate     # Run database migrations
npm run setup      # Setup database and import CSV data
npm run import-csv # Import CSV data manually

# Docker
npm run docker:dev   # Development with Docker
npm run docker:prod  # Production with Docker
npm run docker:stop  # Stop Docker containers

🌍 Environment Variables

Copy .env.example to .env and configure:

# Application
NODE_ENV=development
PORT=3000

# Database
DB_CLIENT=sqlite3
DB_FILENAME=./data/development.db

# API Configuration
API_PREFIX=/api
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# CORS
CORS_ORIGIN=*

📊 Data Source

The API includes a comprehensive dataset of Indian pincodes with:

• 🏢 19,000+ locations across India
• 🗺️ All 28 states and 8 union territories
• 📮 Complete pincode coverage from 110001 to 855117
• ✅ Validated and cleaned data

🚀 Future Enhancements

• Migration to PostgreSQL for production scaling
• API key authentication and advanced rate limiting
• Latitude/longitude coordinates for each pincode
• Caching layer with Redis
• API documentation with Swagger/OpenAPI
• Analytics dashboard for usage tracking
• Fuzzy search capabilities
• Bulk lookup endpoints

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Data sourced from India Post official records
• Built with modern web technologies and best practices
• Inspired by the need for reliable Indian location data

---

Made with ❤️ for the Indian developer community

For support or questions, please open an issue on GitHub.