🌐 Ground Code Web Demo: ground.codes
🌀 How Grok Spiral works: grok-spiral.ground.codes
📚 API Documentation: api.ground.codes

Ground Codes is a coordinate-based addressing system that allows you to pinpoint any location in the world using just a region name and two words (e.g., "Yongsan-Happiness-Smile"). It leverages geographic coordinate systems (GCS) to provide a user-friendly alternative to traditional latitude and longitude coordinates.

And Ground Codes is a multi-planetary addressing system 🪐 that aims to provide a universal coordinate-based solution across celestial bodies. Currently operational on Earth, it will soon expand to support Mars and the Moon as part of its vision for a comprehensive multi-planetary address framework.

• 📍 ground-codes: the core implementation package that provides the fundamental encoding and decoding functionality for the Ground Codes coordinate-based addressing system
• 🗺️ @repo/geoint: a package for processing and providing curated geographical information about global regions with populations of 500 or more people
• 📖 @repo/codebook: a package for managing the word codebooks used in the coordinate encoding system
• 🌀 apps/grok-spiral: an interactive visualization app demonstrating the Grok Spiral coordinate generation system that powers Ground Codes' geospatial indexing
• 🖥️ apps/web: the main web application featuring an interactive Google Maps interface with POI details, grid system, and multilingual support for the Ground Codes system
• 🚀 apps/api-ground-codes: the API server providing endpoints for Ground Codes encoding/decoding services with OpenAPI/Swagger documentation

• 🧠 Simple and Memorable: Just three words to identify any location precisely
• 🌎 Global Coverage: Works anywhere in the world with a unique address
• 🔓 Open Source: MIT licensed and fully transparent implementation
• 🌐 Multilingual Support: Currently available in Korean and English, with plans to expand to 60 languages
• 🎯 Variable Precision: Offers three levels of precision (3m, 30cm, and 3cm) to suit different use cases

• 🆔 Ground Codes assigns globally unique addresses, while Plus Codes can be duplicated across different countries
• 🧭 The region name prefix provides immediate geographic context

• 🆓 Open source and free under MIT license, unlike What 3 Words' proprietary commercial model
• 🧭 The region name prefix gives immediate geographic context, while What 3 Words requires an app to determine approximate location

Ground Codes offers different precision levels through simple syntax changes:

• 📍 Yongsan-Happiness-Smile (3m precision) - Ideal for AI drone delivery destinations
• 🔍 Yongsan#Happiness#Smile (30cm precision) - Suitable for autonomous vehicle navigation
• 🔬 Yongsan+Consideration+Happiness+Smile (3cm precision) - Perfect for AI humanoid robot applications

Ground Codes is available through both web URLs and API access:

• 🌐 Web URL: ground.codes/Yongsan-Happiness-Smile → Shows the location on a map
• 🚀 API: api.ground.codes/Yongsan-Happiness-Smile → Returns latitude/longitude coordinates in JSON format

API usage is limited to 600 requests per minute per IP. For higher volume needs, paid API options or open-source modules are available.

• 🇬🇧 English word set: 6,000 words (AI-generated dataset)
• 🇰🇷 Korean word set: 5,630 words (AI-generated dataset)
• 🌎 Region names: 210,000 unique global locations with populations of 500+ (GeoNames data, commercially usable)
• 🔐 Special solutions:
  • Region 1: ✈️ Optimized for airports/logistics with country codes and airport codes (e.g., NYC-491AD, SSN-TA14C)
  • Region 0: 🛡️ Security solution (military/commercial) with custom central points and FPE encryption

Ground Codes uses a custom GIS algorithm called "Grok Spiral" 🌀 that determines coordinates by moving in a clockwise spiral from a central point. This implementation leverages the "Gauss Circle Problem" formula to achieve O(sqrt N) efficiency in coordinate generation. The spiral pattern maintains a circular shape regardless of distance from the center point, resulting in excellent coordinate indexing efficiency.

MIT License