Geohash Area Utilities

Common errors

• TypeError: geohash.encode is not a function

  cause 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

  cause 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

  cause 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.

Warnings

• breaking As 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.
• gotcha The `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`).
• gotcha The `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.
• gotcha The `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.

Install

• npm install geohash-area npm
• yarn add geohash-area yarn
• pnpm add geohash-area pnpm

Imports

• geohash
  wrong:

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

  correct:

  import * as geohash from '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
  wrong:

  import { rect } from 'geohash-area';

  correct:

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

  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
  wrong:

  import { GeohashString } from 'geohash-area';

  correct:

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

  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.

Quickstart

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`);