mapcode — TypeScript / JavaScript Library

Encode a latitude/longitude pair to one or more mapcodes and decode a mapcode string back to a geographic point. The library is isomorphic: it works in Node.js (ESM and CommonJS) and in the browser with no external dependencies.

Mapcodes are short, memorable location codes maintained by the Stichting Mapcode Foundation.

This is a faithful TypeScript port of the mapcode-java library (version 2.4.19).

Licensed under the Apache License, Version 2.0. Copyright (C) 2014-2026, Stichting Mapcode Foundation.

---

Installation

npm install mapcode-ts

---

Quick start

All entry points are top-level named exports — there is no MapcodeCodec class (unlike the Java library).

import {
  encode, encodeToShortest, encodeToInternational,
  decode, decodeToRectangle,
  Territory, Alphabet,
} from "mapcode-ts";

Encode a lat/lon to all mapcodes

const mapcodes = encode(52.376514, 4.908542);
// Returns an array of Mapcode objects, shortest first within each territory.
for (const m of mapcodes) {
  console.log(m.getCodeWithTerritory()); // e.g. "NLD 49.4V", ..., "AAA VHXGB.1J9J"
}

Restrict encoding to a specific territory

const mapcodes = encode(52.376514, 4.908542, Territory.NLD);
// [ "NLD 49.4V", "NLD G9.VWG", "NLD DL6.H9L", "NLD P25Z.N3Z" ]

Get only the shortest mapcode for a territory

const m = encodeToShortest(52.376514, 4.908542, Territory.NLD);
console.log(m.getCode());              // "49.4V"
console.log(m.getCodeWithTerritory()); // "NLD 49.4V"
console.log(m.getTerritory().name);    // "NLD"

Get only the international (world-wide) mapcode

const m = encodeToInternational(52.376514, 4.908542);
console.log(m.getCode()); // "VHXGB.1J9J"

Decode a mapcode to a Point

// Territory prefix in the string, or pass as second argument:
const pt1 = decode("NLD 49.4V");
const pt2 = decode("49.4V", Territory.NLD);

console.log(pt1.getLatDeg()); // 52.376514
console.log(pt1.getLonDeg()); // 4.908543  (may differ slightly from input — decode is lossless to ~1 μ°)

// International mapcode (no territory needed):
const pt3 = decode("VHXGB.1J9J");

Decode to a bounding rectangle

const rect = decodeToRectangle("49.4V", Territory.NLD);
console.log(rect.getSouthWest()); // Point { lat: 52.376469°, lon: 4.908471° }
console.log(rect.getNorthEast()); // Point { lat: 52.376559°, lon: 4.908617° }
console.log(rect.getCenter());    // same as decode("49.4V", Territory.NLD)

Using Territory and Alphabet

// Territories are static class instances (not a plain enum):
const t = Territory.fromString("NLD");
console.log(t === Territory.NLD); // true
console.log(t.getFullName());     // "Netherlands"

// Request a mapcode rendered in a specific alphabet:
const m = encodeToShortest(37.9715, 23.7263, Territory.GRC);
console.log(m.getCode());                         // Roman: "HJ.Q5"
console.log(m.getCode(Alphabet.GREEK));           // Greek script: "ΗΠ.485"

---

Java → TypeScript API mapping

Java (mapcode-java)	TypeScript (this library)
MapcodeCodec.encode(...)	encode(...) (top-level function)
MapcodeCodec.encodeToShortest(...)	encodeToShortest(...)
MapcodeCodec.encodeToInternational(...)	encodeToInternational(...)
MapcodeCodec.encodeRestrictToCountryISO2(…)	encodeRestrictToCountryISO2(…)
MapcodeCodec.encodeRestrictToCountryISO3(…)	encodeRestrictToCountryISO3(…)
MapcodeCodec.encodeRestrictToCountryISO(…)	encodeRestrictToCountryISO(…)
MapcodeCodec.decode(...)	decode(...)
MapcodeCodec.decodeToRectangle(...)	decodeToRectangle(...)
MapcodeCodec.isNearMultipleBorders(...)	isNearMultipleBorders(...)
IllegalArgumentException	IllegalArgumentError
IllegalStateException	IllegalStateError
UnknownMapcodeException	UnknownMapcodeError
UnknownTerritoryException	UnknownTerritoryError
UnknownAlphabetException	UnknownAlphabetError
UnknownPrecisionFormatException	UnknownPrecisionFormatError
UnknownDecodeException	UnknownDecodeError
IncorrectDataModelException	IncorrectDataModelError

Classes that keep their names: Mapcode, Territory, AlphaCodeFormat, Alphabet, Point, Rectangle.

Enums are implemented as classes with static instances (Territory.NLD, Alphabet.GREEK). Use Territory.fromString("NLD") and Alphabet.fromString("GREEK") to look up by name.

---

Data regeneration

The binary territory data shipped in src/data/mminfo-data.ts is generated from data/mminfo.dat:

npm run gen:data

Re-run this whenever data/mminfo.dat is updated.

---

Development

npm test          # run the full test suite (vitest)
npm run build     # compile to dist/ (ESM + CJS + .d.ts via tsup)
npm run typecheck # type-check without emitting