Python Geohash (Legacy)

Warnings

• breaking This library (python-geohash 0.8.5) is largely unmaintained since its last update in 2014. Users are strongly advised to consider more actively developed and modern alternatives like the 'pygeohash' library (lowercase 'p' in package name) for current projects, which offers Python 3 support, zero dependencies, and performance optimizations.
  Fix: Migrate to a maintained library such as `pygeohash` (`pip install pygeohash`).
• gotcha Installation issues with the optional C extension are common on modern operating systems (e.g., macOS with newer Python versions), potentially leading to `command 'g++' failed with exit status 1` errors during `pip install`. The library can fall back to a pure Python implementation, but this might result in a silent performance degradation or complete installation failure.
  Fix: Ensure a C/C++ compiler is installed and properly configured, or consider using the pure Python fallback if the C extension fails to build (though this library's pure Python mode might still be slow compared to modern alternatives). Migrating to `pygeohash` (which has its own optimized CPython core) is the recommended solution.
• gotcha The `decode()` function returns raw float values for latitude and longitude. Some other geohash libraries might return a tuple with error margins or a custom object, which could lead to incompatibility if migrating between libraries or expecting a specific structured output.
  Fix: Adjust code to handle the direct float return values. If migrating, review the decoding output format of the new library carefully.
• gotcha Geohashes, by nature, can sometimes represent geographically close points with different prefixes if they fall on opposite sides of a geohash grid boundary. This can affect proximity search logic based solely on prefix matching.
  Fix: For precise proximity searches, supplement geohash prefix matching with bounding box queries or actual distance calculations for candidate geohashes, rather than relying solely on shared prefixes.

Install

• pip install python-geohash Basic installation

Imports

• encode

  import geohash; geohash.encode(lat, lng)

  The package name for installation is 'python-geohash', but the import module name is 'geohash'.
• decode

  import geohash; geohash.decode(geohash_string)

  The package name for installation is 'python-geohash', but the import module name is 'geohash'.
• encode_uint64

  import geohash; geohash.encode_uint64(lat, lng)

  For working with 64-bit integer geohash representation, introduced in version 0.8.
• decode_uint64

  import geohash; geohash.decode_uint64(uint64_hash)

  For decoding 64-bit integer geohash representation.

Quickstart

This quickstart demonstrates how to encode latitude and longitude coordinates into geohash strings, control the precision, and decode geohash strings back into coordinates using the `geohash` module. It also shows the usage of `uint64` representation for integer-based geohashing.

import geohash

# Encode coordinates to a geohash string with default precision (12 characters)
latitude, longitude = 42.6, -5.6
geohash_string = geohash.encode(latitude, longitude)
print(f"Encoded geohash: {geohash_string}")

# Encode with custom precision
short_geohash = geohash.encode(latitude, longitude, precision=5)
print(f"Short geohash (precision 5): {short_geohash}")

# Decode a geohash string back to coordinates
decoded_lat, decoded_lng = geohash.decode(geohash_string)
print(f"Decoded coordinates: ({decoded_lat}, {decoded_lng})")

# Example with uint64 representation
uint64_hash = geohash.encode_uint64(latitude, longitude)
print(f"Encoded uint64 geohash: {uint64_hash}")
decoded_lat_uint64, decoded_lng_uint64 = geohash.decode_uint64(uint64_hash)
print(f"Decoded uint64 coordinates: ({decoded_lat_uint64}, {decoded_lng_uint64})")