quantaroute-geocoding 1.0.0

Python SDK for QuantaRoute Geocoding API with offline DigiPin processing

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

pip install quantaroute-geocoding

For offline DigiPin processing, also install the official DigiPin library:

pip install digipin

Quick Start

Online API Usage

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

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

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

# 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

# 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

# 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

# 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

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

latitude,longitude
28.6139,77.2090
19.0760,72.8777

Input CSV for DigiPin to Coordinates

digipin
39J-438-TJC7
39J-49J-4867

Advanced Features

Webhook Management

# 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

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

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:

export QUANTAROUTE_API_KEY="your-api-key"

API Configuration

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

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

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: [e-mail]
• 🌐 Website: https://quantaroute.com
• 📖 API Documentation: https://api.quantaroute.com/v1/digipin/docs

License

MIT License - see LICENSE file for details.