Download the PHP package dev-giri/pin-india without Composer

PinIndia

A Laravel package for managing and querying Indian post office data. PinIndia provides a comprehensive solution for handling postal addresses, location-based services, and geographic data across India. With over 150,000+ post offices indexed, this package enables developers to build robust location-aware applications with minimal effort.

Features

• Complete Postal Database: Access to all Indian post offices, pincodes, districts, and states
• Geolocation Support: Find nearest post offices based on coordinates or existing postal references
• Hierarchical Data Structure: Navigate through the postal hierarchy (State → District → Pincode → Post Office)
• Optimized Performance: Database indexing on frequently queried fields for fast lookups
• Laravel Integration: Seamless integration with Laravel's ecosystem including migrations, seeders, and Eloquent models
• Official Data Source: All data sourced from the official data.gov.in API

Installation

1. Require the package via Composer

2. Add API key to your .env file

You can obtain an API key from data.gov.in by registering for an account and requesting API access. This key is required for the initial data download during installation.

3. Install the package

This command will:

• Publish the configuration file to your application
• Run migrations to create the necessary database tables
• Download post office data from data.gov.in using your API key
• Seed the database with comprehensive post office data

The installation process may take several minutes as it downloads and processes the complete Indian postal database.

Configuration

You can publish the configuration file manually:

Available configuration options in config/pinindia.php:

Usage

Using the Facade

The package provides a simple facade for common postal queries:

State and District Autocomplete

Implement intelligent address autocomplete with real-time suggestions:

Cascading Dropdowns for Address Selection

Create intuitive address forms with dependent dropdowns:

Response Format

All methods return a collection of PostOfficeResource objects with the following structure:

Use Cases

1. Find Address by User's Current Location

Retrieve the nearest post office details based on the user's current GPS coordinates:

2. Address Autocomplete for Forms

Implement an address autocomplete feature in your forms:

3. Delivery Radius Calculation for E-commerce

Determine if a delivery location is within your service area:

4. Regional Data Analysis

Analyze post office distribution by state or district:

Database Structure

The package creates a relational database structure that mirrors India's postal hierarchy:

• States: Top-level administrative divisions
• Districts: Administrative subdivisions within states
• Circles: Postal administrative regions
• Regions: Subdivisions within postal circles
• Divisions: Operational units within postal regions
• Pincodes: 6-digit postal codes
• Post Offices: Individual post office locations with coordinates

This structure allows for efficient querying and navigation through the postal hierarchy.

Available Commands

Models

The package includes the following Eloquent models:

• State: Represents Indian states and union territories
• District: Represents districts within states
• Circle: Represents postal circles (usually state-level)
• Region: Represents postal regions within circles
• Division: Represents postal divisions within regions
• Pincode: Represents 6-digit postal codes
• PostOffice: Represents individual post office locations

Each model includes appropriate relationships for navigating the postal hierarchy.

Notes

• Data Source: All postal data is sourced from the official data.gov.in API, ensuring accuracy and reliability.
• Data Freshness: The package downloads the latest available postal data during installation. You can refresh the data anytime using the pinindia:download command.
• Performance: The package is optimized for performance with proper database indexing on frequently queried fields.
• Coordinate Accuracy: Geographic coordinates (latitude/longitude) are based on data.gov.in's records and may have varying levels of precision across different regions.
• API Rate Limits: Be aware that data.gov.in may impose rate limits on API requests during the initial data download.
• Storage Requirements: The complete dataset requires approximately 150-200MB of database storage.

Legal Disclaimer

• This package accesses data from data.gov.in. Users must comply with data.gov.in's terms of service when using this package.
• The API key required for this package must be obtained directly from data.gov.in by the end user.
• This package is provided "as is" without warranty of any kind. The accuracy and completeness of postal data depend on data.gov.in's records.
• When implementing location-based features, ensure you comply with applicable privacy laws and obtain appropriate user consent for collecting location data.
• The MIT license of this package applies to the code only, not to the data retrieved from data.gov.in.

Testing

The package includes a comprehensive test suite covering models, facades, resources, and services. To run the tests:

Test Requirements

• The tests are configured to use MySQL by default, as some geospatial functions like acos() are required for distance calculations
• You can configure the test database connection in the phpunit.xml file
• Make sure you have a MySQL database named pinindia_test created before running the tests

Running Specific Test Groups

License

This package is open-sourced software licensed under the MIT license.