quantaroute-geocoding 1.0.0__py3-none-any.whl

quantaroute_geocoding/offline.py

@@ -0,0 +1,280 @@
+"""
+Offline DigiPin processing using the official DigiPin library
+"""
+
+import math
+from typing import Dict, Tuple, Optional, List
+from .exceptions import OfflineProcessingError, ValidationError
+
+try:
+    import digipin
+    DIGIPIN_AVAILABLE = True
+except ImportError:
+    DIGIPIN_AVAILABLE = False
+
+
+class OfflineProcessor:
+    """
+    Offline DigiPin processor using the official DigiPin library
+    
+    This class provides offline DigiPin operations without requiring API calls.
+    Perfect for processing large datasets or when internet connectivity is limited.
+    """
+    
+    def __init__(self):
+        """Initialize the offline processor"""
+        if not DIGIPIN_AVAILABLE:
+            raise OfflineProcessingError(
+                "DigiPin library not available. Install with: pip install digipin"
+            )
+    
+    def coordinates_to_digipin(self, latitude: float, longitude: float) -> Dict:
+        """
+        Convert coordinates to DigiPin code (offline)
+        
+        Args:
+            latitude: Latitude coordinate
+            longitude: Longitude coordinate
+            
+        Returns:
+            Dict containing DigiPin and coordinates
+        """
+        if not isinstance(latitude, (int, float)) or not isinstance(longitude, (int, float)):
+            raise ValidationError("Latitude and longitude must be numbers")
+        
+        if not (-90 <= latitude <= 90):
+            raise ValidationError("Latitude must be between -90 and 90")
+        
+        if not (-180 <= longitude <= 180):
+            raise ValidationError("Longitude must be between -180 and 180")
+        
+        try:
+            digipin_code = digipin.getDIGIPINFromLatLon(latitude, longitude)
+            
+            if not digipin_code or digipin_code == "Invalid coordinates":
+                raise OfflineProcessingError("Unable to generate DigiPin from coordinates")
+            
+            return {
+                'digipin': digipin_code,
+                'coordinates': {
+                    'latitude': latitude,
+                    'longitude': longitude
+                },
+                'source': 'offline'
+            }
+            
+        except Exception as e:
+            raise OfflineProcessingError(f"Failed to generate DigiPin: {str(e)}")
+    
+    def digipin_to_coordinates(self, digipin_code: str) -> Dict:
+        """
+        Convert DigiPin code to coordinates (offline)
+        
+        Args:
+            digipin_code: The DigiPin code to convert
+            
+        Returns:
+            Dict containing coordinates
+        """
+        if not digipin_code or not digipin_code.strip():
+            raise ValidationError("DigiPin code is required")
+        
+        try:
+            result = digipin.getLatLonFromDIGIPIN(digipin_code.strip())
+            
+            if result == "Invalid DIGIPIN":
+                raise OfflineProcessingError("Invalid DigiPin code")
+            
+            return {
+                'digipin': digipin_code.strip(),
+                'coordinates': {
+                    'latitude': result.latitude,
+                    'longitude': result.longitude
+                },
+                'source': 'offline'
+            }
+            
+        except Exception as e:
+            raise OfflineProcessingError(f"Failed to convert DigiPin: {str(e)}")
+    
+    def validate_digipin(self, digipin_code: str) -> Dict:
+        """
+        Validate DigiPin format (offline)
+        
+        Args:
+            digipin_code: The DigiPin code to validate
+            
+        Returns:
+            Dict containing validation results
+        """
+        if not digipin_code or not digipin_code.strip():
+            return {
+                'isValid': False,
+                'digipin': digipin_code or '',
+                'errors': ['DigiPin is required'],
+                'source': 'offline'
+            }
+        
+        clean_digipin = digipin_code.strip()
+        errors = []
+        
+        # Basic format validation
+        if len(clean_digipin) < 6 or len(clean_digipin) > 20:
+            errors.append('DigiPin must be between 6 and 20 characters long')
+        
+        # Check for valid characters
+        if not all(c.isalnum() or c in '-_' for c in clean_digipin):
+            errors.append('DigiPin can only contain alphanumeric characters, hyphens, and underscores')
+        
+        # Try to validate with DigiPin library
+        is_valid = len(errors) == 0
+        if is_valid:
+            try:
+                result = digipin.getLatLonFromDIGIPIN(clean_digipin)
+                if result == "Invalid DIGIPIN":
+                    is_valid = False
+                    errors.append('DigiPin does not correspond to a valid location')
+            except:
+                is_valid = False
+                errors.append('DigiPin does not correspond to a valid location')
+        
+        return {
+            'isValid': is_valid,
+            'digipin': clean_digipin,
+            'errors': errors if errors else None,
+            'source': 'offline'
+        }
+    
+    def calculate_distance(
+        self, 
+        lat1: float, lon1: float, 
+        lat2: float, lon2: float,
+        unit: str = 'km'
+    ) -> float:
+        """
+        Calculate distance between two coordinates using Haversine formula
+        
+        Args:
+            lat1, lon1: First coordinate pair
+            lat2, lon2: Second coordinate pair
+            unit: Distance unit ('km' or 'miles')
+            
+        Returns:
+            Distance in specified unit
+        """
+        # Convert to radians
+        lat1, lon1, lat2, lon2 = map(math.radians, [lat1, lon1, lat2, lon2])
+        
+        # Haversine formula
+        dlat = lat2 - lat1
+        dlon = lon2 - lon1
+        a = math.sin(dlat/2)**2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlon/2)**2
+        c = 2 * math.asin(math.sqrt(a))
+        
+        # Earth's radius
+        r = 6371 if unit == 'km' else 3956  # km or miles
+        
+        return c * r
+    
+    def get_grid_info(self, digipin_code: str) -> Dict:
+        """
+        Get information about the DigiPin grid
+        
+        Args:
+            digipin_code: The DigiPin code
+            
+        Returns:
+            Dict containing grid information
+        """
+        try:
+            coords = self.digipin_to_coordinates(digipin_code)
+            lat = coords['coordinates']['latitude']
+            lon = coords['coordinates']['longitude']
+            
+            # Each DigiPin represents a 4x4 meter grid
+            grid_size_meters = 4
+            
+            # Calculate approximate grid bounds
+            # 1 degree latitude ≈ 111,320 meters
+            # 1 degree longitude ≈ 111,320 * cos(latitude) meters
+            lat_offset = grid_size_meters / 111320
+            lon_offset = grid_size_meters / (111320 * math.cos(math.radians(lat)))
+            
+            return {
+                'digipin': digipin_code,
+                'center': {
+                    'latitude': lat,
+                    'longitude': lon
+                },
+                'bounds': {
+                    'north': lat + lat_offset/2,
+                    'south': lat - lat_offset/2,
+                    'east': lon + lon_offset/2,
+                    'west': lon - lon_offset/2
+                },
+                'grid_size_meters': grid_size_meters,
+                'area_square_meters': grid_size_meters * grid_size_meters,
+                'source': 'offline'
+            }
+            
+        except Exception as e:
+            raise OfflineProcessingError(f"Failed to get grid info: {str(e)}")
+    
+    def find_nearby_grids(
+        self, 
+        latitude: float, 
+        longitude: float, 
+        radius_meters: int = 100
+    ) -> List[Dict]:
+        """
+        Find nearby DigiPin grids within a radius
+        
+        Args:
+            latitude: Center latitude
+            longitude: Center longitude
+            radius_meters: Search radius in meters
+            
+        Returns:
+            List of nearby DigiPin codes with distances
+        """
+        if radius_meters > 1000:  # Limit to 1km for performance
+            raise ValidationError("Radius cannot exceed 1000 meters")
+        
+        # Calculate grid step size (4 meters per grid)
+        grid_size = 4
+        steps = math.ceil(radius_meters / grid_size)
+        
+        # 1 degree latitude ≈ 111,320 meters
+        lat_step = grid_size / 111320
+        lon_step = grid_size / (111320 * math.cos(math.radians(latitude)))
+        
+        nearby_grids = []
+        
+        for i in range(-steps, steps + 1):
+            for j in range(-steps, steps + 1):
+                test_lat = latitude + (i * lat_step)
+                test_lon = longitude + (j * lon_step)
+                
+                # Calculate actual distance
+                distance = self.calculate_distance(latitude, longitude, test_lat, test_lon) * 1000  # Convert to meters
+                
+                if distance <= radius_meters:
+                    try:
+                        result = self.coordinates_to_digipin(test_lat, test_lon)
+                        nearby_grids.append({
+                            'digipin': result['digipin'],
+                            'coordinates': result['coordinates'],
+                            'distance_meters': round(distance, 2)
+                        })
+                    except:
+                        continue  # Skip invalid coordinates
+        
+        # Sort by distance and remove duplicates
+        seen = set()
+        unique_grids = []
+        for grid in sorted(nearby_grids, key=lambda x: x['distance_meters']):
+            if grid['digipin'] not in seen:
+                seen.add(grid['digipin'])
+                unique_grids.append(grid)
+        
+        return unique_grids

quantaroute_geocoding-1.0.0.dist-info/METADATA

@@ -0,0 +1,349 @@
+Metadata-Version: 2.4
+Name: quantaroute-geocoding
+Version: 1.0.0
+Summary: Python SDK for QuantaRoute Geocoding API with offline DigiPin processing
+Home-page: https://github.com/quantaroute/quantaroute-geocoding-python
+Author: QuantaRoute
+Author-email: QuantaRoute <support@quantaroute.com>
+License: MIT
+Project-URL: Homepage, https://quantaroute.com
+Project-URL: Documentation, https://api.quantaroute.com/v1/digipin/docs
+Project-URL: Repository, https://github.com/quantaroute/quantaroute-geocoding-python
+Project-URL: Bug Tracker, https://github.com/quantaroute/quantaroute-geocoding-python/issues
+Keywords: geocoding,digipin,gis,location,india,address,coordinates
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: digipin>=1.0.0
+Requires-Dist: tqdm>=4.60.0
+Requires-Dist: click>=8.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8; extra == "dev"
+Requires-Dist: mypy>=0.910; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# QuantaRoute Geocoding Python SDK
+
+A comprehensive Python library for geocoding addresses to DigiPin codes with both online API and offline processing capabilities.
+
+## Features
+
+- 🌐 **Online API Integration**: Full access to QuantaRoute Geocoding API
+- 🔌 **Offline Processing**: Process coordinates ↔ DigiPin without internet
+- 📊 **CSV Bulk Processing**: Handle large datasets efficiently
+- 🚀 **CLI Tools**: Command-line interface for quick operations
+- 📈 **Progress Tracking**: Real-time progress bars for bulk operations
+- 🔄 **Retry Logic**: Automatic retry with exponential backoff
+- 🎯 **Rate Limit Handling**: Intelligent rate limit management
+
+## Installation
+
+```bash
+pip install quantaroute-geocoding
+```
+
+For offline DigiPin processing, also install the official DigiPin library:
+
+```bash
+pip install digipin
+```
+
+## Quick Start
+
+### Online API Usage
+
+```python
+from quantaroute_geocoding import QuantaRouteClient
+
+# Initialize client
+client = QuantaRouteClient(api_key="your-api-key")
+
+# Geocode an address
+result = client.geocode("India Gate, New Delhi, India")
+print(f"DigiPin: {result['digipin']}")
+print(f"Coordinates: {result['coordinates']}")
+
+# Convert coordinates to DigiPin
+result = client.coordinates_to_digipin(28.6139, 77.2090)
+print(f"DigiPin: {result['digipin']}")
+
+# Reverse geocode DigiPin
+result = client.reverse_geocode("39J-438-TJC7")
+print(f"Coordinates: {result['coordinates']}")
+```
+
+### Offline Processing
+
+```python
+from quantaroute_geocoding import OfflineProcessor
+
+# Initialize offline processor
+processor = OfflineProcessor()
+
+# Convert coordinates to DigiPin (offline)
+result = processor.coordinates_to_digipin(28.6139, 77.2090)
+print(f"DigiPin: {result['digipin']}")
+
+# Convert DigiPin to coordinates (offline)
+result = processor.digipin_to_coordinates("39J-438-TJC7")
+print(f"Coordinates: {result['coordinates']}")
+
+# Validate DigiPin format
+result = processor.validate_digipin("39J-438-TJC7")
+print(f"Valid: {result['isValid']}")
+```
+
+### CSV Bulk Processing
+
+```python
+from quantaroute_geocoding import CSVProcessor
+
+# Initialize processor
+processor = CSVProcessor(api_key="your-api-key")
+
+# Process addresses to DigiPin
+result = processor.process_geocoding_csv(
+    input_file="addresses.csv",
+    output_file="results.csv",
+    address_column="address"
+)
+
+print(f"Processed {result['total_rows']} rows")
+print(f"Success rate: {result['success_rate']:.1%}")
+
+# Process coordinates to DigiPin (can use offline mode)
+processor_offline = CSVProcessor(use_offline=True)
+result = processor_offline.process_coordinates_to_digipin_csv(
+    input_file="coordinates.csv",
+    output_file="digipins.csv"
+)
+```
+
+## Command Line Interface
+
+The package includes a powerful CLI for batch processing:
+
+### Geocode addresses from CSV
+
+```bash
+# Using API
+quantaroute-geocode geocode addresses.csv results.csv --api-key your-key
+
+# With custom columns
+quantaroute-geocode geocode data.csv output.csv \
+    --address-column street_address \
+    --city-column city_name \
+    --state-column state_name
+```
+
+### Convert coordinates to DigiPin
+
+```bash
+# Online processing
+quantaroute-geocode coords-to-digipin coordinates.csv digipins.csv --api-key your-key
+
+# Offline processing (no API key needed)
+quantaroute-geocode coords-to-digipin coordinates.csv digipins.csv --offline
+```
+
+### Convert DigiPin to coordinates
+
+```bash
+# Online processing
+quantaroute-geocode digipin-to-coords digipins.csv coordinates.csv --api-key your-key
+
+# Offline processing
+quantaroute-geocode digipin-to-coords digipins.csv coordinates.csv --offline
+```
+
+### Single operations
+
+```bash
+# Convert single coordinate to DigiPin
+quantaroute-geocode single-coord-to-digipin 28.6139 77.2090 --offline
+
+# Convert single DigiPin to coordinates
+quantaroute-geocode single-digipin-to-coords "39J-438-TJC7" --offline
+
+# Check API usage
+quantaroute-geocode usage --api-key your-key
+```
+
+## CSV File Formats
+
+### Input CSV for Address Geocoding
+
+```csv
+address,city,state,pincode,country
+"123 Main Street","New Delhi","Delhi","110001","India"
+"456 Park Avenue","Mumbai","Maharashtra","400001","India"
+```
+
+### Input CSV for Coordinates to DigiPin
+
+```csv
+latitude,longitude
+28.6139,77.2090
+19.0760,72.8777
+```
+
+### Input CSV for DigiPin to Coordinates
+
+```csv
+digipin
+39J-438-TJC7
+39J-49J-4867
+```
+
+## Advanced Features
+
+### Webhook Management
+
+```python
+# Register webhook
+webhook = client.register_webhook(
+    url="https://your-app.com/webhook",
+    events=["bulk_processing.completed", "geocoding.completed"]
+)
+
+# List webhooks
+webhooks = client.list_webhooks()
+
+# Delete webhook
+client.delete_webhook(webhook['id'])
+```
+
+### Batch Processing with Progress Callback
+
+```python
+def progress_callback(processed, total, success, errors):
+    print(f"Progress: {processed}/{total} - Success: {success}, Errors: {errors}")
+
+processor = CSVProcessor(api_key="your-key")
+result = processor.process_geocoding_csv(
+    input_file="large_dataset.csv",
+    output_file="results.csv",
+    progress_callback=progress_callback
+)
+```
+
+### Offline Grid Operations
+
+```python
+processor = OfflineProcessor()
+
+# Get grid information
+grid_info = processor.get_grid_info("39J-438-TJC7")
+print(f"Grid center: {grid_info['center']}")
+print(f"Grid bounds: {grid_info['bounds']}")
+
+# Find nearby grids
+nearby = processor.find_nearby_grids(28.6139, 77.2090, radius_meters=100)
+for grid in nearby:
+    print(f"DigiPin: {grid['digipin']}, Distance: {grid['distance_meters']}m")
+
+# Calculate distance between coordinates
+distance = processor.calculate_distance(28.6139, 77.2090, 28.6150, 77.2100)
+print(f"Distance: {distance:.2f} km")
+```
+
+## Configuration
+
+### Environment Variables
+
+Set your API key as an environment variable:
+
+```bash
+export QUANTAROUTE_API_KEY="your-api-key"
+```
+
+### API Configuration
+
+```python
+client = QuantaRouteClient(
+    api_key="your-key",
+    base_url="https://api.quantaroute.com",  # Custom base URL
+    timeout=30,  # Request timeout in seconds
+    max_retries=3  # Maximum retry attempts
+)
+```
+
+### CSV Processor Configuration
+
+```python
+processor = CSVProcessor(
+    api_key="your-key",
+    use_offline=False,  # Use offline processing when possible
+    batch_size=50,  # Records per API batch
+    delay_between_batches=1.0  # Delay in seconds between batches
+)
+```
+
+## Error Handling
+
+```python
+from quantaroute_geocoding import (
+    QuantaRouteError,
+    APIError,
+    RateLimitError,
+    AuthenticationError,
+    ValidationError
+)
+
+try:
+    result = client.geocode("Invalid address")
+except RateLimitError as e:
+    print(f"Rate limit exceeded. Retry after {e.retry_after} seconds")
+except AuthenticationError:
+    print("Invalid API key")
+except ValidationError as e:
+    print(f"Validation error: {e}")
+except APIError as e:
+    print(f"API error: {e} (Status: {e.status_code})")
+```
+
+## Performance Tips
+
+1. **Use Batch Processing**: Process multiple addresses in batches for better performance
+2. **Offline Mode**: Use offline processing for coordinate ↔ DigiPin conversions
+3. **Caching**: The API includes intelligent caching - repeated requests are faster
+4. **Rate Limits**: The SDK handles rate limits automatically with retry logic
+5. **CSV Processing**: Use the CSV processor for large datasets instead of individual API calls
+
+## API Limits
+
+| Tier | Requests/Minute | Monthly Limit | Batch Size |
+|------|----------------|---------------|------------|
+| Free | 10 | 1,000 | 50 |
+| Paid | 100 | 10,000 | 100 |
+| Enterprise | 1,000 | Unlimited | 100 |
+
+## Support
+
+- 📧 Email: support@quantaroute.com
+- 🌐 Website: https://quantaroute.com
+- 📖 API Documentation: https://api.quantaroute.com/v1/digipin/docs
+
+## License
+
+MIT License - see LICENSE file for details.

quantaroute_geocoding-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+quantaroute_geocoding/__init__.py,sha256=22lbjbaAk75zdndnWvU2lCyjlPnx2HPKrUuoYWkEnV0,688
+quantaroute_geocoding/cli.py,sha256=kfVoKtBNC_jeAeqMeKRN5kxpwNEcPhnekTyLwZJFRw0,10626
+quantaroute_geocoding/client.py,sha256=y6aAr5Ka1nlu2epw6rXxiJ8WQpOTAO7O-ef2Ww6EYtY,10644
+quantaroute_geocoding/csv_processor.py,sha256=tmbtE1bQzi2TnKgxOGIQ-H6MWirh-cuG4RRErcCdfco,16096
+quantaroute_geocoding/exceptions.py,sha256=rAkj8K5-AUf31kV8UlmNxQ5IN0m4CIL2qnI6ALas5Ys,1173
+quantaroute_geocoding/offline.py,sha256=oY_sCFWKDes-yC7IQrgWcYxII8teUACBndEDjOXLZYw,9766
+quantaroute_geocoding-1.0.0.dist-info/licenses/LICENSE,sha256=QY7Uoe-MPRTjfyyDM3HOnqtuSqbzyPLATiriEaQ9u90,1068
+quantaroute_geocoding-1.0.0.dist-info/METADATA,sha256=3GgV9uz4RP7xH0hS1EErhokVMxJJwCNByd2JxoplerM,9545
+quantaroute_geocoding-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+quantaroute_geocoding-1.0.0.dist-info/entry_points.txt,sha256=cniijgPLz_Pb6Fiti6aOxaJp1BB_bv60ZOL_oitGCx8,71
+quantaroute_geocoding-1.0.0.dist-info/top_level.txt,sha256=_cyyFLwSH1wYB1HNs_LcZIDQRo1CnvoEsdnKz-cBCr4,22
+quantaroute_geocoding-1.0.0.dist-info/RECORD,,

quantaroute_geocoding-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

quantaroute_geocoding-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+quantaroute-geocode = quantaroute_geocoding.cli:main

quantaroute_geocoding-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 QuantaRoute
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantaroute_geocoding-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+quantaroute_geocoding