{"id":16625,"library":"geohash-area","title":"Geohash Area Utilities","description":"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.","status":"active","version":"0.1.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install geohash-area","lang":"bash","label":"npm"},{"cmd":"yarn add geohash-area","lang":"bash","label":"yarn"},{"cmd":"pnpm add geohash-area","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const geohash = require('geohash-area');","symbol":"geohash","correct":"import * as geohash from 'geohash-area';"},{"note":"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.","wrong":"import { rect } from 'geohash-area';","symbol":"rect","correct":"import * as geohash from 'geohash-area';\nconst geohashes = geohash.rect(34.0522, -118.2437, 10, 6);"},{"note":"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.","wrong":"import { GeohashString } from 'geohash-area';","symbol":"GeohashString","correct":"import * as geohash from 'geohash-area';\nfunction processGeohash(hash: string): void { /* ... */ }"}],"quickstart":{"code":"import * as geohash from 'geohash-area';\n\n// 1. Encode a point to a geohash\nconst lat = 34.0522;\nconst lng = -118.2437;\nconst precision = 6;\nconst encodedHash = geohash.encode(lat, lng, precision);\nconsole.log(`Encoded Geohash for (${lat}, ${lng}) with precision ${precision}: ${encodedHash}`);\n\n// 2. Decode a geohash to its bounding box and midpoint\nconst decodedInfo = geohash.decode(encodedHash);\nconsole.log('Decoded Geohash info:', decodedInfo);\n\n// 3. Generate geohashes for a rectangular area around a point\nconst distanceMiles = 5;\nconst areaHashes = geohash.rect(lat, lng, distanceMiles, precision);\nconsole.log(`Geohashes covering a ${distanceMiles}-mile radius around (${lat}, ${lng}):`, areaHashes.slice(0, 5), `... (${areaHashes.length} total)`);\n\n// 4. Calculate distance between two points (in miles)\nconst point1 = { lat: 34.0522, lng: -118.2437 };\nconst point2 = { lat: 34.0000, lng: -118.2000 };\nconst dist = geohash.distance(point1, point2);\nconsole.log(`Distance between (${point1.lat}, ${point1.lng}) and (${point2.lat}, ${point2.lng}): ${dist.toFixed(2)} miles`);","lang":"typescript","description":"Demonstrates encoding, decoding, generating geohashes for a rectangular area, and calculating distance between two points using the `geohash-area` library."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<=0.1.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Use a module namespace import: `import * as geohash from 'geohash-area';` and then access the function as `geohash.encode(...)`.","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.","error":"TypeError: geohash.encode is not a function"},{"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.","cause":"The `precision` parameter (geohash length) provided to functions like `encode`, `rect`, or `area` is outside the acceptable range (typically 1 to 12).","error":"RangeError: precision must be between 1 and 12"},{"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.","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.","error":"TypeError: fn is not a function"}],"ecosystem":"npm"}