🇮🇳 Bharat Location Hub

A comprehensive REST API for Indian locations with 500,000+ records covering villages, cities, districts, and administrative divisions.

🌐 Live Demo

Website: https://india-location-hub.in/

🚀 Features

• Complete Database: All 36 states, 766+ districts, 6900+ talukas, and 650,000+ villages
• Smart Search: Fast search across all location levels
• REST API: Easy integration with web and mobile applications
• Real-time Data: Firebase-powered backend for instant updates
• Admin Panel: Secure admin access for data management
• GitHub Pages Ready: Static deployment compatible
• Mobile Responsive: Works perfectly on all devices

🌐 Live Demo

Visit: https://recentlystarted.github.io/bharat-location-hub/

📖 API Documentation

Base URL

https://recentlystarted.github.io/bharat-location-hub/api

Endpoints

Get All States

GET /api/states

Get Districts by State

GET /api/states/{stateName}/districts

Get Talukas by District

GET /api/districts/{stateName}/{districtName}/talukas

Get Villages by Taluka

GET /api/talukas/{stateName}/{districtName}/{talukaName}/villages

Search Locations

GET /api/search?q={searchQuery}&limit={limit}

Get Location by Code

GET /api/locations/by-code/{villageCode}

Get Statistics

GET /api/stats

Response Format

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1000,
    "totalPages": 20
  }
}

🛠️ Installation & Setup

Prerequisites

• Node.js 18+
• npm or pnpm
• Firebase account

Local Development

1. Clone the repository

   git clone https://github.com/Recentlystarted/bharat-location-hub.git
   cd bharat-location-hub

2. Install dependencies

   pnpm install
   # or
   npm install

3. Set up Firebase (See FIREBASE_SETUP.md)

   • Create Firebase project
   • Set up Firestore database
   • Update src/config/firebase.ts with your config

4. Upload location data to Firebase

   node scripts/uploadToFirebase.js

5. Start development server

   pnpm dev
   # or
   npm run dev

Deployment to GitHub Pages

1. Build the project

   pnpm build

2. Deploy to GitHub Pages

   pnpm deploy

📁 Project Structure

bharat-location-hub/
├── public/
│   └── india_locations.json     # Raw location data (98MB)
├── src/
│   ├── components/              # React components
│   ├── config/
│   │   └── firebase.ts          # Firebase configuration
│   ├── services/
│   │   ├── locationService.ts   # Location data operations
│   │   ├── apiService.ts        # API service layer
│   │   └── authService.ts       # Authentication service
│   ├── types/
│   │   └── location.ts          # TypeScript interfaces
│   ├── utils/
│   │   └── codeGenerator.ts     # Utility functions
│   └── App.tsx                  # Main React component
├── scripts/
│   └── uploadToFirebase.js      # Data migration script
└── FIREBASE_SETUP.md            # Firebase setup guide

🔧 Configuration

Firebase Config

Update src/config/firebase.ts:

const firebaseConfig = {
  apiKey: "your-api-key",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project-id",
  storageBucket: "your-project.appspot.com",
  messagingSenderId: "123456789",
  appId: "your-app-id"
};

Environment Variables

Create .env file:

VITE_FIREBASE_API_KEY=your-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789
VITE_FIREBASE_APP_ID=your-app-id

📊 Data Structure

The location data follows this hierarchy:

State
└── District
    └── Taluka (Sub-district)
        └── Village

Location Document Schema

interface LocationDocument {
  id: string;
  stateName: string;
  stateCode: string;
  districtName: string;
  districtCode: string;
  talukaName: string;
  talukaCode: string;
  villageName: string;
  villageCode: string;
  uniqueCode: string;        // Auto-generated: ST-DIS-VIL-XXXX
  fullPath: string;          // Full hierarchy path
  searchText: string;        // Optimized for search
  createdAt: Date;
  updatedAt: Date;
}

🔐 Admin Features

• Secure Authentication: Firebase Auth with role-based access
• Data Management: Add, edit, delete locations
• Unique Code Generation: Automatic unique identifiers
• Batch Operations: Bulk data management
• Statistics Dashboard: Real-time database stats

🌍 Use Cases

Web Applications

import { ApiService } from './src/services/apiService';

// Get all states
const states = await ApiService.getStates();

// Search locations
const results = await ApiService.searchLocations('Mumbai');

// Get districts by state
const districts = await ApiService.getDistrictsByState('MAHARASHTRA');

Mobile Applications

// React Native example
const API_BASE = 'https://recentlystarted.github.io/bharat-location-hub/api';

const response = await fetch(`${API_BASE}/states`);
const { data: states } = await response.json();

External APIs

# cURL example
curl "https://recentlystarted.github.io/bharat-location-hub/api/search?q=Delhi"

📈 Performance

• Fast Search: Optimized search across 650K+ locations
• Efficient Pagination: Chunked data loading
• CDN Delivery: GitHub Pages global distribution
• Caching: Firebase caching for better performance
• Mobile Optimized: Responsive design for all devices

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Data sourced from official Indian government sources
• Built with React, TypeScript, and Firebase
• Icons by Lucide React
• Deployed on GitHub Pages

📞 Support

For support, email your-email@domain.com or create an issue on GitHub.

🔗 Links

• Live Demo
• API Documentation
• Firebase Setup Guide
• GitHub Repository

---

Made with ❤️ for developers building location-aware applications in India.