quantaroute-geocoding 1.0.0__tar.gz

quantaroute_geocoding-1.0.0/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/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+recursive-include quantaroute_geocoding *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

quantaroute_geocoding-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,305 @@
+# 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.