# QuantaRoute Geocoding Python SDK
A **revolutionary** Python library for geocoding addresses to DigiPin codes with **groundbreaking Location Lookup API** and offline processing capabilities.
## 🚀 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
- 🚀 **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
```
## Upgrade
```bash
pip install --upgrade quantaroute-geocoding
or
pip install quantaroute-geocoding==<version>
or
pip install --force-reinstall quantaroute-geocoding==1.0.3
or
pip cache purge
pip install --upgrade quantaroute-geocoding
or
pip install --no-cache-dir --upgrade quantaroute-geocoding
```
For offline DigiPin processing, also install the official DigiPin library:
```bash
pip install digipin
```
## Quick Start
### 🚀 **NEW: Revolutionary Location Lookup API**
```python
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['totalBoundaries']:,}")
print(f"Total States: {stats['totalStates']}")
```
### 🌟 **Traditional Geocoding API**
```python
# 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 **revolutionary** CLI with Location Lookup capabilities:
### 🚀 **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
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
```
## 🚀 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
```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
### 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
- 📖 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
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/quantaroute/quantaroute-geocoding-python",
"name": "quantaroute-geocoding",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "geocoding, digipin, gis, location, india, address, coordinates, administrative-boundaries, pincode, postal-lookup, location-intelligence",
"author": "QuantaRoute",
"author_email": "QuantaRoute <support@quantaroute.com>",
"download_url": "https://files.pythonhosted.org/packages/9a/4a/7480b23fb5716a4b7a181b4e6d10adf575c915afd4758ad36e5778baf332/quantaroute_geocoding-1.0.5.tar.gz",
"platform": null,
"description": "# QuantaRoute Geocoding Python SDK\n\nA **revolutionary** Python library for geocoding addresses to DigiPin codes with **groundbreaking Location Lookup API** and offline processing capabilities.\n\n## \ud83d\ude80 Revolutionary Features\n\n### \ud83c\udfaf **NEW: Location Lookup API** - *Service that even government doesn't provide!*\n- \ud83d\uddfa\ufe0f **Administrative Boundary Lookup**: Get state, division, locality, pincode from coordinates\n- \ud83d\udccd **36,000+ Postal Boundaries**: Complete coverage across India\n- \u26a1 **Sub-100ms Response**: Cached responses with database fallback\n- \ud83c\udfaf **Government-Level Precision**: Accuracy that official services don't offer\n- \ud83d\udd04 **Batch Processing**: Up to 100 locations per request\n\n### \ud83c\udf1f **Core Features**\n- \ud83c\udf10 **Online API Integration**: Full access to QuantaRoute Geocoding API\n- \ud83d\udd0c **Offline Processing**: Process coordinates \u2194 DigiPin without internet\n- \ud83d\udcca **CSV Bulk Processing**: Handle large datasets efficiently\n- \ud83d\ude80 **CLI Tools**: Command-line interface for quick operations\n- \ud83d\udcc8 **Progress Tracking**: Real-time progress bars for bulk operations\n- \ud83d\udd04 **Retry Logic**: Automatic retry with exponential backoff\n- \ud83c\udfaf **Rate Limit Handling**: Intelligent rate limit management\n\n## Installation\n\n```bash\npip install quantaroute-geocoding\n```\n\n## Upgrade\n\n```bash\npip install --upgrade quantaroute-geocoding\nor\npip install quantaroute-geocoding==<version>\nor\npip install --force-reinstall quantaroute-geocoding==1.0.3\nor\npip cache purge\npip install --upgrade quantaroute-geocoding\nor\npip install --no-cache-dir --upgrade quantaroute-geocoding\n```\n\nFor offline DigiPin processing, also install the official DigiPin library:\n\n```bash\npip install digipin\n```\n\n## Quick Start\n\n### \ud83d\ude80 **NEW: Revolutionary Location Lookup API**\n\n```python\nfrom quantaroute_geocoding import QuantaRouteClient, LocationLookupClient\n\n# Initialize client\nclient = QuantaRouteClient(api_key=\"your-api-key\")\n\n# \ud83d\ude80 REVOLUTIONARY: Get administrative boundaries from coordinates\nresult = client.lookup_location_from_coordinates(28.6139, 77.2090)\nprint(f\"Pincode: {result['pincode']}\") # 110001\nprint(f\"Office: {result['office_name']}\") # New Delhi GPO\nprint(f\"Division: {result['division']}\") # New Delhi GPO\nprint(f\"Circle: {result['circle']}\") # Delhi\nprint(f\"DigiPin: {result['digipin']}\") # 39J-438-TJC7\nprint(f\"Response Time: {result['response_time_ms']}ms\") # <100ms\n\n# \ud83d\ude80 REVOLUTIONARY: Get boundaries from DigiPin\nresult = client.lookup_location_from_digipin(\"39J-438-TJC7\")\nprint(f\"Pincode: {result['administrative_info']['pincode']}\")\nprint(f\"State: {result['administrative_info']['state']}\")\nprint(f\"Division: {result['administrative_info']['division']}\")\nprint(f\"Locality: {result['administrative_info']['locality']}\")\n\n# \ud83d\udcca Get live statistics (36,000+ boundaries)\nstats = client.get_location_statistics()\nprint(f\"Total Boundaries: {stats['totalBoundaries']:,}\")\nprint(f\"Total States: {stats['totalStates']}\")\n```\n\n### \ud83c\udf1f **Traditional Geocoding API**\n\n```python\n# Geocode an address\nresult = client.geocode(\"India Gate, New Delhi, India\")\nprint(f\"DigiPin: {result['digipin']}\")\nprint(f\"Coordinates: {result['coordinates']}\")\n\n# Convert coordinates to DigiPin\nresult = client.coordinates_to_digipin(28.6139, 77.2090)\nprint(f\"DigiPin: {result['digipin']}\")\n\n# Reverse geocode DigiPin\nresult = client.reverse_geocode(\"39J-438-TJC7\")\nprint(f\"Coordinates: {result['coordinates']}\")\n```\n\n### Offline Processing\n\n```python\nfrom quantaroute_geocoding import OfflineProcessor\n\n# Initialize offline processor\nprocessor = OfflineProcessor()\n\n# Convert coordinates to DigiPin (offline)\nresult = processor.coordinates_to_digipin(28.6139, 77.2090)\nprint(f\"DigiPin: {result['digipin']}\")\n\n# Convert DigiPin to coordinates (offline)\nresult = processor.digipin_to_coordinates(\"39J-438-TJC7\")\nprint(f\"Coordinates: {result['coordinates']}\")\n\n# Validate DigiPin format\nresult = processor.validate_digipin(\"39J-438-TJC7\")\nprint(f\"Valid: {result['isValid']}\")\n```\n\n### CSV Bulk Processing\n\n```python\nfrom quantaroute_geocoding import CSVProcessor\n\n# Initialize processor\nprocessor = CSVProcessor(api_key=\"your-api-key\")\n\n# Process addresses to DigiPin\nresult = processor.process_geocoding_csv(\n input_file=\"addresses.csv\",\n output_file=\"results.csv\",\n address_column=\"address\"\n)\n\nprint(f\"Processed {result['total_rows']} rows\")\nprint(f\"Success rate: {result['success_rate']:.1%}\")\n\n# Process coordinates to DigiPin (can use offline mode)\nprocessor_offline = CSVProcessor(use_offline=True)\nresult = processor_offline.process_coordinates_to_digipin_csv(\n input_file=\"coordinates.csv\",\n output_file=\"digipins.csv\"\n)\n```\n\n## Command Line Interface\n\nThe package includes a **revolutionary** CLI with Location Lookup capabilities:\n\n### \ud83d\ude80 **NEW: Revolutionary Location Lookup Commands**\n\n```bash\n# Get administrative boundaries from coordinates\nquantaroute-geocode location-lookup 28.6139 77.2090 --api-key your-key\n\n# Get boundaries from DigiPin\nquantaroute-geocode location-from-digipin \"39J-438-TJC7\" --api-key your-key\n\n# Get live statistics (36,000+ boundaries)\nquantaroute-geocode location-stats --api-key your-key\n\n# Batch location lookup from CSV (coming soon)\nquantaroute-geocode location-lookup-csv coordinates.csv boundaries.csv --api-key your-key\n```\n\n### \ud83c\udf1f **Traditional Geocoding Commands**\n\n```bash\n# Using API\nquantaroute-geocode geocode addresses.csv results.csv --api-key your-key\n\n# With custom columns\nquantaroute-geocode geocode data.csv output.csv \\\n --address-column street_address \\\n --city-column city_name \\\n --state-column state_name\n```\n\n### Convert coordinates to DigiPin\n\n```bash\n# Online processing\nquantaroute-geocode coords-to-digipin coordinates.csv digipins.csv --api-key your-key\n\n# Offline processing (no API key needed)\nquantaroute-geocode coords-to-digipin coordinates.csv digipins.csv --offline\n```\n\n### Convert DigiPin to coordinates\n\n```bash\n# Online processing\nquantaroute-geocode digipin-to-coords digipins.csv coordinates.csv --api-key your-key\n\n# Offline processing\nquantaroute-geocode digipin-to-coords digipins.csv coordinates.csv --offline\n```\n\n### Single operations\n\n```bash\n# Convert single coordinate to DigiPin\nquantaroute-geocode single-coord-to-digipin 28.6139 77.2090 --offline\n\n# Convert single DigiPin to coordinates\nquantaroute-geocode single-digipin-to-coords \"39J-438-TJC7\" --offline\n\n# Check API usage\nquantaroute-geocode usage --api-key your-key\n```\n\n## CSV File Formats\n\n### Input CSV for Address Geocoding\n\n```csv\naddress,city,state,pincode,country\n\"123 Main Street\",\"New Delhi\",\"Delhi\",\"110001\",\"India\"\n\"456 Park Avenue\",\"Mumbai\",\"Maharashtra\",\"400001\",\"India\"\n```\n\n### Input CSV for Coordinates to DigiPin\n\n```csv\nlatitude,longitude\n28.6139,77.2090\n19.0760,72.8777\n```\n\n### Input CSV for DigiPin to Coordinates\n\n```csv\ndigipin\n39J-438-TJC7\n39J-49J-4867\n```\n\n## \ud83d\ude80 Revolutionary Location Lookup API\n\n### Dedicated Location Lookup Client\n\n```python\nfrom quantaroute_geocoding import LocationLookupClient\n\n# Initialize dedicated location client\nlocation_client = LocationLookupClient(api_key=\"your-api-key\")\n\n# Single coordinate lookup\nresult = location_client.lookup_coordinates(28.6139, 77.2090)\nprint(f\"\ud83d\udcee Pincode: {result['pincode']}\")\nprint(f\"\ud83c\udfe2 Office: {result['office_name']}\")\nprint(f\"\ud83c\udfdb\ufe0f Division: {result['division']}\")\nprint(f\"\u26a1 Response Time: {result['response_time_ms']}ms\")\n\n# DigiPin to boundaries\nresult = location_client.lookup_digipin(\"39J-438-TJC7\")\nprint(f\"Administrative boundaries: {result}\")\n\n# Batch processing (up to 100 locations)\nlocations = [\n {\"latitude\": 28.6139, \"longitude\": 77.2090},\n {\"latitude\": 19.0760, \"longitude\": 72.8777},\n {\"digipin\": \"39J-438-TJC7\"}\n]\nresults = location_client.batch_lookup(locations)\nprint(f\"Processed {len(results['results'])} locations\")\n\n# Live statistics\nstats = location_client.get_statistics()\nprint(f\"\ud83d\uddfa\ufe0f Total Boundaries: {stats['total_boundaries']:,}\")\nprint(f\"\u26a1 Cache Size: {stats['cache_size']}\")\n\n# Coverage information\ncoverage = location_client.get_coverage_info()\nprint(f\"Service capabilities: {coverage}\")\n```\n\n### Location Lookup Output Format\n\n```json\n{\n \"pincode\": \"110001\",\n \"office_name\": \"New Delhi GPO\",\n \"division\": \"New Delhi GPO\",\n \"region\": \"\",\n \"circle\": \"Delhi\",\n \"coordinates\": {\n \"latitude\": 28.6139,\n \"longitude\": 77.2090\n },\n \"digipin\": \"39J-438-TJC7\",\n \"cached\": true,\n \"response_time_ms\": 45\n}\n```\n\n### Why This is Revolutionary\n\n\ud83c\udfaf **Government-Level Precision**: Access to administrative boundaries that even government APIs don't provide at this level of detail and accessibility.\n\n\ud83d\udccd **36,000+ Boundaries**: Complete coverage of Indian postal boundaries with sub-district level precision.\n\n\u26a1 **Performance**: Sub-100ms cached responses, <500ms database queries.\n\n\ud83d\udd04 **Batch Processing**: Process up to 100 locations in a single API call.\n\n\u2728 **Unique Value**: The only service providing this level of administrative boundary lookup precision for India.\n\n## Advanced Features\n\n### Webhook Management\n\n```python\n# Register webhook\nwebhook = client.register_webhook(\n url=\"https://your-app.com/webhook\",\n events=[\"bulk_processing.completed\", \"geocoding.completed\"]\n)\n\n# List webhooks\nwebhooks = client.list_webhooks()\n\n# Delete webhook\nclient.delete_webhook(webhook['id'])\n```\n\n### Batch Processing with Progress Callback\n\n```python\ndef progress_callback(processed, total, success, errors):\n print(f\"Progress: {processed}/{total} - Success: {success}, Errors: {errors}\")\n\nprocessor = CSVProcessor(api_key=\"your-key\")\nresult = processor.process_geocoding_csv(\n input_file=\"large_dataset.csv\",\n output_file=\"results.csv\",\n progress_callback=progress_callback\n)\n```\n\n### Offline Grid Operations\n\n```python\nprocessor = OfflineProcessor()\n\n# Get grid information\ngrid_info = processor.get_grid_info(\"39J-438-TJC7\")\nprint(f\"Grid center: {grid_info['center']}\")\nprint(f\"Grid bounds: {grid_info['bounds']}\")\n\n# Find nearby grids\nnearby = processor.find_nearby_grids(28.6139, 77.2090, radius_meters=100)\nfor grid in nearby:\n print(f\"DigiPin: {grid['digipin']}, Distance: {grid['distance_meters']}m\")\n\n# Calculate distance between coordinates\ndistance = processor.calculate_distance(28.6139, 77.2090, 28.6150, 77.2100)\nprint(f\"Distance: {distance:.2f} km\")\n```\n\n## Configuration\n\n### Environment Variables\n\nSet your API key as an environment variable:\n\n```bash\nexport QUANTAROUTE_API_KEY=\"your-api-key\"\n```\n\n### API Configuration\n\n```python\nclient = QuantaRouteClient(\n api_key=\"your-key\",\n base_url=\"https://api.quantaroute.com\", # Custom base URL\n timeout=30, # Request timeout in seconds\n max_retries=3 # Maximum retry attempts\n)\n```\n\n### CSV Processor Configuration\n\n```python\nprocessor = CSVProcessor(\n api_key=\"your-key\",\n use_offline=False, # Use offline processing when possible\n batch_size=50, # Records per API batch\n delay_between_batches=1.0 # Delay in seconds between batches\n)\n```\n\n## Error Handling\n\n```python\nfrom quantaroute_geocoding import (\n QuantaRouteError,\n APIError,\n RateLimitError,\n AuthenticationError,\n ValidationError\n)\n\ntry:\n result = client.geocode(\"Invalid address\")\nexcept RateLimitError as e:\n print(f\"Rate limit exceeded. Retry after {e.retry_after} seconds\")\nexcept AuthenticationError:\n print(\"Invalid API key\")\nexcept ValidationError as e:\n print(f\"Validation error: {e}\")\nexcept APIError as e:\n print(f\"API error: {e} (Status: {e.status_code})\")\n```\n\n## Performance Tips\n\n1. **Use Batch Processing**: Process multiple addresses in batches for better performance\n2. **Offline Mode**: Use offline processing for coordinate \u2194 DigiPin conversions\n3. **Caching**: The API includes intelligent caching - repeated requests are faster\n4. **Rate Limits**: The SDK handles rate limits automatically with retry logic\n5. **CSV Processing**: Use the CSV processor for large datasets instead of individual API calls\n\n## API Limits\n\n### Traditional Geocoding API\n\n| Tier | Requests/Minute | Monthly Limit | Batch Size |\n|------|----------------|---------------|------------|\n| Free | 10 | 1,000 | 50 |\n| Paid | 100 | 10,000 | 100 |\n| Enterprise | 1,000 | Unlimited | 100 |\n\n### \ud83d\ude80 Revolutionary Location Lookup API\n\n| Tier | Requests/Minute | Monthly Limit | Batch Size | Boundaries |\n|------|----------------|---------------|------------|------------|\n| Free | 20 | 2,000 | 50 | 36,000+ |\n| Paid | 200 | 20,000 | 100 | 36,000+ |\n| Enterprise | 2,000 | Unlimited | 100 | 36,000+ |\n\n**Performance Guarantees:**\n- \u26a1 Cached responses: <100ms\n- \ud83d\udd0d Database queries: <500ms\n- \ud83d\udcca Batch processing: <50ms per location\n- \ud83c\udfaf 99.9% uptime SLA (Enterprise)\n\n## Support\n\n- \ud83d\udce7 Email: support@quantaroute.com\n- \ud83c\udf10 Website: https://quantaroute.com\n- \ud83d\udcd6 Traditional API Docs: https://api.quantaroute.com/v1/digipin/docs\n- \ud83d\ude80 **NEW: Location Lookup API**: https://api.quantaroute.com/v1/location\n- \ud83d\udcca **Live Statistics**: https://api.quantaroute.com/v1/location/stats\n\n### \ud83d\ude80 What Makes This Revolutionary?\n\n**QuantaRoute's Location Lookup API is the first and only service to provide:**\n\n\u2728 **Government-Level Precision**: Administrative boundary data that even government APIs don't provide at this level of detail and accessibility.\n\n\ud83d\udccd **Complete Coverage**: 36,000+ postal boundaries across India with sub-district precision.\n\n\u26a1 **Blazing Performance**: Sub-100ms cached responses, guaranteed <500ms database queries.\n\n\ud83c\udfaf **Unique Value Proposition**: The only service providing this level of administrative boundary lookup precision for India.\n\n\ud83d\udd04 **Developer-Friendly**: Simple APIs, comprehensive SDKs, and excellent documentation.\n\n**Ready to revolutionize your location intelligence applications?**\n\n## License\n\nMIT License - see LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Revolutionary Python SDK for QuantaRoute Geocoding API with Location Lookup and offline DigiPin processing",
"version": "1.0.5",
"project_urls": {
"Bug Tracker": "https://github.com/quantaroute/quantaroute-geocoding-python/issues",
"Documentation": "https://api.quantaroute.com/v1/digipin/docs",
"Homepage": "https://quantaroute.com",
"Repository": "https://github.com/quantaroute/quantaroute-geocoding-python"
},
"split_keywords": [
"geocoding",
" digipin",
" gis",
" location",
" india",
" address",
" coordinates",
" administrative-boundaries",
" pincode",
" postal-lookup",
" location-intelligence"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f4676c7c7c501063b4bfaadba45c374a66c8950ce2a033dcc5a2464de97b05ed",
"md5": "9fdb4c7df6401ae175bdee5f42afb185",
"sha256": "d863473330cbca43d87ee5a7b98bde1e116d47acfcd27266e2f116f86a276ab8"
},
"downloads": -1,
"filename": "quantaroute_geocoding-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9fdb4c7df6401ae175bdee5f42afb185",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 23297,
"upload_time": "2025-10-30T20:28:11",
"upload_time_iso_8601": "2025-10-30T20:28:11.226226Z",
"url": "https://files.pythonhosted.org/packages/f4/67/6c7c7c501063b4bfaadba45c374a66c8950ce2a033dcc5a2464de97b05ed/quantaroute_geocoding-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9a4a7480b23fb5716a4b7a181b4e6d10adf575c915afd4758ad36e5778baf332",
"md5": "b6ba2b7b301f2dd2154f7bcfd1b9f5c9",
"sha256": "4c6d9dead88a4dd2e0b7de8b668aad754ddb9211398141023de489dffc13a279"
},
"downloads": -1,
"filename": "quantaroute_geocoding-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "b6ba2b7b301f2dd2154f7bcfd1b9f5c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 29136,
"upload_time": "2025-10-30T20:28:12",
"upload_time_iso_8601": "2025-10-30T20:28:12.712946Z",
"url": "https://files.pythonhosted.org/packages/9a/4a/7480b23fb5716a4b7a181b4e6d10adf575c915afd4758ad36e5778baf332/quantaroute_geocoding-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 20:28:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quantaroute",
"github_project": "quantaroute-geocoding-python",
"github_not_found": true,
"lcname": "quantaroute-geocoding"
}
JSON
