geohash-area

library0.1.0jsnpmunverified

The `geohash-area` library provides specialized utilities for working with geohashes, primarily focused on generating and querying geohashes for rectangular regions and arbitrary areas. It is designed to facilitate efficient spatial lookups in databases by producing a set of geohashes that cover a specific geographical extent. The package is currently at version 0.1.0, indicating an early development stage, and while a specific release cadence is not defined, its focused scope suggests a stable, yet evolving, set of core functionalities. Key differentiators include its unique `rect` function for radial geohash generation and an `area` function that supports recursively determining geohashes for complex, user-defined geographical boundaries via a callback, setting it apart from more generic geohash encoding/decoding libraries. It ships with comprehensive TypeScript type definitions, ensuring a robust development experience.

database data

npm install geohash-area

package ↗

INSTALL

IMPORT

SIG · GEOHASH-AREA

geohash-area

databasejavascriptv0.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

geohash

✓ import * as geohash from 'geohash-area';

✗ const geohash = require('geohash-area');

This package is designed for modern ESM usage, importing all functions under a namespace object. While CommonJS `require` might work in some environments, ESM is recommended. Named imports for individual functions are not directly supported by this namespace pattern.

rect

✓ import * as geohash from 'geohash-area'; const geohashes = geohash.rect(34.0522, -118.2437, 10, 6);

✗ import { rect } from 'geohash-area';

Functions like `rect` are exposed as properties of the main `geohash` export, not as top-level named exports. Direct named imports for individual functions will result in an undefined symbol error.

GeohashString

✓ import * as geohash from 'geohash-area'; function processGeohash(hash: string): void { /* ... */ }

✗ import { GeohashString } from 'geohash-area';

The library primarily uses `string` for geohash values. While it ships with TypeScript types, there isn't a specific `GeohashString` type to import; standard `string` should be used for type annotations. The library's types augment existing primitives or define interfaces for function parameters.

Demonstrates encoding, decoding, generating geohashes for a rectangular area, and calculating distance between two points using the `geohash-area` library.

import * as geohash from 'geohash-area'; // 1. Encode a point to a geohash const lat = 34.0522; const lng = -118.2437; const precision = 6; const encodedHash = geohash.encode(lat, lng, precision); console.log(`Encoded Geohash for (${lat}, ${lng}) with precision ${precision}: ${encodedHash}`); // 2. Decode a geohash to its bounding box and midpoint const decodedInfo = geohash.decode(encodedHash); console.log('Decoded Geohash info:', decodedInfo); // 3. Generate geohashes for a rectangular area around a point const distanceMiles = 5; const areaHashes = geohash.rect(lat, lng, distanceMiles, precision); console.log(`Geohashes covering a ${distanceMiles}-mile radius around (${lat}, ${lng}):`, areaHashes.slice(0, 5), `... (${areaHashes.length} total)`); // 4. Calculate distance between two points (in miles) const point1 = { lat: 34.0522, lng: -118.2437 }; const point2 = { lat: 34.0000, lng: -118.2000 }; const dist = geohash.distance(point1, point2); console.log(`Distance between (${point1.lat}, ${point1.lng}) and (${point2.lat}, ${point2.lng}): ${dist.toFixed(2)} miles`);

Debug

Known issues

breakingAs a 0.1.0 version package, the API surface (`geohash.rect`, `geohash.area`, etc.) may not be stable and could introduce breaking changes in minor or patch releases without following strict semantic versioning practices.

fix

Always pin to exact versions (e.g., `"geohash-area": "0.1.0"`) and thoroughly review release notes when upgrading to new versions, even patch or minor releases.

affects: <=0.1.0

gotchaThe `geohash.distance` function explicitly returns distance in *miles*. This can be a common source of error for developers expecting kilometers or needing a different unit without explicit conversion.

fix

Be aware that the unit is miles. If kilometers or another unit is required, perform a conversion manually after obtaining the result from `geohash.distance` (e.g., `distanceInKm = distanceInMiles * 1.60934`).

affects: >=0.1.0

gotchaThe `geohash.area` function requires a recursive callback function (`fn`) to determine if a geohash is within the area of interest. Incorrectly implementing this `fn` (e.g., returning `1` for partial inclusion or `2` for full inclusion) can lead to inaccurate or incomplete area coverage.

fix

Carefully review the documentation for the `fn` parameter of `geohash.area`. Ensure your callback correctly returns `0` (not included), `1` (partially included), or `2` (fully included) as specified to guarantee accurate area coverage.

affects: >=0.1.0

gotchaThe `precision` parameter in `encode`, `rect`, and `area` functions directly impacts the granularity and number of geohashes generated. Very high precision can lead to a large number of geohashes, potentially causing performance issues or excessive database queries.

fix

Start with a lower precision and gradually increase it, monitoring performance and the number of generated geohashes. Choose the lowest precision that meets your application's accuracy requirements to optimize performance.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: geohash.encode is not a function

Attempting to import individual functions as named exports (e.g., `import { encode } from 'geohash-area'`) instead of importing the entire module namespace or default export.

fix

Use a module namespace import: `import * as geohash from 'geohash-area';` and then access the function as `geohash.encode(...)`.

RangeError: precision must be between 1 and 12

The `precision` parameter (geohash length) provided to functions like `encode`, `rect`, or `area` is outside the acceptable range (typically 1 to 12).

fix

Ensure the `precision` value passed to geohash functions is an integer between 1 and 12, inclusive. Refer to geohash standards for appropriate precision levels based on desired accuracy.

TypeError: fn is not a function

The `fn` parameter for `geohash.area` was not provided or was not a callable function, leading to an attempt to invoke an undefined or non-function value.

fix

Ensure that a valid callback function is passed as the first argument to `geohash.area`. This function should accept a geohash string and return `0`, `1`, or `2` based on its relation to the area of interest.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/geohash-area ↗