hex-address 1.4.0

Convert GPS coordinates to memorable hex addresses using H3

Hex Address - Python Package

Convert GPS coordinates to memorable syllable addresses like je-ma-su-cu|du-ve-gu-ba with ~0.5 meter precision using spatially optimized H3 indexing.

🚀 Quick Start

pip install hex-address

from hex_address import H3SyllableSystem

# Initialize system (uses default ascii-fqwfmd config)
system = H3SyllableSystem()

# Convert coordinates to syllable address  
address = system.coordinate_to_syllable(48.8566, 2.3522)
print(address)  # "je-ma-su-cu|du-ve-gu-ba"

# Convert back to coordinates
lat, lon = system.syllable_to_coordinate(address)
print(f"{lat:.6f}, {lon:.6f}")  # 48.856602, 2.352198

# Validate addresses (some combinations don't exist)
if system.is_valid_syllable_address(address):
    print("Valid address!")

🛠️ Command Line Interface

# Convert coordinates to syllable address
hex-address coordinate 48.8566 2.3522

# Convert syllable address to coordinates  
hex-address syllable "je-ma-su-cu|du-ve-gu-ba"

# Validate an address
hex-address validate "je-ma-su-cu|du-ve-gu-ba"

# List available configurations
hex-address configs

# Use specific configuration
hex-address --config ascii-cjbnb coordinate 48.8566 2.3522

📋 Features

• Sub-meter precision (~0.5m) using H3 Level 15
• Spatially optimized with perfect Hamiltonian path (100% adjacency)
• Memorable addresses using pronounceable syllables
• Geographic similarity - nearby locations share syllable prefixes like postal codes
• Perfect reversibility for all real coordinates
• Dynamic formatting with pipe separators for readability
• Multiple configurations optimized for different use cases
• Pure ASCII letters for universal compatibility
• CLI tool for easy integration

🎯 Configuration Options

Choose from multiple configurations based on your needs:

# Full ASCII alphabet (21 consonants, 5 vowels, 8 syllables)
system = H3SyllableSystem('ascii-fqwfmd')  # Default

# Minimal balanced (10 consonants, 5 vowels, 9 syllables) 
system = H3SyllableSystem('ascii-cjbnb')

# Japanese-friendly (no L/R confusion)
system = H3SyllableSystem('ascii-fqwclj')

# List all available configurations
from h3_syllable import list_available_configs
print(list_available_configs())

🌍 Use Cases

• Emergency services: Share precise locations memorably
• Logistics: Human-friendly delivery addresses
• Gaming: Location-based game mechanics
• International: Cross-language location sharing with ASCII compatibility
• Navigation: Easy-to-communicate waypoints

🔬 Technical Details

• Precision: ~0.5 meter accuracy (H3 Resolution 15)
• Coverage: 122 × 7^15 = 579,202,504,213,046 H3 positions
• Constraint: max_consecutive = 1 (no adjacent identical syllables)
• Spatial optimization: 100% adjacency through Hamiltonian path
• Geographic ordering: Syllables ordered coarse-to-fine (like postal codes)
• Performance: ~6,700 conversions/second

Geographic Similarity

Nearby locations share syllable prefixes, making addresses intuitive:

# Coordinates ~75m apart in Paris
system.coordinate_to_syllable(48.8566, 2.3522)  # "bi-me-mu-mu|hi-vu-ka-ju"
system.coordinate_to_syllable(48.8567, 2.3523)  # "bi-me-mu-mu|hi-vu-ne-go"
                                                 #  ^^^^^^^^^^^^^^^ shared prefix (75%)

This works because syllables represent geographic hierarchy from coarse (continent/country) to fine (meter-level), similar to how postal codes work.

📖 API Reference

Core Functions

from hex_address import H3SyllableSystem

# Initialize with specific configuration
system = H3SyllableSystem('ascii-fqwfmd')

# Convert coordinates to syllable
address = system.coordinate_to_syllable(latitude, longitude)

# Convert syllable to coordinates
latitude, longitude = system.syllable_to_coordinate(address)

# Validate syllable address
is_valid = system.is_valid_syllable_address(address)

# Get system information
info = system.get_system_info()

# Test round-trip accuracy
result = system.test_round_trip(latitude, longitude)

Convenience Functions

from h3_syllable import coordinate_to_syllable, syllable_to_coordinate

# Quick conversions with default config
address = coordinate_to_syllable(48.8566, 2.3522)
lat, lon = syllable_to_coordinate(address)

# With specific config
address = coordinate_to_syllable(48.8566, 2.3522, config_name='ascii-cjbnb')

📖 Documentation

For complete documentation, architecture details, and live demo, visit the Hex Address App.

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.