# Hex Address - Python Package
[](https://badge.fury.io/py/hex-address)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
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
```bash
pip install hex-address
```
```python
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
```bash
# 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:
```python
# 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:
```python
# 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
```python
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
```python
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](https://hex-address-app.vercel.app/).
## 🤝 Contributing
Contributions welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
## 📄 License
MIT License - see [LICENSE](../../LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "hex-address",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "h3, gps, coordinates, hex, address, geospatial, mapping",
"author": null,
"author_email": "\u00c1lvaro Silva <alvaro@sanluca.cc>",
"download_url": "https://files.pythonhosted.org/packages/78/14/96eee88706b6b5710e48875eb290efde959f100bf31fcc927cc7a82b427c/hex_address-1.2.0.tar.gz",
"platform": null,
"description": "# Hex Address - Python Package\n\n[](https://badge.fury.io/py/hex-address)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nConvert 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.\n\n## \ud83d\ude80 Quick Start\n\n```bash\npip install hex-address\n```\n\n```python\nfrom hex_address import H3SyllableSystem\n\n# Initialize system (uses default ascii-fqwfmd config)\nsystem = H3SyllableSystem()\n\n# Convert coordinates to syllable address \naddress = system.coordinate_to_syllable(48.8566, 2.3522)\nprint(address) # \"je-ma-su-cu|du-ve-gu-ba\"\n\n# Convert back to coordinates\nlat, lon = system.syllable_to_coordinate(address)\nprint(f\"{lat:.6f}, {lon:.6f}\") # 48.856602, 2.352198\n\n# Validate addresses (some combinations don't exist)\nif system.is_valid_syllable_address(address):\n print(\"Valid address!\")\n```\n\n## \ud83d\udee0\ufe0f Command Line Interface\n\n```bash\n# Convert coordinates to syllable address\nhex-address coordinate 48.8566 2.3522\n\n# Convert syllable address to coordinates \nhex-address syllable \"je-ma-su-cu|du-ve-gu-ba\"\n\n# Validate an address\nhex-address validate \"je-ma-su-cu|du-ve-gu-ba\"\n\n# List available configurations\nhex-address configs\n\n# Use specific configuration\nhex-address --config ascii-cjbnb coordinate 48.8566 2.3522\n```\n\n## \ud83d\udccb Features\n\n- **Sub-meter precision** (~0.5m) using H3 Level 15\n- **Spatially optimized** with perfect Hamiltonian path (100% adjacency)\n- **Memorable addresses** using pronounceable syllables\n- **Geographic similarity** - nearby locations share syllable prefixes like postal codes\n- **Perfect reversibility** for all real coordinates\n- **Dynamic formatting** with pipe separators for readability\n- **Multiple configurations** optimized for different use cases\n- **Pure ASCII** letters for universal compatibility\n- **CLI tool** for easy integration\n\n## \ud83c\udfaf Configuration Options\n\nChoose from multiple configurations based on your needs:\n\n```python\n# Full ASCII alphabet (21 consonants, 5 vowels, 8 syllables)\nsystem = H3SyllableSystem('ascii-fqwfmd') # Default\n\n# Minimal balanced (10 consonants, 5 vowels, 9 syllables) \nsystem = H3SyllableSystem('ascii-cjbnb')\n\n# Japanese-friendly (no L/R confusion)\nsystem = H3SyllableSystem('ascii-fqwclj')\n\n# List all available configurations\nfrom h3_syllable import list_available_configs\nprint(list_available_configs())\n```\n\n## \ud83c\udf0d Use Cases\n\n- **Emergency services**: Share precise locations memorably\n- **Logistics**: Human-friendly delivery addresses \n- **Gaming**: Location-based game mechanics\n- **International**: Cross-language location sharing with ASCII compatibility\n- **Navigation**: Easy-to-communicate waypoints\n\n## \ud83d\udd2c Technical Details\n\n- **Precision**: ~0.5 meter accuracy (H3 Resolution 15)\n- **Coverage**: 122 \u00d7 7^15 = 579,202,504,213,046 H3 positions\n- **Constraint**: max_consecutive = 1 (no adjacent identical syllables)\n- **Spatial optimization**: 100% adjacency through Hamiltonian path\n- **Geographic ordering**: Syllables ordered coarse-to-fine (like postal codes)\n- **Performance**: ~6,700 conversions/second\n\n### Geographic Similarity\n\nNearby locations share syllable prefixes, making addresses intuitive:\n\n```python\n# Coordinates ~75m apart in Paris\nsystem.coordinate_to_syllable(48.8566, 2.3522) # \"bi-me-mu-mu|hi-vu-ka-ju\"\nsystem.coordinate_to_syllable(48.8567, 2.3523) # \"bi-me-mu-mu|hi-vu-ne-go\"\n # ^^^^^^^^^^^^^^^ shared prefix (75%)\n```\n\nThis works because syllables represent geographic hierarchy from coarse (continent/country) to fine (meter-level), similar to how postal codes work.\n\n## \ud83d\udcd6 API Reference\n\n### Core Functions\n\n```python\nfrom hex_address import H3SyllableSystem\n\n# Initialize with specific configuration\nsystem = H3SyllableSystem('ascii-fqwfmd')\n\n# Convert coordinates to syllable\naddress = system.coordinate_to_syllable(latitude, longitude)\n\n# Convert syllable to coordinates\nlatitude, longitude = system.syllable_to_coordinate(address)\n\n# Validate syllable address\nis_valid = system.is_valid_syllable_address(address)\n\n# Get system information\ninfo = system.get_system_info()\n\n# Test round-trip accuracy\nresult = system.test_round_trip(latitude, longitude)\n```\n\n### Convenience Functions\n\n```python\nfrom h3_syllable import coordinate_to_syllable, syllable_to_coordinate\n\n# Quick conversions with default config\naddress = coordinate_to_syllable(48.8566, 2.3522)\nlat, lon = syllable_to_coordinate(address)\n\n# With specific config\naddress = coordinate_to_syllable(48.8566, 2.3522, config_name='ascii-cjbnb')\n```\n\n## \ud83d\udcd6 Documentation\n\nFor complete documentation, architecture details, and live demo, visit the [Hex Address App](https://hex-address-app.vercel.app/).\n\n## \ud83e\udd1d Contributing\n\nContributions welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](../../LICENSE) for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert GPS coordinates to memorable hex addresses using H3",
"version": "1.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/alvasilvao/hex-address/issues",
"Documentation": "https://hex-address-app.vercel.app/",
"Homepage": "https://hex-address-app.vercel.app/",
"Repository": "https://github.com/alvasilvao/hex-address.git"
},
"split_keywords": [
"h3",
" gps",
" coordinates",
" hex",
" address",
" geospatial",
" mapping"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d800cb3646ba0d5881de874791e01f7f43da4e04b6494c14a13095f17d03b65a",
"md5": "10be9803a8e8be38f44d60859841729d",
"sha256": "e011c5b505adfb15925eff44d5c7c6505e6d60285de4cca261feb2206019addb"
},
"downloads": -1,
"filename": "hex_address-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "10be9803a8e8be38f44d60859841729d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22989,
"upload_time": "2025-07-14T21:34:35",
"upload_time_iso_8601": "2025-07-14T21:34:35.426958Z",
"url": "https://files.pythonhosted.org/packages/d8/00/cb3646ba0d5881de874791e01f7f43da4e04b6494c14a13095f17d03b65a/hex_address-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "781496eee88706b6b5710e48875eb290efde959f100bf31fcc927cc7a82b427c",
"md5": "219d7f628554738f50575d769ace4b0d",
"sha256": "bd59e9ec315117aec5d88d036e8e33f87a14d39b8995a71f9989c4b08b778c6f"
},
"downloads": -1,
"filename": "hex_address-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "219d7f628554738f50575d769ace4b0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24198,
"upload_time": "2025-07-14T21:34:37",
"upload_time_iso_8601": "2025-07-14T21:34:37.518769Z",
"url": "https://files.pythonhosted.org/packages/78/14/96eee88706b6b5710e48875eb290efde959f100bf31fcc927cc7a82b427c/hex_address-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 21:34:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alvasilvao",
"github_project": "hex-address",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hex-address"
}
JSON
