Registry / data / pygeohash

pygeohash

JSON →
library3.3.2pypypi✓ verified 26d ago

PyGeoHash is a Python module that provides functions for encoding and decoding geohashes to and from latitude and longitude coordinates, along with utilities for performing calculations and approximations with them. It is a simple, lightweight, and dependency-free library, with core operations implemented in C for high performance. The current version is 3.2.2, and it maintains an active release cadence, having undergone a major rewrite to v3.0.0 in early 2025, focusing on performance enhancements and a license change, followed by several minor updates.

pip install pygeohash
INSTALL
IMPORT
SIG · PYGEOHASH
P
pygeohash
datapythonv3.3.2
Install
5.3s avg
Import
33ms
Disk
84MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.3.2 · pip install
no network on importno background threads
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
py 3.103.910 runs
build_error
glibc
py 3.103.910 runs
installs and imports cleanly · install 5.3s · import 0.033s · 19MB
84MB installed
● package 84MB
Code
Verified usage

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

pygeohash
import pygeohash as pgh
import geohash
The `pygeohash` library is a modern Python 3 compatible, dependency-free alternative to older, often Python 2-only, 'geohash' modules. Importing `geohash` directly will likely lead to an ImportError or an outdated, incompatible library.

This quickstart demonstrates how to encode latitude/longitude coordinates into geohashes, control precision, decode geohashes back to coordinates, calculate approximate distances between geohashes, and find adjacent geohashes using the `pygeohash` library.

import pygeohash as pgh # Encode coordinates to a geohash string latitude = 42.6 longitude = -5.6 geohash_full = pgh.encode(latitude, longitude) print(f"Full geohash: {geohash_full}") # e.g., 'ezs42e44yx96' # Encode with custom precision (e.g., 5 characters) geohash_short = pgh.encode(latitude, longitude, precision=5) print(f"Short geohash: {geohash_short}") # e.g., 'ezs42' # Decode a geohash string back to coordinates decoded_lat, decoded_lng = pgh.decode(geohash_short) print(f"Decoded: Latitude={decoded_lat}, Longitude={decoded_lng}") # e.g., Latitude=42.6, Longitude=-5.6 # Calculate approximate distance between two geohashes (in meters) distance = pgh.geohash_approximate_distance('bcd3u', 'bc83n') print(f"Approximate distance: {distance} meters") # e.g., 625441 # Find an adjacent geohash adjacent_geohash = pgh.get_adjacent(geohash='kd3ybyu', direction='right') print(f"Adjacent geohash (right): {adjacent_geohash}") # e.g., 'kd3ybyv'
Debug
Known issues
breakingPyGeoHash v3.0.0 introduced a complete rewrite of the core logic in CPython, removing previous dependencies like Numba and NumPy for core geohashing operations. The library also switched from a GPL-3.0 to an MIT license. Code relying on specific Numba/NumPy accelerated variants or the previous GPL license might break or behave differently.
fix
Review your codebase for direct dependencies on Numba/NumPy for `pygeohash`'s core functions. Adapt any license-sensitive usage. The new implementation is significantly faster and dependency-free for core functionality.
affects: >=3.0.0
gotchaInput coordinates must be within valid geographical ranges: latitude between -90.0 and 90.0 degrees, and longitude between -180.0 and 180.0 degrees. Providing values outside these ranges will result in a `ValueError` for functions like `encode` and `encode_strictly`.
fix
Ensure that latitude and longitude inputs are validated to be within their respective bounds (-90 <= lat <= 90, -180 <= lon <= 180) before passing them to `pygeohash` functions.
affects: All
gotchaGeohash strings must adhere to the base32 character set (0-9, b-h, j-k, m-n, p-z) and be between 1 and 12 characters long. Functions like `decode`, `decode_exactly`, and validation utilities (e.g., `assert_valid_geohash`) will raise a `ValueError` for invalid geohash formats (e.g., empty string, invalid characters, or excessive length).
fix
Always ensure geohash strings are valid before passing them to decoding or validation functions. You can use `pgh.is_valid_geohash(your_geohash_string)` for programmatic checks.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'Geohash'
Developers often confuse the `pygeohash` library with an older, less maintained `geohash` library or attempt to import the package incorrectly.
fix
Install `pygeohash` using `pip install pygeohash` and import it as `import pygeohash as pgh` or `from pygeohash import encode, decode`.
ValueError: Latitude must be between -90.0 and 90.0 degrees, but got X.
The latitude value provided to the `encode` or `encode_strictly` function is outside the valid range of -90 to 90 degrees.
fix
Ensure the `latitude` argument passed to `pygeohash.encode()` or `pygeohash.encode_strictly()` is a float within the inclusive range of -90.0 to 90.0.
ValueError: Geohash cannot be empty.
The `decode` or related geohash validation functions received an empty string or a string containing invalid characters as the geohash input.
fix
Provide a non-empty string that consists only of valid base32 geohash characters (0-9, b-h, j-k, m-n, p-z) to `pygeohash.decode()` or `pygeohash.assert_valid_geohash()`.
ValueError: Precision must be between 1 and 12, but got X.
The `precision` argument passed to the `encode` function is either not an integer or falls outside the accepted range of 1 to 12 characters.
fix
Set the `precision` argument in `pygeohash.encode()` to an integer value between 1 and 12 (inclusive).
error: command 'gcc' failed with exit status 1
This error occurs during installation (e.g., `pip install pygeohash`) because `pygeohash` relies on a C extension, and the necessary C/C++ compiler (like GCC on Linux/macOS or Visual C++ Build Tools on Windows) is not installed or not configured correctly in the system's PATH.
fix
Install the appropriate C/C++ build tools for your operating system (e.g., `sudo apt-get install build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, or Visual C++ Build Tools on Windows).
Upgrade
Version history
3.3.2latest on PyPI · released Aug 22, 2026
Audit
Dependencies
matplotliboptionalRequired for static geohash visualization functions if `[viz]` extra is installed.
foliumoptionalRequired for interactive geohash map visualizations if `[viz]` extra is installed.
Agent activity
17 hits · last 30 days
node
12
OpenAI (training)
1
Resources
pygeohash — pip install pygeohash · libregistry