quantaroute-geocoding 1.0.0__py3-none-any.whl

quantaroute_geocoding/__init__.py

@@ -0,0 +1,32 @@
+"""
+QuantaRoute Geocoding Python SDK
+
+A Python library for geocoding addresses to DigiPin codes with both online API
+and offline processing capabilities.
+"""
+
+__version__ = "1.0.0"
+__author__ = "QuantaRoute"
+__email__ = "support@quantaroute.com"
+
+from .client import QuantaRouteClient
+from .offline import OfflineProcessor
+from .csv_processor import CSVProcessor
+from .exceptions import (
+    QuantaRouteError,
+    APIError,
+    RateLimitError,
+    AuthenticationError,
+    ValidationError
+)
+
+__all__ = [
+    "QuantaRouteClient",
+    "OfflineProcessor", 
+    "CSVProcessor",
+    "QuantaRouteError",
+    "APIError",
+    "RateLimitError",
+    "AuthenticationError",
+    "ValidationError"
+]

quantaroute_geocoding/cli.py

@@ -0,0 +1,281 @@
+"""
+Command-line interface for QuantaRoute Geocoding
+"""
+
+import click
+import os
+from typing import Optional
+
+from .csv_processor import CSVProcessor
+from .client import QuantaRouteClient
+from .offline import OfflineProcessor
+from .exceptions import QuantaRouteError
+
+
+@click.group()
+@click.version_option(version="1.0.0")
+def main():
+    """QuantaRoute Geocoding CLI - Process addresses and coordinates with DigiPin"""
+    pass
+
+
+@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', help='QuantaRoute API key')
+@click.option('--address-column', default='address', help='Name of address column')
+@click.option('--city-column', help='Name of city column')
+@click.option('--state-column', help='Name of state column')
+@click.option('--pincode-column', help='Name of pincode column')
+@click.option('--country-column', help='Name of country column')
+@click.option('--batch-size', default=50, help='Batch size for API requests')
+@click.option('--delay', default=1.0, help='Delay between batches (seconds)')
+@click.option('--offline', is_flag=True, help='Use offline processing (limited functionality)')
+def geocode(
+    input_file: str,
+    output_file: str,
+    api_key: Optional[str],
+    address_column: str,
+    city_column: Optional[str],
+    state_column: Optional[str],
+    pincode_column: Optional[str],
+    country_column: Optional[str],
+    batch_size: int,
+    delay: float,
+    offline: bool
+):
+    """Geocode addresses from CSV file to DigiPin codes"""
+    
+    if not offline and not api_key:
+        click.echo("Error: API key is required for online geocoding. Set QUANTAROUTE_API_KEY environment variable or use --api-key option.")
+        return
+    
+    try:
+        processor = CSVProcessor(
+            api_key=api_key,
+            use_offline=offline,
+            batch_size=batch_size,
+            delay_between_batches=delay
+        )
+        
+        def progress_callback(processed, total, success, errors):
+            click.echo(f"Progress: {processed}/{total} ({processed/total*100:.1f}%) - Success: {success}, Errors: {errors}")
+        
+        click.echo(f"Processing {input_file}...")
+        
+        result = processor.process_geocoding_csv(
+            input_file=input_file,
+            output_file=output_file,
+            address_column=address_column,
+            city_column=city_column,
+            state_column=state_column,
+            pincode_column=pincode_column,
+            country_column=country_column,
+            progress_callback=progress_callback
+        )
+        
+        click.echo(f"\nProcessing complete!")
+        click.echo(f"Total rows: {result['total_rows']}")
+        click.echo(f"Successful: {result['success_count']}")
+        click.echo(f"Errors: {result['error_count']}")
+        click.echo(f"Success rate: {result['success_rate']:.1%}")
+        click.echo(f"Output saved to: {result['output_file']}")
+        
+    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', 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('--offline', is_flag=True, help='Use offline processing')
+def coords_to_digipin(
+    input_file: str,
+    output_file: str,
+    api_key: Optional[str],
+    latitude_column: str,
+    longitude_column: str,
+    offline: bool
+):
+    """Convert coordinates to DigiPin codes from CSV file"""
+    
+    if not offline and not api_key:
+        click.echo("Error: API key is required for online processing. Set QUANTAROUTE_API_KEY environment variable or use --api-key option.")
+        return
+    
+    try:
+        processor = CSVProcessor(
+            api_key=api_key,
+            use_offline=offline
+        )
+        
+        def progress_callback(processed, total, success, errors):
+            click.echo(f"Progress: {processed}/{total} ({processed/total*100:.1f}%) - Success: {success}, Errors: {errors}")
+        
+        click.echo(f"Processing {input_file}...")
+        
+        result = processor.process_coordinates_to_digipin_csv(
+            input_file=input_file,
+            output_file=output_file,
+            latitude_column=latitude_column,
+            longitude_column=longitude_column,
+            progress_callback=progress_callback
+        )
+        
+        click.echo(f"\nProcessing complete!")
+        click.echo(f"Total rows: {result['total_rows']}")
+        click.echo(f"Successful: {result['success_count']}")
+        click.echo(f"Errors: {result['error_count']}")
+        click.echo(f"Success rate: {result['success_rate']:.1%}")
+        click.echo(f"Output saved to: {result['output_file']}")
+        
+    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', help='QuantaRoute API key')
+@click.option('--digipin-column', default='digipin', help='Name of DigiPin column')
+@click.option('--offline', is_flag=True, help='Use offline processing')
+def digipin_to_coords(
+    input_file: str,
+    output_file: str,
+    api_key: Optional[str],
+    digipin_column: str,
+    offline: bool
+):
+    """Convert DigiPin codes to coordinates from CSV file"""
+    
+    if not offline and not api_key:
+        click.echo("Error: API key is required for online processing. Set QUANTAROUTE_API_KEY environment variable or use --api-key option.")
+        return
+    
+    try:
+        processor = CSVProcessor(
+            api_key=api_key,
+            use_offline=offline
+        )
+        
+        def progress_callback(processed, total, success, errors):
+            click.echo(f"Progress: {processed}/{total} ({processed/total*100:.1f}%) - Success: {success}, Errors: {errors}")
+        
+        click.echo(f"Processing {input_file}...")
+        
+        result = processor.process_digipin_to_coordinates_csv(
+            input_file=input_file,
+            output_file=output_file,
+            digipin_column=digipin_column,
+            progress_callback=progress_callback
+        )
+        
+        click.echo(f"\nProcessing complete!")
+        click.echo(f"Total rows: {result['total_rows']}")
+        click.echo(f"Successful: {result['success_count']}")
+        click.echo(f"Errors: {result['error_count']}")
+        click.echo(f"Success rate: {result['success_rate']:.1%}")
+        click.echo(f"Output saved to: {result['output_file']}")
+        
+    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 usage():
+    """Check API usage statistics"""
+    
+    try:
+        client = QuantaRouteClient(api_key)
+        usage_data = client.get_usage()
+        
+        click.echo("API Usage Statistics:")
+        click.echo("-" * 30)
+        
+        usage_info = usage_data.get('usage', {})
+        click.echo(f"Current Usage: {usage_info.get('currentUsage', 0)}")
+        click.echo(f"Monthly Limit: {usage_info.get('monthlyLimit', 'Unknown')}")
+        click.echo(f"Tier: {usage_info.get('tier', 'Unknown')}")
+        click.echo(f"Reset Date: {usage_info.get('resetDate', 'Unknown')}")
+        
+        rate_limit = usage_data.get('rateLimit', {})
+        click.echo(f"\nRate Limit:")
+        click.echo(f"Requests per minute: {rate_limit.get('limit', 'Unknown')}")
+        click.echo(f"Remaining: {rate_limit.get('remaining', 'Unknown')}")
+        
+    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('latitude', type=float)
+@click.argument('longitude', type=float)
+@click.option('--api-key', envvar='QUANTAROUTE_API_KEY', help='QuantaRoute API key')
+@click.option('--offline', is_flag=True, help='Use offline processing')
+def single_coord_to_digipin(latitude: float, longitude: float, api_key: Optional[str], offline: bool):
+    """Convert single coordinate pair to DigiPin"""
+    
+    try:
+        if offline:
+            processor = OfflineProcessor()
+            result = processor.coordinates_to_digipin(latitude, longitude)
+        else:
+            if not api_key:
+                click.echo("Error: API key is required for online processing.")
+                return
+            
+            client = QuantaRouteClient(api_key)
+            result = client.coordinates_to_digipin(latitude, longitude)
+        
+        click.echo(f"Coordinates: {latitude}, {longitude}")
+        click.echo(f"DigiPin: {result['digipin']}")
+        
+    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', help='QuantaRoute API key')
+@click.option('--offline', is_flag=True, help='Use offline processing')
+def single_digipin_to_coords(digipin_code: str, api_key: Optional[str], offline: bool):
+    """Convert single DigiPin to coordinates"""
+    
+    try:
+        if offline:
+            processor = OfflineProcessor()
+            result = processor.digipin_to_coordinates(digipin_code)
+        else:
+            if not api_key:
+                click.echo("Error: API key is required for online processing.")
+                return
+            
+            client = QuantaRouteClient(api_key)
+            result = client.reverse_geocode(digipin_code)
+        
+        coords = result['coordinates']
+        click.echo(f"DigiPin: {digipin_code}")
+        click.echo(f"Coordinates: {coords['latitude']}, {coords['longitude']}")
+        
+    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)
+
+
+if __name__ == '__main__':
+    main()

quantaroute_geocoding/client.py

@@ -0,0 +1,312 @@
+"""
+QuantaRoute Geocoding API Client
+"""
+
+import requests
+import time
+from typing import Dict, List, Optional, Union
+from .exceptions import APIError, RateLimitError, AuthenticationError, ValidationError
+
+
+class QuantaRouteClient:
+    """
+    Client for QuantaRoute Geocoding API
+    
+    Provides methods to interact with the QuantaRoute Geocoding API for
+    address geocoding, reverse geocoding, and DigiPin operations.
+    """
+    
+    def __init__(
+        self, 
+        api_key: str, 
+        base_url: str = "https://api.quantaroute.com",
+        timeout: int = 30,
+        max_retries: int = 3
+    ):
+        """
+        Initialize the QuantaRoute 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/1.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 geocode(
+        self, 
+        address: str, 
+        city: Optional[str] = None,
+        state: Optional[str] = None,
+        pincode: Optional[str] = None,
+        country: Optional[str] = None
+    ) -> Dict:
+        """
+        Geocode an address to get DigiPin and coordinates
+        
+        Args:
+            address: The address to geocode
+            city: City name (optional)
+            state: State name (optional)
+            pincode: Postal code (optional)
+            country: Country name (optional, defaults to India)
+            
+        Returns:
+            Dict containing DigiPin, coordinates, and address information
+        """
+        if not address or not address.strip():
+            raise ValidationError("Address is required")
+        
+        data = {
+            'address': address.strip(),
+            'city': city,
+            'state': state,
+            'pincode': pincode,
+            'country': country or 'India'
+        }
+        
+        # Remove None values
+        data = {k: v for k, v in data.items() if v is not None}
+        
+        response = self._make_request('POST', '/v1/digipin/geocode', data)
+        return response.get('data', {})
+    
+    def reverse_geocode(self, digipin: str) -> Dict:
+        """
+        Reverse geocode a DigiPin to get coordinates and address
+        
+        Args:
+            digipin: The DigiPin code to reverse geocode
+            
+        Returns:
+            Dict containing coordinates and address information
+        """
+        if not digipin or not digipin.strip():
+            raise ValidationError("DigiPin is required")
+        
+        data = {'digipin': digipin.strip()}
+        response = self._make_request('POST', '/v1/digipin/reverse', data)
+        return response.get('data', {})
+    
+    def coordinates_to_digipin(self, latitude: float, longitude: float) -> Dict:
+        """
+        Convert coordinates to DigiPin
+        
+        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")
+        
+        data = {
+            'latitude': float(latitude),
+            'longitude': float(longitude)
+        }
+        
+        response = self._make_request('POST', '/v1/digipin/coordinates-to-digipin', data)
+        return response.get('data', {})
+    
+    def validate_digipin(self, digipin: str) -> Dict:
+        """
+        Validate a DigiPin format and check if it's a real location
+        
+        Args:
+            digipin: The DigiPin code to validate
+            
+        Returns:
+            Dict containing validation results
+        """
+        if not digipin or not digipin.strip():
+            raise ValidationError("DigiPin is required")
+        
+        response = self._make_request('GET', f'/v1/digipin/validate/{digipin.strip()}')
+        return response.get('data', {})
+    
+    def batch_geocode(self, addresses: List[Dict]) -> Dict:
+        """
+        Geocode multiple addresses in batch
+        
+        Args:
+            addresses: List of address dictionaries
+            
+        Returns:
+            Dict containing batch processing results
+        """
+        if not addresses or not isinstance(addresses, list):
+            raise ValidationError("Addresses must be a non-empty list")
+        
+        if len(addresses) > 100:
+            raise ValidationError("Maximum 100 addresses allowed per batch")
+        
+        # Validate each address
+        for i, addr in enumerate(addresses):
+            if not isinstance(addr, dict) or 'address' not in addr:
+                raise ValidationError(f"Address {i+1} must be a dict with 'address' key")
+        
+        data = {'addresses': addresses}
+        response = self._make_request('POST', '/v1/digipin/batch', data)
+        return response.get('data', {})
+    
+    def get_usage(self) -> Dict:
+        """
+        Get API usage statistics
+        
+        Returns:
+            Dict containing usage information
+        """
+        response = self._make_request('GET', '/v1/digipin/usage')
+        return response.get('data', {})
+    
+    def autocomplete(self, query: str, limit: int = 5) -> List[Dict]:
+        """
+        Get autocomplete suggestions for addresses
+        
+        Args:
+            query: Search query (minimum 3 characters)
+            limit: Maximum number of suggestions (default: 5, max: 10)
+            
+        Returns:
+            List of address suggestions
+        """
+        if not query or len(query.strip()) < 3:
+            raise ValidationError("Query must be at least 3 characters long")
+        
+        if limit > 10:
+            limit = 10
+        
+        params = {
+            'q': query.strip(),
+            'limit': limit
+        }
+        
+        response = self._make_request('GET', '/v1/digipin/autocomplete', params=params)
+        return response.get('data', [])
+    
+    def register_webhook(self, url: str, events: List[str], secret: Optional[str] = None) -> Dict:
+        """
+        Register a webhook endpoint
+        
+        Args:
+            url: Webhook URL
+            events: List of events to subscribe to
+            secret: Optional secret for signature verification
+            
+        Returns:
+            Dict containing webhook registration details
+        """
+        if not url or not url.startswith(('http://', 'https://')):
+            raise ValidationError("Valid webhook URL is required")
+        
+        if not events or not isinstance(events, list):
+            raise ValidationError("Events list is required")
+        
+        data = {
+            'url': url,
+            'events': events
+        }
+        
+        if secret:
+            data['secret'] = secret
+        
+        response = self._make_request('POST', '/v1/digipin/webhooks', data)
+        return response.get('data', {})
+    
+    def list_webhooks(self) -> List[Dict]:
+        """
+        List registered webhooks
+        
+        Returns:
+            List of webhook configurations
+        """
+        response = self._make_request('GET', '/v1/digipin/webhooks')
+        return response.get('data', [])
+    
+    def delete_webhook(self, webhook_id: str) -> Dict:
+        """
+        Delete a webhook
+        
+        Args:
+            webhook_id: ID of the webhook to delete
+            
+        Returns:
+            Dict containing deletion confirmation
+        """
+        if not webhook_id:
+            raise ValidationError("Webhook ID is required")
+        
+        response = self._make_request('DELETE', f'/v1/digipin/webhooks/{webhook_id}')
+        return response