Hex Address - JavaScript/TypeScript Package

Convert GPS coordinates to memorable hex addresses like dinenunukiwufeme with ~0.5 meter precision using H3 spatial indexing.

🚀 Quick Start

npm install @alvarosilva/hex-address

JavaScript (ES6+)

import { coordinateToAddress, addressToCoordinate, isValidAddress } from '@alvarosilva/hex-address';

// Convert coordinates to hex address
const address = coordinateToAddress(48.8566, 2.3522);
console.log(address); // "dinenunukiwufeme"

// Convert back to coordinates
const [lat, lon] = addressToCoordinate(address);
console.log(`${lat.toFixed(6)}, ${lon.toFixed(6)}`); // 48.856602, 2.352198

// Validate addresses
const isValid = isValidAddress(address);
console.log(isValid); // true

TypeScript

import { 
  H3SyllableSystem, 
  coordinateToAddress,
  isValidAddress,
  ValidationResult
} from '@alvarosilva/hex-address';

// Type-safe coordinate conversion
const coords: [number, number] = [48.8566, 2.3522];
const address: string = coordinateToAddress(...coords);

// Advanced validation with error details
const validation: ValidationResult = isValidAddress(address, 'ascii-elomr', true);
if (!validation.isValid) {
  validation.errors.forEach(error => {
    console.log(`Error: ${error.message}`);
    if (error.suggestions) {
      console.log(`Suggestions: ${error.suggestions.join(', ')}`);
    }
  });
}

CommonJS

const { coordinateToAddress, addressToCoordinate } = require('@alvarosilva/hex-address');

const address = coordinateToAddress(48.8566, 2.3522);
console.log(address); // "dinenunukiwufeme"

📋 Features

Core Features

• Sub-meter precision (~0.5m) using H3 Level 15
• Memorable addresses using pronounceable syllables
• Perfect reversibility for all real coordinates
• TypeScript support with full type definitions
• Comprehensive validation with intelligent error messages
• Phonetic suggestions for misheard/misspelled addresses

Geographic Analysis (New in v1.3.0!)

• Distance calculation between addresses
• Nearby address search within radius
• Address clustering for route optimization
• Geographic bounds calculation
• Spatial utilities for location-based applications

Technical Features

• Pure ASCII letters for universal compatibility
• Multiple configurations optimized for different languages
• Dual package (ESM and CommonJS)
• Browser compatible with polyfills
• Comprehensive error handling

🎯 New Utility Functions (v1.3.0)

Distance & Location Analysis

import { 
  calculateDistance, 
  findNearbyAddresses, 
  getAddressBounds,
  clusterAddresses 
} from '@alvarosilva/hex-address';

// Calculate distance between two addresses
const distance = calculateDistance("addr1", "addr2");
console.log(`Distance: ${distance.toFixed(2)} km`);

// Find addresses within radius
const nearby = findNearbyAddresses("centerAddress", 1.0); // 1km radius
console.log(`Found ${nearby.length} nearby addresses`);

// Get geographic bounds for an address
const bounds = getAddressBounds("address");
console.log(`Bounds: ${bounds.north}, ${bounds.south}, ${bounds.east}, ${bounds.west}`);

// Cluster addresses for route optimization
const clusters = clusterAddresses(["addr1", "addr2", "addr3"], 0.5); // 500m max distance
console.log(`Organized into ${clusters.length} clusters`);

Enhanced Validation (v1.3.0)

// Simple validation
const isValid = isValidAddress("dinenunukiwufeme"); // returns boolean

// Detailed validation with phonetic suggestions
const result = isValidAddress("helloworld", "ascii-elomr", true);
if (!result.isValid) {
  result.errors.forEach(error => {
    console.log(`[${error.type}] ${error.message}`);
    if (error.suggestions) {
      console.log(`Try: ${error.suggestions.slice(0, 3).join(', ')}`);
    }
  });
}

🌍 Use Cases

• Emergency Services: Share precise locations with phonetic alternatives for radio communication
• Delivery & Logistics: Route optimization with address clustering
• Real Estate: Property analysis with nearby location search
• Gaming: Location-based mechanics with memorable addresses
• Navigation: User-friendly waypoint system
• International: Cross-language compatibility with ASCII addresses

🛠️ API Reference

Coordinate Conversion

// Convert coordinates to address
coordinateToAddress(latitude: number, longitude: number, configName?: string): string

// Convert address to coordinates  
addressToCoordinate(address: string, configName?: string): [number, number]

Validation

// Simple validation (returns boolean)
isValidAddress(address: string, configName?: string): boolean

// Detailed validation (returns ValidationResult with errors/suggestions)
isValidAddress(address: string, configName: string, detailed: true): ValidationResult

Geographic Analysis

// Calculate distance between addresses
calculateDistance(address1: string, address2: string, configName?: string): number

// Find nearby addresses within radius
findNearbyAddresses(
  centerAddress: string, 
  radiusKm: number, 
  configName?: string
): Array<{address: string, distance: number, coordinates: [number, number]}>

// Get geographic bounds for address
getAddressBounds(address: string, configName?: string): GeographicBounds

// Cluster addresses by proximity
clusterAddresses(
  addresses: string[], 
  maxDistanceKm: number, 
  configName?: string
): Array<{addresses: string[], center: [number, number], bounds: GeographicBounds}>

Advanced Analysis

// Get partial location estimates
estimateLocationFromPartial(
  partialAddress: string, 
  configName?: string, 
  comprehensive?: boolean
): PartialLocationEstimate

// Analyze address with phonetic alternatives
analyzeAddress(address: string, configName?: string): AddressAnalysis

Configuration Management

// List available configurations
listAvailableConfigs(): string[]

// Get configuration details
getConfigInfo(configName: string): ConfigInfo

// Find configs by letters
findConfigsByLetters(letters: string[]): string[]

// System optimization
suggestSystemForLanguage(language?: string, precisionMeters?: number): H3SyllableSystem

H3SyllableSystem Class

const system = new H3SyllableSystem(configName?: string);

// Core methods
system.coordinateToAddress(lat: number, lon: number): string
system.addressToCoordinate(address: string): [number, number]
system.isValidAddress(address: string, detailed?: boolean): boolean | ValidationResult

// Analysis methods  
system.analyzeAddress(address: string): AddressAnalysis
system.estimateLocationFromPartial(partial: string, comprehensive?: boolean): PartialLocationEstimate

// System information
system.getSystemInfo(): SystemInfo
system.getConfig(): SyllableConfig
system.clearCache(): void

🎯 Configuration Options

Choose from multiple configurations optimized for different languages and use cases:

// Default configuration (21 consonants, 5 vowels)
const system = new H3SyllableSystem('ascii-elomr'); // Default

// Japanese-friendly (no L/R confusion)
const system2 = new H3SyllableSystem('ascii-fqwclj');

// List all available configurations
import { listAvailableConfigs, getConfigInfo } from '@alvarosilva/hex-address';

const configs = listAvailableConfigs();
configs.forEach(config => {
  const info = getConfigInfo(config);
  console.log(`${config}: ${info.totalSyllables} syllables, ${info.addressLength} length`);
});

🔬 Technical Details

• Precision: ~0.5 meter accuracy (H3 Resolution 15)
• Coverage: Global coverage with 122 × 7^15 ≈ 579 trillion addresses
• Performance: Optimized with caching and efficient algorithms
• Memory: Minimal footprint with configurable cache limits
• Browser Support: Works in all modern browsers with polyfills

Geographic Similarity

Nearby locations share address prefixes, making addresses intuitive:

// Coordinates ~75m apart in Paris
coordinateToAddress(48.8566, 2.3522); // "dinenunukiwufeme"
coordinateToAddress(48.8567, 2.3523); // "dinenunukiwufene"
//                                     ^^^^^^^^^^^^^^^ shared prefix (93%)

📖 Examples & Documentation

• Complete Examples - Real-world use cases and code samples
• Validation Guide - Detailed validation and error handling
• System Comparison - How hex-address compares to What3Words, Plus Codes, etc.

🧪 Testing Your Integration

import { coordinateToAddress, addressToCoordinate, calculateDistance } from '@alvarosilva/hex-address';

// Test round-trip accuracy
function testAccuracy(lat, lon) {
  const address = coordinateToAddress(lat, lon);
  const [newLat, newLon] = addressToCoordinate(address);
  const error = calculateDistance(
    coordinateToAddress(lat, lon),
    coordinateToAddress(newLat, newLon)
  );
  
  console.log(`Original: ${lat}, ${lon}`);
  console.log(`Address: ${address}`);
  console.log(`Converted: ${newLat}, ${newLon}`);
  console.log(`Error: ${(error * 1000).toFixed(1)}m`);
}

testAccuracy(48.8566, 2.3522); // Test with Eiffel Tower coordinates

🔧 Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Run linting  
npm run lint

# Type checking
npm run type-check

📦 Package Information

• Size: ~50KB minified
• Dependencies: h3-js only
• Node.js: 16+ required
• Browser: Modern browsers with ES2020 support
• TypeScript: Full type definitions included

🆕 What's New in v1.3.0

• ✅ Enhanced Validation: Detailed error messages with phonetic suggestions
• ✅ Geographic Utilities: Distance calculation, nearby search, clustering
• ✅ Better Error Handling: Comprehensive validation with specific error types
• ✅ Phonetic Suggestions: 54 phonetic confusion patterns for voice applications
• ✅ Performance Improvements: Optimized algorithms and caching
• ✅ Complete Documentation: Extensive examples and guides

🤝 Contributing

Contributions welcome! Please read our Contributing Guide for details.

📄 License

MIT License - see LICENSE for details.

Need help? Check out our Examples or open an issue on GitHub.