Metadata-Version: 2.4
Name: quantaroute-geocoding
Version: 1.0.1
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.
