quantaroute-geocoding 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

quantaroute_geocoding/__init__.py

@@ -5,11 +5,12 @@ A Python library for geocoding addresses to DigiPin codes with both online API
 and offline processing capabilities.
 """
 
-__version__ = "1.0.2"
+__version__ = "1.0.4"
 __author__ = "QuantaRoute"
 __email__ = "support@quantaroute.com"
 
 from .client import QuantaRouteClient
+from .location_lookup import LocationLookupClient
 from .offline import OfflineProcessor
 from .csv_processor import CSVProcessor
 from .exceptions import (
@@ -22,6 +23,7 @@ from .exceptions import (
 
 __all__ = [
     "QuantaRouteClient",
+    "LocationLookupClient",
     "OfflineProcessor", 
     "CSVProcessor",
     "QuantaRouteError",

quantaroute_geocoding/cli.py

@@ -8,14 +8,15 @@ from typing import Optional
 
 from .csv_processor import CSVProcessor
 from .client import QuantaRouteClient
+from .location_lookup import LocationLookupClient
 from .offline import OfflineProcessor
 from .exceptions import QuantaRouteError
 
 
 @click.group()
-@click.version_option(version="1.0.0")
+@click.version_option(version="2.0.0")
 def main():
-    """QuantaRoute Geocoding CLI - Process addresses and coordinates with DigiPin"""
+    """QuantaRoute Geocoding CLI - Revolutionary location intelligence with DigiPin and administrative boundaries"""
     pass
 
 
@@ -277,5 +278,140 @@ def single_digipin_to_coords(digipin_code: str, api_key: Optional[str], offline:
         click.echo(f"Unexpected error: {str(e)}", err=True)
 
 
+# 🚀 REVOLUTIONARY LOCATION LOOKUP COMMANDS
+
+@main.command()
+@click.argument('latitude', type=float)
+@click.argument('longitude', type=float)
+@click.option('--api-key', envvar='QUANTAROUTE_API_KEY', required=True, help='QuantaRoute API key')
+def location_lookup(latitude: float, longitude: float, api_key: str):
+    """🚀 REVOLUTIONARY: Get administrative boundaries from coordinates"""
+    
+    try:
+        client = LocationLookupClient(api_key)
+        result = client.lookup_coordinates(latitude, longitude)
+        
+        click.echo("🚀 REVOLUTIONARY LOCATION LOOKUP RESULT")
+        click.echo("=" * 50)
+        click.echo(f"📍 Coordinates: {latitude}, {longitude}")
+        click.echo(f"📮 Pincode: {result.get('pincode', 'N/A')}")
+        click.echo(f"🏢 Office Name: {result.get('office_name', 'N/A')}")
+        click.echo(f"🏛️ Division: {result.get('division', 'N/A')}")
+        click.echo(f"🌍 Region: {result.get('region', 'N/A')}")
+        click.echo(f"⭕ Circle: {result.get('circle', 'N/A')}")
+        click.echo(f"🗺️ DigiPin: {result.get('digipin', 'N/A')}")
+        
+        if result.get('cached'):
+            click.echo(f"⚡ Response Time: {result.get('response_time_ms', 0)}ms (cached)")
+        else:
+            click.echo(f"🔍 Response Time: {result.get('response_time_ms', 0)}ms (database)")
+        
+        click.echo("\n✨ This precision is not available from government services!")
+        
+    except QuantaRouteError as e:
+        click.echo(f"❌ Error: {str(e)}", err=True)
+    except Exception as e:
+        click.echo(f"💥 Unexpected error: {str(e)}", err=True)
+
+
+@main.command()
+@click.argument('digipin_code')
+@click.option('--api-key', envvar='QUANTAROUTE_API_KEY', required=True, help='QuantaRoute API key')
+def location_from_digipin(digipin_code: str, api_key: str):
+    """🚀 REVOLUTIONARY: Get administrative boundaries from DigiPin"""
+    
+    try:
+        client = LocationLookupClient(api_key)
+        result = client.lookup_digipin(digipin_code)
+        
+        click.echo("🚀 REVOLUTIONARY LOCATION LOOKUP FROM DIGIPIN")
+        click.echo("=" * 55)
+        click.echo(f"🔢 DigiPin: {digipin_code}")
+        click.echo(f"📮 Pincode: {result.get('pincode', 'N/A')}")
+        click.echo(f"🏢 Office Name: {result.get('office_name', 'N/A')}")
+        click.echo(f"🏛️ Division: {result.get('division', 'N/A')}")
+        click.echo(f"🌍 Region: {result.get('region', 'N/A')}")
+        click.echo(f"⭕ Circle: {result.get('circle', 'N/A')}")
+        
+        coords = result.get('coordinates', {})
+        if coords:
+            click.echo(f"📍 Coordinates: {coords.get('latitude', 'N/A')}, {coords.get('longitude', 'N/A')}")
+        
+        if result.get('cached'):
+            click.echo(f"⚡ Response Time: {result.get('response_time_ms', 0)}ms (cached)")
+        else:
+            click.echo(f"🔍 Response Time: {result.get('response_time_ms', 0)}ms (database)")
+        
+        click.echo("\n✨ Administrative boundary precision that governments don't provide!")
+        
+    except QuantaRouteError as e:
+        click.echo(f"❌ Error: {str(e)}", err=True)
+    except Exception as e:
+        click.echo(f"💥 Unexpected error: {str(e)}", err=True)
+
+
+@main.command()
+@click.option('--api-key', envvar='QUANTAROUTE_API_KEY', required=True, help='QuantaRoute API key')
+def location_stats(api_key: str):
+    """📊 Get live statistics about the revolutionary Location Lookup service"""
+    
+    try:
+        client = LocationLookupClient(api_key)
+        stats = client.get_statistics()
+        
+        click.echo("📊 REVOLUTIONARY LOCATION LOOKUP STATISTICS")
+        click.echo("=" * 50)
+        click.echo(f"🗺️ Total Boundaries: {stats.get('total_boundaries', 'N/A'):,}")
+        click.echo(f"🏛️ Total States: {stats.get('total_states', 'N/A')}")
+        click.echo(f"📮 Total Divisions: {stats.get('total_divisions', 'N/A')}")
+        click.echo(f"⚡ Cache Size: {stats.get('cache_size', 'N/A')}")
+        
+        performance = stats.get('performance_metrics', {})
+        if performance:
+            click.echo(f"\n⚡ PERFORMANCE METRICS:")
+            click.echo(f"   Average Response Time: {performance.get('avg_response_time_ms', 'N/A')}ms")
+            click.echo(f"   Cache Hit Rate: {performance.get('cache_hit_rate', 'N/A')}%")
+            click.echo(f"   Total Requests: {performance.get('total_requests', 'N/A'):,}")
+        
+        click.echo("\n🚀 Revolutionary service with 36,000+ postal boundaries!")
+        click.echo("✨ Precision that even government services don't provide!")
+        
+    except QuantaRouteError as e:
+        click.echo(f"❌ Error: {str(e)}", err=True)
+    except Exception as e:
+        click.echo(f"💥 Unexpected error: {str(e)}", err=True)
+
+
+@main.command()
+@click.argument('input_file', type=click.Path(exists=True))
+@click.argument('output_file', type=click.Path())
+@click.option('--api-key', envvar='QUANTAROUTE_API_KEY', required=True, help='QuantaRoute API key')
+@click.option('--latitude-column', default='latitude', help='Name of latitude column')
+@click.option('--longitude-column', default='longitude', help='Name of longitude column')
+@click.option('--batch-size', default=50, help='Batch size for API requests')
+def location_lookup_csv(
+    input_file: str,
+    output_file: str,
+    api_key: str,
+    latitude_column: str,
+    longitude_column: str,
+    batch_size: int
+):
+    """🚀 REVOLUTIONARY: Batch location lookup from CSV coordinates"""
+    
+    try:
+        # This would need to be implemented in csv_processor.py
+        click.echo("🚀 REVOLUTIONARY BATCH LOCATION LOOKUP")
+        click.echo("=" * 45)
+        click.echo(f"📁 Input: {input_file}")
+        click.echo(f"📁 Output: {output_file}")
+        click.echo(f"📊 Batch Size: {batch_size}")
+        click.echo("\n⚠️ CSV Location Lookup processing coming soon!")
+        click.echo("✨ Will process thousands of coordinates to administrative boundaries!")
+        
+    except Exception as e:
+        click.echo(f"💥 Unexpected error: {str(e)}", err=True)
+
+
 if __name__ == '__main__':
     main()

quantaroute_geocoding/client.py

@@ -39,7 +39,7 @@ class QuantaRouteClient:
         self.session = requests.Session()
         self.session.headers.update({
             'x-api-key': api_key,
-            'User-Agent': 'quantaroute-geocoding-python/1.0.0',
+            'User-Agent': 'quantaroute-geocoding-python/2.0.0',
             'Content-Type': 'application/json'
         })
     
@@ -310,3 +310,114 @@ class QuantaRouteClient:
         
         response = self._make_request('DELETE', f'/v1/digipin/webhooks/{webhook_id}')
         return response
+    
+    # 🚀 REVOLUTIONARY LOCATION LOOKUP METHODS
+    
+    def lookup_location_from_coordinates(self, latitude: float, longitude: float) -> Dict:
+        """
+        🚀 REVOLUTIONARY: Get administrative boundaries from coordinates
+        
+        This is a revolutionary service that provides administrative boundary lookup
+        with precision that even government services don't offer.
+        
+        Args:
+            latitude: Latitude coordinate
+            longitude: Longitude coordinate
+            
+        Returns:
+            Dict containing administrative boundary information:
+            - pincode: 6-digit postal code
+            - office_name: Post office name
+            - division: Postal division
+            - region: Postal region
+            - circle: Postal circle
+            - state: State name
+            - coordinates: Input coordinates
+            - digipin: DigiPin code for the location
+            - cached: Whether result was from cache
+            - response_time_ms: Response time in milliseconds
+        """
+        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")
+        
+        data = {
+            'latitude': float(latitude),
+            'longitude': float(longitude)
+        }
+        
+        response = self._make_request('POST', '/v1/location/lookup', data)
+        return response.get('data', {})
+    
+    def lookup_location_from_digipin(self, digipin: str) -> Dict:
+        """
+        🚀 REVOLUTIONARY: Get administrative boundaries from DigiPin
+        
+        Args:
+            digipin: DigiPin code (format: XXX-XXX-XXXX)
+            
+        Returns:
+            Dict containing administrative boundary information
+        """
+        if not digipin or not digipin.strip():
+            raise ValidationError("DigiPin is required")
+        
+        # Use the LocationLookupClient for this operation
+        from .location_lookup import LocationLookupClient
+        location_client = LocationLookupClient(
+            api_key=self.api_key,
+            base_url=self.base_url,
+            timeout=self.timeout,
+            max_retries=self.max_retries
+        )
+        
+        return location_client.lookup_digipin(digipin)
+    
+    def batch_location_lookup(self, locations: List[Dict]) -> Dict:
+        """
+        🚀 REVOLUTIONARY: Batch lookup for multiple locations
+        
+        Args:
+            locations: List of location dictionaries, each containing either:
+                      - {'latitude': float, 'longitude': float}
+                      - {'digipin': str}
+            
+        Returns:
+            Dict containing batch processing results with administrative boundaries
+        """
+        if not locations or not isinstance(locations, list):
+            raise ValidationError("Locations must be a non-empty list")
+        
+        if len(locations) > 100:
+            raise ValidationError("Maximum 100 locations allowed per batch")
+        
+        # Use the LocationLookupClient for this operation
+        from .location_lookup import LocationLookupClient
+        location_client = LocationLookupClient(
+            api_key=self.api_key,
+            base_url=self.base_url,
+            timeout=self.timeout,
+            max_retries=self.max_retries
+        )
+        
+        return location_client.batch_lookup(locations)
+    
+    def get_location_statistics(self) -> Dict:
+        """
+        📊 Get live statistics about the revolutionary Location Lookup service
+        
+        Returns:
+            Dict containing:
+            - total_boundaries: Total number of postal boundaries (36,000+)
+            - total_states: Number of states covered
+            - total_divisions: Number of postal divisions
+            - cache_size: Current cache size
+            - performance_metrics: Response time statistics
+        """
+        response = self._make_request('GET', '/v1/location/stats')
+        return response.get('data', {})

quantaroute_geocoding/location_lookup.py

@@ -0,0 +1,293 @@
+"""
+Revolutionary Location Lookup Client
+
+Provides administrative boundary lookup capabilities - a service that even
+the government doesn't provide at this level of precision and accessibility.
+"""
+
+import requests
+import time
+from typing import Dict, List, Optional, Union
+from .exceptions import APIError, RateLimitError, AuthenticationError, ValidationError
+
+
+class LocationLookupClient:
+    """
+    Revolutionary Location Lookup Client
+    
+    Get administrative boundaries (state, division, locality, pincode) from
+    coordinates or DigiPin codes. Access to 36,000+ postal boundaries across India.
+    """
+    
+    def __init__(
+        self, 
+        api_key: str, 
+        base_url: str = "https://api.quantaroute.com",
+        timeout: int = 30,
+        max_retries: int = 3
+    ):
+        """
+        Initialize the Location Lookup client
+        
+        Args:
+            api_key: Your QuantaRoute API key
+            base_url: Base URL for the API (default: https://api.quantaroute.com)
+            timeout: Request timeout in seconds (default: 30)
+            max_retries: Maximum number of retries for failed requests (default: 3)
+        """
+        self.api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.session = requests.Session()
+        self.session.headers.update({
+            'x-api-key': api_key,
+            'User-Agent': 'quantaroute-geocoding-python/2.0.0',
+            'Content-Type': 'application/json'
+        })
+    
+    def _make_request(
+        self, 
+        method: str, 
+        endpoint: str, 
+        data: Optional[Dict] = None,
+        params: Optional[Dict] = None
+    ) -> Dict:
+        """Make HTTP request with retry logic"""
+        url = f"{self.base_url}{endpoint}"
+        
+        for attempt in range(self.max_retries + 1):
+            try:
+                if method.upper() == 'GET':
+                    response = self.session.get(url, params=params, timeout=self.timeout)
+                else:
+                    response = self.session.post(url, json=data, params=params, timeout=self.timeout)
+                
+                # Handle rate limiting
+                if response.status_code == 429:
+                    retry_after = int(response.headers.get('Retry-After', 60))
+                    if attempt < self.max_retries:
+                        time.sleep(retry_after)
+                        continue
+                    raise RateLimitError(
+                        "Rate limit exceeded", 
+                        retry_after=retry_after
+                    )
+                
+                # Handle authentication errors
+                if response.status_code == 401:
+                    raise AuthenticationError()
+                
+                # Handle other client/server errors
+                if not response.ok:
+                    try:
+                        error_data = response.json()
+                        message = error_data.get('message', f'HTTP {response.status_code}')
+                        error_code = error_data.get('code')
+                    except:
+                        message = f'HTTP {response.status_code}: {response.text}'
+                        error_code = None
+                    
+                    raise APIError(message, response.status_code, error_code)
+                
+                return response.json()
+                
+            except requests.exceptions.RequestException as e:
+                if attempt < self.max_retries:
+                    time.sleep(2 ** attempt)  # Exponential backoff
+                    continue
+                raise APIError(f"Request failed: {str(e)}")
+        
+        raise APIError("Max retries exceeded")
+    
+    def lookup_coordinates(self, latitude: float, longitude: float) -> Dict:
+        """
+        🚀 REVOLUTIONARY: Get administrative boundaries from coordinates
+        
+        Args:
+            latitude: Latitude coordinate
+            longitude: Longitude coordinate
+            
+        Returns:
+            Dict containing administrative boundary information:
+            - pincode: 6-digit postal code
+            - office_name: Post office name
+            - division: Postal division
+            - region: Postal region
+            - circle: Postal circle
+            - state: State name
+            - coordinates: Input coordinates
+            - digipin: DigiPin code for the location
+            - cached: Whether result was from cache
+            - response_time_ms: Response time in milliseconds
+        """
+        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")
+        
+        data = {
+            'latitude': float(latitude),
+            'longitude': float(longitude)
+        }
+        
+        response = self._make_request('POST', '/v1/location/lookup', data)
+        return response.get('data', {})
+    
+    def lookup_digipin(self, digipin: str) -> Dict:
+        """
+        🚀 REVOLUTIONARY: Get administrative boundaries from DigiPin
+        
+        Args:
+            digipin: DigiPin code (format: XXX-XXX-XXXX)
+            
+        Returns:
+            Dict containing administrative boundary information
+        """
+        if not digipin or not digipin.strip():
+            raise ValidationError("DigiPin is required")
+        
+        # Convert DigiPin to coordinates first, then lookup
+        from .offline import OfflineProcessor
+        processor = OfflineProcessor()
+        
+        try:
+            coords_result = processor.digipin_to_coordinates(digipin)
+            if coords_result and 'coordinates' in coords_result:
+                coords = coords_result['coordinates']
+                lat = coords['latitude']
+                lng = coords['longitude']
+                return self.lookup_coordinates(lat, lng)
+            else:
+                raise ValidationError("Invalid DigiPin format")
+        except Exception as e:
+            raise ValidationError(f"DigiPin conversion failed: {str(e)}")
+    
+    def batch_lookup(self, locations: List[Dict]) -> Dict:
+        """
+        🚀 REVOLUTIONARY: Batch lookup for multiple locations
+        
+        Args:
+            locations: List of location dictionaries, each containing either:
+                      - {'latitude': float, 'longitude': float}
+                      - {'digipin': str}
+            
+        Returns:
+            Dict containing batch processing results with administrative boundaries
+        """
+        if not locations or not isinstance(locations, list):
+            raise ValidationError("Locations must be a non-empty list")
+        
+        if len(locations) > 100:
+            raise ValidationError("Maximum 100 locations allowed per batch")
+        
+        # Validate and normalize locations
+        normalized_locations = []
+        for i, loc in enumerate(locations):
+            if not isinstance(loc, dict):
+                raise ValidationError(f"Location {i+1} must be a dictionary")
+            
+            if 'latitude' in loc and 'longitude' in loc:
+                # Coordinate-based lookup
+                if not isinstance(loc['latitude'], (int, float)) or not isinstance(loc['longitude'], (int, float)):
+                    raise ValidationError(f"Location {i+1}: latitude and longitude must be numbers")
+                normalized_locations.append({
+                    'latitude': float(loc['latitude']),
+                    'longitude': float(loc['longitude'])
+                })
+            elif 'digipin' in loc:
+                # DigiPin-based lookup - convert to coordinates
+                from .offline import OfflineProcessor
+                processor = OfflineProcessor()
+                try:
+                    coords_result = processor.digipin_to_coordinates(loc['digipin'])
+                    if coords_result and 'coordinates' in coords_result:
+                        lat, lng = coords_result['coordinates']
+                        normalized_locations.append({
+                            'latitude': lat,
+                            'longitude': lng,
+                            'original_digipin': loc['digipin']
+                        })
+                    else:
+                        raise ValidationError(f"Location {i+1}: Invalid DigiPin format")
+                except Exception as e:
+                    raise ValidationError(f"Location {i+1}: DigiPin conversion failed: {str(e)}")
+            else:
+                raise ValidationError(f"Location {i+1} must contain either 'latitude'+'longitude' or 'digipin'")
+        
+        data = {'locations': normalized_locations}
+        response = self._make_request('POST', '/v1/location/batch-lookup', data)
+        return response.get('data', {})
+    
+    def get_statistics(self) -> Dict:
+        """
+        📊 Get live statistics about the Location Lookup service
+        
+        Returns:
+            Dict containing:
+            - total_boundaries: Total number of postal boundaries
+            - total_states: Number of states covered
+            - total_divisions: Number of postal divisions
+            - cache_size: Current cache size
+            - performance_metrics: Response time statistics
+        """
+        response = self._make_request('GET', '/v1/location/stats')
+        return response.get('data', {})
+    
+    def get_coverage_info(self) -> Dict:
+        """
+        🌍 Get coverage information about the Location Lookup service
+        
+        Returns:
+            Dict containing coverage details and service capabilities
+        """
+        response = self._make_request('GET', '/v1/location')
+        return response
+    
+    def find_nearby_boundaries(
+        self, 
+        latitude: float, 
+        longitude: float, 
+        radius_km: float = 5.0,
+        limit: int = 10
+    ) -> List[Dict]:
+        """
+        🎯 Find nearby postal boundaries (experimental feature)
+        
+        Args:
+            latitude: Center latitude
+            longitude: Center longitude
+            radius_km: Search radius in kilometers (default: 5.0)
+            limit: Maximum number of results (default: 10, max: 50)
+            
+        Returns:
+            List of nearby postal boundaries with distances
+        """
+        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")
+        
+        if radius_km <= 0 or radius_km > 100:
+            raise ValidationError("Radius must be between 0 and 100 km")
+        
+        if limit > 50:
+            limit = 50
+        
+        params = {
+            'lat': latitude,
+            'lng': longitude,
+            'radius': radius_km,
+            'limit': limit
+        }
+        
+        response = self._make_request('GET', '/v1/location/nearby', params=params)
+        return response.get('data', [])

{quantaroute_geocoding-1.0.2.dist-info → quantaroute_geocoding-1.0.4.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: quantaroute-geocoding
-Version: 1.0.2
-Summary: Python SDK for QuantaRoute Geocoding API with offline DigiPin processing
+Version: 1.0.4
+Summary: Revolutionary Python SDK for QuantaRoute Geocoding API with Location Lookup and offline DigiPin processing
 Home-page: https://github.com/quantaroute/quantaroute-geocoding-python
 Author: QuantaRoute
 Author-email: QuantaRoute <support@quantaroute.com>
@@ -10,7 +10,7 @@ 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
+Keywords: geocoding,digipin,gis,location,india,address,coordinates,administrative-boundaries,pincode,postal-lookup,location-intelligence
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -44,10 +44,18 @@ 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.
+A **revolutionary** Python library for geocoding addresses to DigiPin codes with **groundbreaking Location Lookup API** and offline processing capabilities.
 
-## Features
+## 🚀 Revolutionary Features
 
+### 🎯 **NEW: Location Lookup API** - *Service that even government doesn't provide!*
+- 🗺️ **Administrative Boundary Lookup**: Get state, division, locality, pincode from coordinates
+- 📍 **36,000+ Postal Boundaries**: Complete coverage across India
+- ⚡ **Sub-100ms Response**: Cached responses with database fallback
+- 🎯 **Government-Level Precision**: Accuracy that official services don't offer
+- 🔄 **Batch Processing**: Up to 100 locations per request
+
+### 🌟 **Core Features**
 - 🌐 **Online API Integration**: Full access to QuantaRoute Geocoding API
 - 🔌 **Offline Processing**: Process coordinates ↔ DigiPin without internet
 - 📊 **CSV Bulk Processing**: Handle large datasets efficiently
@@ -70,14 +78,39 @@ pip install digipin
 
 ## Quick Start
 
-### Online API Usage
+### 🚀 **NEW: Revolutionary Location Lookup API**
 
 ```python
-from quantaroute_geocoding import QuantaRouteClient
+from quantaroute_geocoding import QuantaRouteClient, LocationLookupClient
 
 # Initialize client
 client = QuantaRouteClient(api_key="your-api-key")
 
+# 🚀 REVOLUTIONARY: Get administrative boundaries from coordinates
+result = client.lookup_location_from_coordinates(28.6139, 77.2090)
+print(f"Pincode: {result['pincode']}")           # 110001
+print(f"Office: {result['office_name']}")        # New Delhi GPO
+print(f"Division: {result['division']}")         # New Delhi GPO
+print(f"Circle: {result['circle']}")             # Delhi
+print(f"DigiPin: {result['digipin']}")           # 39J-438-TJC7
+print(f"Response Time: {result['response_time_ms']}ms")  # <100ms
+
+# 🚀 REVOLUTIONARY: Get boundaries from DigiPin
+result = client.lookup_location_from_digipin("39J-438-TJC7")
+print(f"Pincode: {result['administrative_info']['pincode']}")
+print(f"State: {result['administrative_info']['state']}")
+print(f"Division: {result['administrative_info']['division']}")
+print(f"Locality: {result['administrative_info']['locality']}")
+
+# 📊 Get live statistics (36,000+ boundaries)
+stats = client.get_location_statistics()
+print(f"Total Boundaries: {stats['total_boundaries']:,}")
+print(f"Total States: {stats['total_states']}")
+```
+
+### 🌟 **Traditional Geocoding API**
+
+```python
 # Geocode an address
 result = client.geocode("India Gate, New Delhi, India")
 print(f"DigiPin: {result['digipin']}")
@@ -141,9 +174,25 @@ result = processor_offline.process_coordinates_to_digipin_csv(
 
 ## Command Line Interface
 
-The package includes a powerful CLI for batch processing:
+The package includes a **revolutionary** CLI with Location Lookup capabilities:
 
-### Geocode addresses from CSV
+### 🚀 **NEW: Revolutionary Location Lookup Commands**
+
+```bash
+# Get administrative boundaries from coordinates
+quantaroute-geocode location-lookup 28.6139 77.2090 --api-key your-key
+
+# Get boundaries from DigiPin
+quantaroute-geocode location-from-digipin "39J-438-TJC7" --api-key your-key
+
+# Get live statistics (36,000+ boundaries)
+quantaroute-geocode location-stats --api-key your-key
+
+# Batch location lookup from CSV (coming soon)
+quantaroute-geocode location-lookup-csv coordinates.csv boundaries.csv --api-key your-key
+```
+
+### 🌟 **Traditional Geocoding Commands**
 
 ```bash
 # Using API
@@ -215,6 +264,77 @@ digipin
 39J-49J-4867
 ```
 
+## 🚀 Revolutionary Location Lookup API
+
+### Dedicated Location Lookup Client
+
+```python
+from quantaroute_geocoding import LocationLookupClient
+
+# Initialize dedicated location client
+location_client = LocationLookupClient(api_key="your-api-key")
+
+# Single coordinate lookup
+result = location_client.lookup_coordinates(28.6139, 77.2090)
+print(f"📮 Pincode: {result['pincode']}")
+print(f"🏢 Office: {result['office_name']}")
+print(f"🏛️ Division: {result['division']}")
+print(f"⚡ Response Time: {result['response_time_ms']}ms")
+
+# DigiPin to boundaries
+result = location_client.lookup_digipin("39J-438-TJC7")
+print(f"Administrative boundaries: {result}")
+
+# Batch processing (up to 100 locations)
+locations = [
+    {"latitude": 28.6139, "longitude": 77.2090},
+    {"latitude": 19.0760, "longitude": 72.8777},
+    {"digipin": "39J-438-TJC7"}
+]
+results = location_client.batch_lookup(locations)
+print(f"Processed {len(results['results'])} locations")
+
+# Live statistics
+stats = location_client.get_statistics()
+print(f"🗺️ Total Boundaries: {stats['total_boundaries']:,}")
+print(f"⚡ Cache Size: {stats['cache_size']}")
+
+# Coverage information
+coverage = location_client.get_coverage_info()
+print(f"Service capabilities: {coverage}")
+```
+
+### Location Lookup Output Format
+
+```json
+{
+  "pincode": "110001",
+  "office_name": "New Delhi GPO",
+  "division": "New Delhi GPO",
+  "region": "",
+  "circle": "Delhi",
+  "coordinates": {
+    "latitude": 28.6139,
+    "longitude": 77.2090
+  },
+  "digipin": "39J-438-TJC7",
+  "cached": true,
+  "response_time_ms": 45
+}
+```
+
+### Why This is Revolutionary
+
+🎯 **Government-Level Precision**: Access to administrative boundaries that even government APIs don't provide at this level of detail and accessibility.
+
+📍 **36,000+ Boundaries**: Complete coverage of Indian postal boundaries with sub-district level precision.
+
+⚡ **Performance**: Sub-100ms cached responses, <500ms database queries.
+
+🔄 **Batch Processing**: Process up to 100 locations in a single API call.
+
+✨ **Unique Value**: The only service providing this level of administrative boundary lookup precision for India.
+
 ## Advanced Features
 
 ### Webhook Management
@@ -332,17 +452,51 @@ except APIError as e:
 
 ## API Limits
 
+### Traditional Geocoding API
+
 | Tier | Requests/Minute | Monthly Limit | Batch Size |
 |------|----------------|---------------|------------|
 | Free | 10 | 1,000 | 50 |
 | Paid | 100 | 10,000 | 100 |
 | Enterprise | 1,000 | Unlimited | 100 |
 
+### 🚀 Revolutionary Location Lookup API
+
+| Tier | Requests/Minute | Monthly Limit | Batch Size | Boundaries |
+|------|----------------|---------------|------------|------------|
+| Free | 20 | 2,000 | 50 | 36,000+ |
+| Paid | 200 | 20,000 | 100 | 36,000+ |
+| Enterprise | 2,000 | Unlimited | 100 | 36,000+ |
+
+**Performance Guarantees:**
+- ⚡ Cached responses: <100ms
+- 🔍 Database queries: <500ms
+- 📊 Batch processing: <50ms per location
+- 🎯 99.9% uptime SLA (Enterprise)
+
 ## Support
 
 - 📧 Email: support@quantaroute.com
 - 🌐 Website: https://quantaroute.com
-- 📖 API Documentation: https://api.quantaroute.com/v1/digipin/docs
+- 📖 Traditional API Docs: https://api.quantaroute.com/v1/digipin/docs
+- 🚀 **NEW: Location Lookup API**: https://api.quantaroute.com/v1/location
+- 📊 **Live Statistics**: https://api.quantaroute.com/v1/location/stats
+
+### 🚀 What Makes This Revolutionary?
+
+**QuantaRoute's Location Lookup API is the first and only service to provide:**
+
+✨ **Government-Level Precision**: Administrative boundary data that even government APIs don't provide at this level of detail and accessibility.
+
+📍 **Complete Coverage**: 36,000+ postal boundaries across India with sub-district precision.
+
+⚡ **Blazing Performance**: Sub-100ms cached responses, guaranteed <500ms database queries.
+
+🎯 **Unique Value Proposition**: The only service providing this level of administrative boundary lookup precision for India.
+
+🔄 **Developer-Friendly**: Simple APIs, comprehensive SDKs, and excellent documentation.
+
+**Ready to revolutionize your location intelligence applications?**
 
 ## License
 

quantaroute_geocoding-1.0.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+quantaroute_geocoding/__init__.py,sha256=MKBlkAnJYv5BCGMAJ9TfpCAElhGY8Ie6lQCFT2A8qx4,766
+quantaroute_geocoding/cli.py,sha256=2vJRef_4dP-4iCs3BWmNDACxMV628X4q2pos4S5UfIY,16835
+quantaroute_geocoding/client.py,sha256=47sirSJMek9dGeybm6-62RoLx1SBfYlJuqDqZfgQcF8,14935
+quantaroute_geocoding/csv_processor.py,sha256=tmbtE1bQzi2TnKgxOGIQ-H6MWirh-cuG4RRErcCdfco,16096
+quantaroute_geocoding/exceptions.py,sha256=rAkj8K5-AUf31kV8UlmNxQ5IN0m4CIL2qnI6ALas5Ys,1173
+quantaroute_geocoding/location_lookup.py,sha256=kMUceiQF6sUG_nmyH9UyXDO07xtyNZyPNsinsuv7TYg,11490
+quantaroute_geocoding/offline.py,sha256=HymAwPNp01oHifQrXZ5Qj8EVn7EwoeqxjczJxbMNuXE,9711
+quantaroute_geocoding-1.0.4.dist-info/licenses/LICENSE,sha256=QY7Uoe-MPRTjfyyDM3HOnqtuSqbzyPLATiriEaQ9u90,1068
+quantaroute_geocoding-1.0.4.dist-info/METADATA,sha256=ehVSo01AtkdHv00pLMsxZ5qr5zXqLXJKd55UDjS0ypk,15504
+quantaroute_geocoding-1.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+quantaroute_geocoding-1.0.4.dist-info/entry_points.txt,sha256=cniijgPLz_Pb6Fiti6aOxaJp1BB_bv60ZOL_oitGCx8,71
+quantaroute_geocoding-1.0.4.dist-info/top_level.txt,sha256=_cyyFLwSH1wYB1HNs_LcZIDQRo1CnvoEsdnKz-cBCr4,22
+quantaroute_geocoding-1.0.4.dist-info/RECORD,,

quantaroute_geocoding-1.0.2.dist-info/RECORD

@@ -1,12 +0,0 @@
-quantaroute_geocoding/__init__.py,sha256=lvtwtmpxPcgW050HFy-n5ReuYN1QsDmadn8sPsjXVQE,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=HymAwPNp01oHifQrXZ5Qj8EVn7EwoeqxjczJxbMNuXE,9711
-quantaroute_geocoding-1.0.2.dist-info/licenses/LICENSE,sha256=QY7Uoe-MPRTjfyyDM3HOnqtuSqbzyPLATiriEaQ9u90,1068
-quantaroute_geocoding-1.0.2.dist-info/METADATA,sha256=lcu-ynNWxk1I6D-ok_Rbv2fyKtlHGhp-1qMdbvNOUMw,9545
-quantaroute_geocoding-1.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-quantaroute_geocoding-1.0.2.dist-info/entry_points.txt,sha256=cniijgPLz_Pb6Fiti6aOxaJp1BB_bv60ZOL_oitGCx8,71
-quantaroute_geocoding-1.0.2.dist-info/top_level.txt,sha256=_cyyFLwSH1wYB1HNs_LcZIDQRo1CnvoEsdnKz-cBCr4,22
-quantaroute_geocoding-1.0.2.dist-info/RECORD,,