geohashing

TypeScript-written Geohash library for Node.js and the browser.

Install

npm install geohashing

or

yarn add geohashing

Usage

import { encodeBase32, decodeBase32 } from 'geohashing';

const hash = encodeBase32(40.1838684, 44.5138549);
console.log(hash);

const { lat, lng, error } = decodeBase32(hash);
console.log(`Latitude: ${lat}±${error.lat}`);
console.log(`Longitude: ${lng}±${error.lng}`);

Support of two Geohash formats

Geohash can be either an integer number or a Base32 string (Geohash uses its own Base32 variant). The precision of a Geohash integer is defined by its bit depth, which must be between 1 and 52. The precision of a Geohash Base32 string is defined by its length, which must be between 1 and 9.

Bit depth can be either odd or even. An odd bit depth results in equal latitude and longitude errors, which means that an encoded cell must be square. However, due to the nonlinearity of the coordinate system, it depends a lot on latitude (compare the cell at the equator and more northerly cell).

An even bit depth results in a rectangular cell. If we had a square cell encoded with a 31-bit depth, encoding the same coordinates with a 32-bit depth would result in half the square (example).

Encoding and decoding

encodeInt(lat, lng [, bitDepth])

Encodes coordinates and returns a Geohash integer. bitDepth defines precision of encoding. The bigger the value, the smaller the encoded cell.

encodeBase32(lat, lng [, length])

Encodes coordinates and returns a Geohash Base32 string. length is a number of characters in the output string. The bigger the value, the smaller the encoded cell.

decodeInt(hashInt [, bitDepth])

Decodes a Geohash integer and returns an object with coordinates:

{
  lat: string;
  lng: string;
  error: {
    lat: string;
    lng: string;
  } 
}

decodeBase32(hashBase32)

Decodes a Geohash Base32 string and returns an object with coordinates like decodeInt().

Neighbors

getNeighborInt(hashInt, direction [, bitDepth])

Calculates a Geohash integer of a neighbor cell. direction specifies which neighbor should be found (e.g. northern, southwestern, etc.)

import { getNeighborInt } from 'geohashing';

const neighbor = getNeighborInt(1677051423, 'north', 31);
console.log(neighbor); // 1677051445

getNeighborBase32(hashBase32, direction)

Calculates Geohash Base32 string of a neighbor cell.

getNeighborsInt(hashInt [, bitDepth])

Calculates Geohash integers of all neighbor cells. Returns a Neghbors object with the following properties:

{
  north:     number;
  northEast: number;
  east:      number;
  southEast: number;
  south:     number;
  southWest: number;
  west:      number;
  northWest: number;
}

getNeighborsBase32(hashBase32)

Calculates Geohash Base32 strings of all neighbor cells. Returns a Neghbors object similar to what getNeighborsInt() returns, but containing string properties instead.

Bounding boxes

encodeBboxInt(minLat, minLng, maxLat, maxLng)

Finds the smallest cell that the given bbox fits into. Returns an object with a Geohash integer and bit depth that represent that cell:

{ hashInt, bitDepth }

This example shows the Geohash integer (which encodes the outer bbox) that would be found if the inner bbox was passed into the function.

decodeBboxInt(hashInt [, bitDepth])

Calculates edge coordinates of the encoded cell. Takes a Geohash integer. Returns a Bbox object with coordinates:

{ 
  minLat: number;
  minLng: number;
  maxLat: number;
  maxLng: number;
}

encodeBboxBase32(minLat, minLng, maxLat, maxLng)

Finds a Geohash Base32 string that represents the smallest cell which the given bbox fits into (see encodeBboxInt()).

decodeBboxBase32(hashBase32)

Calculates edge coordinates of the encoded cell. Takes a Geohash Base32 string. Returns a Bbox object similar to what decodeBboxInt() returns.

getHashesWithinBboxInt(minLat, minLng, maxLat, maxLng [, bitDepth])

Calculates all Geohash integer values within the box. Returns an array of Geohash integers.

getHashesWithinBboxBase32(minLat, minLng, maxLat, maxLng [, length])

Calculates all Geohash Base32 values within the box. Returns an array of Geohash Base32 strings.

Base32

intToBase32(intValue, precision)

Convert an integer to a base-32 string (Geohash Base32 variant is used). Precision is required to fill the output with leading zeros if necessary.

base32ToInt(base32Value)

Convert a base-32 string to an integer (Geohash Base32 variant is used).

GeoJSON

The library can convert Geohash to GeoJSON Feature.

hashIntToRectangle(hashInt [, bitDepth])

Takes a Geohash integer and bit depth and returns a GeoJSON object, where the encoded cell is represented by a Polygon (see example).

hashBase32ToRectangle(hashBase32)

Takes a Geohash Base32 string and returns a GeoJSON object, like hashIntToRectangle() does.

hashIntArrayToMultiPolygon(hashIntArray)

Converts an array of Geohash integer/bit depth pairs to a GeoJSON object with MultiPolygon geometry containing all rectangle areas encoded with provided hashes (see example).

hashBase32ArrayToMultiPolygon(hashBase32Array)

Converts an array of Geohash Base32 strings to a GeoJSON object, like hashIntArrayToMultiPolygon() does.

License

geohashing is MIT licensed.