quad-hexer

Overview

quad-hexer is a JavaScript library that losslessly compresses location coordinate encodings by approximately 50% by converting the quaternary part (base-4 expression) of geocode formats such as Quadkey, S2 Hilbert Quadkey, and Spatial ID Tilehash (Z-order curve) into a hexadecimal format starting with x.

When converting each quaternary digit (2 bits) into hexadecimal (4 bits), if the total number of digits (level) is odd, a # symbol is added as an indicator, followed by a single quaternary character (0–3).
This mechanism preserves both prefix-matching searchability and sort order of the original quaternary representation.

Example (latitude/longitude 35.675, 139.762):

When using Spatial ID with a nonzero F (Floor / Altitude) component, the hexadecimal encoding appends a + or - to indicate the sign, followed by the hexadecimal value of the F component after the XYZ part.

• Example: Latitude/longitude 35.675, 139.762 with altitude 100 meters at zoom level 23
  • ZFXY format: 23/25/7450994/3303428
  • Tilehash (Z-order curve): 24411322342311212265325
  • Encoded value: x7c25b604549#0+19

Demo

https://sanak.github.io/quad-hexer/

Installation

npm install quad-hexer
# or
# yarn add quad-hexer
# pnpm add quad-hexer

Usage

Quadkey

import { quadHexer } from 'quad-hexer';

const hexQuadkey = quadHexer.encodeQuadkey('13300211231200101110210');
console.log(hexQuadkey);
// => x7c25b604549#0
console.log(quadHexer.decodeHexQuadkey(hexQuadkey));
// => 13300211231200101110210

S2 Hilbert Quadkey

import { quadHexer } from 'quad-hexer';

const hexS2HilbertQuadkey = quadHexer.encodeS2HilbertQuadkey('3/000030101133133301211');
console.log(hexS2HilbertQuadkey);
// => 3x00c45f7f19#1
console.log(quadHexer.decodeHexS2HilbertQuadkey(hexS2HilbertQuadkey));
// => 3/000030101133133301211

Spatial ID Tilehash (Z-order curve)

import { quadHexer } from 'quad-hexer';

const hexSpatialIdTileHash = quadHexer.encodeSpatialIdTilehash('24411322342311212221321');
console.log(hexSpatialIdTileHash);
// => x7c25b604549#0
console.log(quadHexer.decodeHexSpatialIdTilehash(hexSpatialIdTileHash));
// => 24411322342311212221321

License

MIT License

Contribution

Bug reports and feature requests are welcome via GitHub Issues.
Pull requests are also highly appreciated!