Wayword

Wayword is a lightweight geocoding system that encodes geographic coordinates into short, human-friendly strings. It combines high precision (~5m), fixed-length codes, and typo-resistant formatting using checksum-verified word segments.

Features

• 📍 Short, consistent codes – Fixed-length 12-character base-25 string format.
• 🧠 Memorable output – Encodes into 3 human-readable words + 4-character seed+checksum suffix
• ✅ Checksum-verified – Detects common typos using a built-in checksum.
• 🌐 Global coverage – Works for any longitude/latitude on Earth.
• 🔒 Offline + open – No network or API required. Built for open-source use.

Installation

npm install wayword

or

yarn add wayword

Usage

Encode Coordinates

import { Wayword } from "wayword";

const coords: [number, number] = [51.5072, -0.1276]; // London
const w = new Wayword(coords);

console.log(w.formatted); // e.g., "fewa-tydy-tncf"

Decode Coordinates

import { Wayword } from "wayword";

const w = new Wayword("fewa-tydy-tncf");
console.log(w.coordinate); // [longitude,latitude]

Normalize Input (either format)

import { Wayword } from "wayword";

const w1 = new Wayword("fewa-tydy-tncf");
const w2 = new Wayword([51.5072, -0.1276]);

console.log(w1.raw === w2.raw); // true if same location

Autocomplete Suggestions

import { Wayword, autocomplete } from "wayword";

const suggestions = autocomplete("milo-je", [51.51391, -0.12312]);
console.log(suggestions);
// → [ { code: "milo-jeby-tzqt", distanceKm: 1.2 }, ... ]

API

| Function | Description | |:---|:---| | fromCoordinate([lat, lon]) | Encode a coordinate into a raw base-25 string | | toCoordinate(rawCode) | Decode a raw string back to a coordinate | | toFormatted(rawCode) | Convert a raw string into readable word form | | fromFormatted(str) | Parse a word-formatted string back to raw code | | normalizeInput(input) | Accepts either coordinates or formatted string and returns raw code | | autocomplete(partial, [coords]) | Suggest closest valid codes based on user input and optional location |

How It Works

Wayword divides the world into a 5×5 grid at each level, encoding location data into a raw 9-character base-25 string:

• The first 8 characters represent spatial location (grid walk).
• The 9th character is the deterministic seed for word mapping.

To generate the final human-readable code:

1. Split the raw string:
   • First 6 characters (two 3-char chunks) → two 4-letter words
   • Last 3 characters remain unconverted as the “seed segment”
2. Compute a 1-character checksum over the full 9-character string
3. Assemble the parts:
   [word1]-[word2]-[seedSegment][checksum]

Example

• Raw code: abcdefghi
  • Chunks: abc, def → word1, word2
  • Seed segment: ghi
  • Checksum: j
• Final: word1-word2-ghij

The checksum ensures that typos in the final formatted string are caught and rejected during decoding. This gives the system a level of safety similar to traditional error-correcting codes, with no additional length added to the core precision.

Format

Formatted Wayword codes always follow this structure:

[word1]-[word2]-[seed][checksum]

Examples:

• fewa-tydy-tncf
• bosa-defe-meeq
• jyra-vawe-jybi

Hyphens are optional — the system can parse input with or without them, and is case-insensitive:

new Wayword("FewaTydyTNcf").raw === new Wayword("fewa-tydy-tncf").raw

License

MIT License © 2025

Acknowledgments

• NATO Phonetic Alphabet
• Inspired by What3Words and Open Location Codes (Plus Codes)