quantaroute-geocoding
Advanced tools
India-specific Node.js SDK for QuantaRoute Geocoding API with Location Lookup, Webhooks, and DigiPin processing
A unique Node.js/TypeScript library for geocoding addresses to DigiPin codes or reverse with groundbreaking Location Lookup API and offline processing capabilities. This library is designed for India 🇮🇳!
npm install quantaroute-geocoding
What's included:
import { QuantaRouteClient } from 'quantaroute-geocoding';
// Initialize client
const client = new QuantaRouteClient({
apiKey: 'your-api-key'
});
// 🚀 Unique: Get administrative boundaries from coordinates
const result = await client.lookupLocationFromCoordinates(28.6139, 77.2090);
console.log(`Pincode: ${result.administrative_info.pincode}`); // 110001
console.log(`State: ${result.administrative_info.state}`); // Delhi
console.log(`Division: ${result.administrative_info.division}`); // New Delhi Central
console.log(`Locality: ${result.administrative_info.locality}`); // Nirman Bhawan SO
console.log(`District: ${result.administrative_info.district}`); // New Delhi
console.log(`Delivery: ${result.administrative_info.delivery}`); // Delivery
console.log(`DigiPin: ${result.digipin}`); // 39J-438-TJC7
console.log(`Response Time: ${result.response_time_ms}ms`); // <100ms
// 🚀 Unique: Get boundaries from DigiPin
const digipinResult = await client.lookupLocationFromDigiPin("39J-438-TJC7");
console.log(`Pincode: ${digipinResult.administrative_info.pincode}`);
console.log(`State: ${digipinResult.administrative_info.state}`);
console.log(`Division: ${digipinResult.administrative_info.division}`);
console.log(`Locality: ${digipinResult.administrative_info.locality}`);
console.log(`District: ${digipinResult.administrative_info.district}`);
// 📊 Get live statistics (19,000+ boundaries with 154,000 post offices)
const stats = await client.getLocationStatistics();
console.log(`Total Boundaries: ${stats.totalBoundaries.toLocaleString()}`);
console.log(`Total States: ${stats.totalStates}`);
// Geocode an address
const geocodeResult = await client.geocode("India Gate, New Delhi, India");
console.log(`DigiPin: ${geocodeResult.digipin}`);
console.log(`Coordinates: ${geocodeResult.coordinates}`);
// Convert coordinates to DigiPin
const coordResult = await client.coordinatesToDigiPin(28.6139, 77.2090);
console.log(`DigiPin: ${coordResult.digipin}`);
// Reverse geocode DigiPin - Get Nominatim/OpenStreetMap address with DigiPin (Our USP!)
const reverseResult = await client.reverseGeocode("39J-438-TJC7");
console.log(`DigiPin: ${reverseResult.digipin}`); // Always returned - Our USP!
console.log(`Coordinates: ${reverseResult.coordinates}`);
console.log(`Address: ${reverseResult.address}`);
console.log(`Display Name: ${reverseResult.displayName}`);
console.log(`Street: ${reverseResult.addressComponents.road}`);
console.log(`House Name: ${reverseResult.addressComponents.amenity || reverseResult.addressComponents.name}`);
NEW: Official India Post DigiPin Algorithm Vendored! 🎉
quantaroute-geocoding now includes the official DigiPin algorithm directly - no external dependencies needed!
import { OfflineProcessor } from 'quantaroute-geocoding';
// Initialize offline processor (no dependencies needed!)
const processor = new OfflineProcessor();
// Convert coordinates to DigiPin (offline, 100% accurate)
const offlineResult = processor.coordinatesToDigiPin(28.6139, 77.2090);
console.log(`DigiPin: ${offlineResult.digipin}`); // "39J-438-TJC7"
console.log(`Source: ${offlineResult.source}`); // "offline"
// Convert DigiPin to coordinates (offline)
const coordsResult = processor.digiPinToCoordinates("39J-438-TJC7");
console.log(`Latitude: ${coordsResult.coordinates.latitude}`);
console.log(`Longitude: ${coordsResult.coordinates.longitude}`);
// Validate DigiPin format
const validation = processor.validateDigiPin("39J-438-TJC7");
console.log(`Valid: ${validation.isValid}`);
if (!validation.isValid) {
console.log(`Errors: ${validation.errors.join(', ')}`);
}
// Calculate distance between coordinates
const distance = processor.calculateDistance(28.6139, 77.2090, 28.6150, 77.2100);
console.log(`Distance: ${distance.toFixed(2)} km`);
For simple use cases, you can use the core functions directly:
import {
getDigiPin,
getLatLngFromDigiPin,
isValidDigiPinFormat,
getBounds
} from 'quantaroute-geocoding';
// Convert coordinates to DigiPin
const digipin = getDigiPin(28.6139, 77.2090);
console.log('DigiPin:', digipin); // "39J-438-TJC7"
// Convert DigiPin to coordinates
const coords = getLatLngFromDigiPin("39J-438-TJC7");
console.log('Latitude:', coords.latitude); // "28.613900"
console.log('Longitude:', coords.longitude); // "77.209000"
// Validate DigiPin
const isValid = isValidDigiPinFormat("39J-438-TJC7");
console.log('Valid:', isValid); // true
// Get India bounds covered by DigiPin
const bounds = getBounds();
console.log('Bounds:', bounds);
// { minLat: 2.5, maxLat: 38.5, minLon: 63.5, maxLon: 99.5 }
Why This Matters:
digipin packages// Register a webhook endpoint
const webhook = await client.registerWebhook({
url: 'https://your-app.com/webhooks',
events: [
'location.lookup.completed',
'geocoding.completed',
'rate_limit.exceeded'
],
secret: 'your-webhook-secret' // Optional: for signature verification
});
console.log(`Webhook registered: ${webhook.id}`);
// List all webhooks
const webhooks = await client.listWebhooks();
webhooks.forEach(wh => {
console.log(`${wh.id}: ${wh.url} (${wh.events.length} events)`);
});
// Get a specific webhook
const webhookDetails = await client.getWebhook(webhook.id);
console.log(`Active: ${webhookDetails.isActive}`);
console.log(`Failures: ${webhookDetails.failureCount}`);
// Test webhook delivery
const testResult = await client.testWebhook(webhook.id);
console.log(`Test delivered: ${testResult.delivered}`);
// Delete webhook
await client.deleteWebhook(webhook.id);
location.lookup.completed - Location lookup completed successfullylocation.lookup.failed - Location lookup failedlocation.batch_lookup.completed - Batch location lookup completedlocation.batch_lookup.failed - Batch location lookup failedgeocoding.completed - Geocoding completed successfullygeocoding.failed - Geocoding failedbulk_processing.started - Bulk processing startedbulk_processing.completed - Bulk processing completedbulk_processing.failed - Bulk processing failedrate_limit.exceeded - Rate limit exceededapi_key.usage_warning - API key usage warning (80% threshold)webhook.test - Test webhook eventWebhooks include HMAC-SHA256 signatures for verification:
import crypto from 'crypto';
// Verify webhook signature
function verifyWebhookSignature(
body: string,
signature: string,
secret: string
): boolean {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(body)
.digest('hex');
const receivedSignature = signature.replace('sha256=', '');
return expectedSignature === receivedSignature;
}
{
event: 'location.lookup.completed',
timestamp: '2025-11-10T12:00:00.000Z',
data: {
coordinates: { latitude: 28.6139, longitude: 77.2090 },
digipin: '39J-438-TJC7',
administrative_info: {
country: 'India',
state: 'Delhi',
division: 'New Delhi Central',
locality: 'Nirman Bhawan SO',
pincode: '110001'
}
}
}
import { LocationLookupClient } from 'quantaroute-geocoding';
// Initialize dedicated location client
const locationClient = new LocationLookupClient({
apiKey: 'your-api-key'
});
// Single coordinate lookup
const result = await locationClient.lookupCoordinates(28.6139, 77.2090);
console.log(`📮 Pincode: ${result.administrative_info.pincode}`);
console.log(`🏢 Office: ${result.administrative_info.locality}`);
console.log(`🏛️ Division: ${result.administrative_info.division}`);
console.log(`⚡ Response Time: ${result.response_time_ms}ms`);
// DigiPin to boundaries
const digipinResult = await locationClient.lookupDigiPin("39J-438-TJC7");
console.log(`Administrative boundaries:`, digipinResult.administrative_info);
// Batch processing (up to 100 locations)
const locations = [
{ latitude: 28.6139, longitude: 77.2090 },
{ latitude: 19.0760, longitude: 72.8777 },
{ digipin: "39J-438-TJC7" }
];
const batchResults = await locationClient.batchLookup(locations);
console.log(`Processed ${batchResults.results.length} locations`);
// Live statistics
const stats = await locationClient.getStatistics();
console.log(`🗺️ Total Boundaries: ${stats.totalBoundaries.toLocaleString()}`);
console.log(`⚡ Cache Size: ${stats.cacheSize}`);
// Coverage information
const coverage = await locationClient.getCoverageInfo();
console.log(`Service capabilities:`, coverage);
interface LocationLookupResult {
administrative_info: {
pincode: string; // "110001"
locality: string; // "Nirman Bhawan SO"
division: string; // "New Delhi Central"
state: string; // "Delhi"
country: string; // "India"
delivery?: string; // "Delivery"
district?: string; // "New Delhi"
};
coordinates: {
latitude: number; // 28.6139
longitude: number; // 77.2090
};
digipin: string; // "39J-438-TJC7"
confidence: number; // 0.95
source: 'cache' | 'database';
response_time_ms?: number; // 45
}
🎯 Government-Level Precision: Access to administrative boundaries that even government APIs don't provide at this level of detail and accessibility.
📍 19,000+ Boundaries (with 154,000 post offices): 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.
Set your API key as an environment variable:
export QUANTAROUTE_API_KEY="your-api-key"
const client = new QuantaRouteClient({
apiKey: 'your-key',
baseURL: 'https://api.quantaroute.com', // Custom base URL
timeout: 30000, // Request timeout in milliseconds
maxRetries: 3 // Maximum retry attempts
});
import {
QuantaRouteError,
APIRequestError,
RateLimitError,
AuthenticationError,
ValidationError
} from 'quantaroute-geocoding';
try {
const result = await client.geocode("Invalid address");
} catch (error) {
if (error instanceof RateLimitError) {
console.log(`Rate limit exceeded. Retry after ${error.retryAfter} seconds`);
} else if (error instanceof AuthenticationError) {
console.log("Invalid API key");
} else if (error instanceof ValidationError) {
console.log(`Validation error: ${error.message}`);
} else if (error instanceof APIRequestError) {
console.log(`API error: ${error.message} (Status: ${error.statusCode})`);
}
}
This package works in both Node.js and browser environments. For browser usage:
// Works in React, Vue, Angular, vanilla JS, etc.
import { QuantaRouteClient } from 'quantaroute-geocoding';
const client = new QuantaRouteClient({
apiKey: 'your-api-key'
});
// Use in your frontend application
const handleGeocode = async () => {
try {
const result = await client.lookupLocationFromCoordinates(28.6139, 77.2090);
console.log('Location data:', result);
} catch (error) {
console.error('Geocoding error:', error);
}
};
The QuantaRoute API server is configured to allow cross-origin requests. If you encounter CORS issues:
Note: CORS issues are server-side configuration problems, not client-side package issues.
This package includes full TypeScript definitions:
import {
QuantaRouteClient,
LocationLookupResult,
GeocodeResult,
LocationStatistics,
BatchLocationRequest
} from 'quantaroute-geocoding';
// All types are fully typed
const client: QuantaRouteClient = new QuantaRouteClient({ apiKey: 'key' });
const result: LocationLookupResult = await client.lookupLocationFromCoordinates(28.6139, 77.2090);
| Tier | Requests/Minute | Monthly Limit | Batch Size |
|---|---|---|---|
| Free | 10 | 1,000 | 50 |
| Paid | 100 | 10,000 | 100 |
| Enterprise | 1,000 | Unlimited | 100 |
| Tier | Requests/Minute | Monthly Limit | Batch Size | Boundaries |
|---|---|---|---|---|
| Free | 20 | 25,000 | 50 | 19,000+ (with 154,000 post offices) |
| Paid | 200 | 50,000 | 100 | 19,000+ (with 154,000 post offices) |
| Enterprise | 10,000,000 | Unlimited | 100 | 19,000+ (with 154,000 post offices) |
Performance Guarantees:
Check out the examples/ directory for more comprehensive examples:
basic-usage.js - Basic geocoding operationslocation-lookup.js - Unique Location Lookup APIwebhooks.js - Webhook management and event handlingoffline-processing.js - Offline DigiPin operationsQuantaRoute'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: 19,000+ postal boundaries (with 154,000 post offices) 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 TypeScript support, and excellent documentation.
Ready to revolutionize your location intelligence applications?
address, displayName, and addressComponents fieldsMIT License - see LICENSE file for details.
FAQs
India-specific Node.js SDK for QuantaRoute Geocoding API with Location Lookup, Webhooks, and DigiPin processing
We found that quantaroute-geocoding demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.
Security News
OpenSSF has issued a high-severity advisory warning open source developers of an active Slack-based campaign using impersonation to deliver malware.