bench get-app https://github.com/shridarpatil/postal_db

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=shridarpatil%2Fpostal_db)](https://frappegems.com/gems/apps/shridarpatil/postal_db)

Postal DB - Indian Pincode Database for Frappe

A comprehensive Frappe application containing complete Indian postal data including pincodes, areas, cities, districts, and states. This app provides easy access to Indian geographical and postal information for integration with your Frappe/ERPNext applications.

Features

• Complete Indian Postal Data: Contains all Indian pincodes with corresponding geographical information
• Structured Location Data: Organized by Area, City, District, and State
• Easy Integration: Seamlessly integrates with existing Frappe applications
• Search & Filter: Built-in search and filtering capabilities
• API Access: RESTful API endpoints for external integrations

Installation

Prerequisites

• Frappe Framework (v13 or higher)
• Python 3.6+
• MariaDB/PSQL

Install from GitHub

1. Navigate to your Frappe bench directory:

cd /path/to/your/bench

2. Get the app:

bench get-app https://github.com/shridarpatil/postal_db

3. Install the app on your site:

bench --site your-site-name install-app postal_db

4. Migrate the database:

bench --site your-site-name migrate

5. Restart your bench:

bench restart

Manual Installation

1. Clone the repository:

git clone https://github.com/shridarpatil/postal_db.git
cd postal_db

2. Install in development mode:

bench get-app /path/to/postal_db
bench --site your-site-name install-app postal_db

Usage

Accessing Location Data

Through Frappe Desk

1. Go to your Frappe desk
2. Search for "Location" in the awesome bar
3. Browse, search, and filter postal data

Programmatic Access

import frappe

# Get location by pincode
location = frappe.get_doc("Location", {"pincode": "95221"})
print(f"Area: {location.area}, City: {location.city}")

# Search locations by city
locations = frappe.get_all("Location", 
    filters={"city": "Bilaspur"},
    fields=["pincode", "area", "district", "state"]
)

# Get all locations in a state
hp_locations = frappe.get_all("Location",
    filters={"state": "Himachal Pradesh"},
    fields=["*"]
)

API Endpoints

# Get all locations
GET /api/resource/Location

# Get specific location
GET /api/resource/Location/{location-name}

# Filter by pincode
GET /api/resource/Location?filters=[["pincode","=","95221"]]

# Filter by city
GET /api/resource/Location?filters=[["city","=","Bilaspur"]]

# Filter by state
GET /api/resource/Location?filters=[["state","=","Himachal Pradesh"]]

Integration Examples

Validate Pincode in Custom DocType

import frappe

def validate_pincode(pincode):
    """Validate if pincode exists in postal database"""
    if frappe.db.exists("Location", {"pincode": pincode}):
        return True
    return False

def get_location_details(pincode):
    """Get complete location details by pincode"""
    location = frappe.db.get_value("Location", 
        {"pincode": pincode}, 
        ["area", "city", "district", "state"], 
        as_dict=True
    )
    return location

Auto-fill Address Fields

// Client-side script for auto-filling address
frappe.ui.form.on('Your DocType', {
    pincode: function(frm) {
        if (frm.doc.pincode && frm.doc.pincode.length === 6) {
            frappe.call({
                method: 'frappe.client.get_list',
                args: {
                    doctype: 'Location',
                    filters: {
                        pincode: frm.doc.pincode
                    },
                    fields: ['area', 'city', 'district', 'state']
                },
                callback: function(r) {
                    if (r.message && r.message.length > 0) {
                        let location = r.message[0];
                        frm.set_value('city', location.city);
                        frm.set_value('district', location.district);
                        frm.set_value('state', location.state);
                    }
                }
            });
        }
    }
});

Sample Data

The database contains over 150,000+ postal locations across India. Here are some sample records:

{
  "area": "Bilaspur",
  "city": "Bilaspur",
  "district": "Bilaspur",
  "pincode": "95221",
  "state": "Himachal Pradesh"
}

{
  "area": "Connaught Place",
  "city": "New Delhi",
  "district": "Central Delhi",
  "pincode": "110001",
  "state": "Delhi"
}

{
  "area": "Fort",
  "city": "Mumbai",
  "district": "Mumbai",
  "pincode": "400001",
  "state": "Maharashtra"
}

{
  "area": "Brigade Road",
  "city": "Bangalore",
  "district": "Bangalore Urban",
  "pincode": "560025",
  "state": "Karnataka"
}

DocType Structure

Location DocType Fields:

Field	Type	Description
name	Data	Auto-generated unique identifier
pincode	Data	6-digit postal code
area	Data	Local area/locality name
city	Data	City name
district	Data	District name
state	Data	State name

Data Sources

The postal data is sourced from official Indian Postal Department records and regularly updated to ensure accuracy.

Contributing

1. Fork the repository
2. Create a 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

Support

For support and questions: - Create an issue on GitHub

License

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

Changelog

v1.0.0

• Initial release with complete Indian postal database
• Location DocType with all major fields
• API endpoints for data access
• Search and filter functionality

---

Note: This app contains postal data for educational and development purposes. Please verify critical postal information with official sources for production use.