@openstatestack/geo-token-code

GeoTokenCode

A modern ES6 TypeScript library to convert geographic coordinates into memorable four-word combinations for the OpenStateStack ecosystem.

Features

• Convert geographic coordinates (latitude/longitude) to four words
• Convert Plus Codes to four words
• Decode four words back to coordinates or Plus Codes
• Support for multiple languages (planned)
• TypeScript support with full type definitions
• Modern ES6 module format

Installation

npm install @openstatestack/geo-token-code-sdk

Usage

import { GeoTokenCode } from '@openstatestack/geo-token-code-sdk';

// Create a new instance
const geoTokenCode = new GeoTokenCode();

// Encode coordinates to words
const encoded = geoTokenCode.encodeFromCoordinates(47.36618749999998, 8.523671875000009);
console.log(encoded.words); // ["redhead", "differs", "tablets", "report"]

// Encode Plus Code to words
const encodedFromPlusCode = geoTokenCode.encodeFromPlusCode('8FVC9G8F+FFF');
console.log(encodedFromPlusCode.words); // ["redhead", "differs", "tablets", "report"]

// Decode words back to coordinates

const decoded = geoTokenCode.decodeToCoordinates(["redhead", "differs", "tablets", "report"]);
console.log(decoded.coordinates); // { latitude: 47.36618749999998, longitude: 8.523671875000009 }
console.log(decoded.plusCode); // '9C3W9QCJ+2V'

Configuration

You can configure the GeoTokenCode instance with options:

const geoTokenCode = new GeoTokenCode({
  language: 'en', // Language for word dictionary (default: 'en')
  precision: 1,  // Precision level for coordinates (default: 10)
  useShortCode: false // Whether to use short code format (default: false)
});

API Documentation

GeoTokenCode

The main class for encoding and decoding geographic coordinates.

Constructor

constructor(options?: GeoTokenCodeOptions)

Options:

• language: Language for word dictionary (default: 'en')
• precision: Precision level for coordinates (default: 11)
• useShortCode: Whether to use short code format (default: false)

Methods

encodeFromCoordinates(latitude: number, longitude: number): EncodingResult

Encode geographic coordinates to four words.

encodeFromPlusCode(plusCode: string): EncodingResult

Encode a Plus Code to four words.

decodeToCoordinates(words: string[]): DecodingResult

Decode four words back to geographic coordinates.

Types

EncodingResult

interface EncodingResult {
  words: string[];     // Array of four words representing the location
  plusCode: string;    // The original plus code
  confidence: number;  // Confidence score (1.0 = perfect match)
}

DecodingResult

interface DecodingResult {
  plusCode: string;    // The plus code representing the location
  coordinates: {
    latitude: number;
    longitude: number;
  };
  confidence: number;  // Confidence score (1.0 = perfect match)
}

How It Works

The GeoTokenCode library uses a deterministic algorithm to convert geographic coordinates (or Plus Codes) into four memorable words:

1. First, coordinates are converted to Plus Codes using Google's Open Location Code library.
2. The Plus Code is then converted to a numeric value.
3. This numeric value is used to select four words from a dictionary using a consistent mapping.
4. The process is reversible, allowing the words to be converted back to coordinates.

ES6 Module Format

This package uses ES6 modules. When importing in your project, make sure your environment supports ES modules. For Node.js, you may need to:

1. Use Node.js version 14 or higher
2. Add "type": "module" to your package.json

Development

Building

npm run build

Testing

npm test

License

OpenStateStack OSRUL-1.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.