geolib - Geohash encoding and decoding

Common errors

• AttributeError: module 'geolib' has no attribute 'encode'

  cause Users often attempt to call geohash functions directly on the top-level 'geolib' module after `import geolib`, instead of accessing them through the 'geohash' submodule.
  fix Import the 'geohash' submodule explicitly: `from geolib import geohash`. Then, call functions as `geohash.encode(...)`, `geohash.decode(...)`, etc.

• TypeError: float argument required, not str

  cause Latitude and longitude values passed to `geohash.encode()` are strings instead of the expected numeric types (float or int).
  fix Ensure that `latitude` and `longitude` variables are converted to `float` or `int` before being passed to `geohash.encode()`. Example: `geohash.encode(float(lat_str), float(lon_str), precision)`.

Warnings

• gotcha The `precision` parameter in `geohash.encode()` directly controls the length and granularity of the resulting geohash. An incorrect precision can lead to hashes that are either too coarse for the desired accuracy or unnecessarily long, impacting storage and comparison efficiency.
  Fix: Carefully choose the `precision` value (typically an integer between 1 and 12) based on the required spatial resolution for your application. Higher precision means a longer geohash and greater detail.
• gotcha The return types for core functions vary: `geohash.encode` returns a string, `geohash.decode` returns a tuple `(latitude, longitude)`, and `geohash.bbox` returns a dictionary with 'n', 's', 'e', 'w' keys for the bounding box corners. This inconsistency can lead to type errors if not handled explicitly.
  Fix: Always be mindful of the expected return type for each `geohash` function and destructure/access results accordingly. For `decode`, expect `lat, lon = geohash.decode(...)`; for `bbox`, expect `box_dict = geohash.bbox(...)`.
• gotcha While `geolib` officially supports Python >=2.7 (excluding 3.0-3.3), using it with Python 2.x in new projects is strongly discouraged. Encoding/decoding issues related to string types (unicode vs bytes) or default encodings can arise more easily in Python 2 environments, leading to subtle bugs.
  Fix: Prioritize using `geolib` with Python 3. If Python 2 compatibility is absolutely required, ensure all string inputs are consistently handled (e.g., explicitly converted to unicode) and thoroughly test all geohash operations.

Install

• pip install geolib Install stable version

Imports

• geohash
  wrong:

  import geolib; geolib.encode(...)

  correct:

  from geolib import geohash

  The primary geohash functions (encode, decode, bbox) reside within the 'geohash' submodule, not directly on the top-level 'geolib' module.

Quickstart

This quickstart demonstrates encoding geographical coordinates into a geohash, decoding a geohash back to coordinates, and calculating the bounding box for a given geohash string.

from geolib import geohash

# Example: Encode latitude and longitude into a geohash string
latitude = 39.04
longitude = -77.48
precision = 9 # Desired geohash length

encoded_hash = geohash.encode(latitude, longitude, precision)
print(f"Encoded geohash for ({latitude}, {longitude}) with precision {precision}: {encoded_hash}")

# Example: Decode a geohash string back to latitude and longitude
decoded_lat, decoded_lon = geohash.decode(encoded_hash)
print(f"Decoded coordinates from {encoded_hash}: Latitude={decoded_lat}, Longitude={decoded_lon}")

# Example: Get the bounding box for a geohash
bbox_coords = geohash.bbox(encoded_hash)
print(f"Bounding box for {encoded_hash}: {bbox_coords}")