pygeodesy.geohash

Package pygeodesy :: Module geohash |
[frames] | no frames]

# Module geohash

Gustavo Niemeyer’s Geohash.

Class Geohash and several functions to encode, decode and inspect `geohashes` and optional Geohashed caches.

Originally transcoded from JavaScript originals by (C) Chris Veness 2011-2024 and published under the same MIT Licence**, see Geohashes.

See Also: Geohash, Karney's C++ Geohash, geohash, pygeohash and geohash-js.

Version: 25.09.16

Classes
| Geohash Geohash class, a named `str`.
| Geohashed A cache of en- and decoded geohashes of one precision.
| GeohashError Geohash encode, decode or other Geohash issue.
| Neighbors8Dict 8-Dict `(N, NE, E, SE, S, SW, W, NW)` of Geohashes, providing key and attribute access to the items.
| Resolutions2Tuple 2-Tuple `(res1, res2)` with the primary (longitudinal) and secondary (latitudinal) resolution, both in `degrees`.
| Sizes3Tuple 3-Tuple `(height, width, radius)` with latitudinal `height`, longitudinal `width` and area `radius`, all in `meter`.

Functions
bounds(geohash, LatLon=None, **LatLon_kwds) Returns the lower-left SW and upper-right NE corners of a geohash. |
decode(geohash) Decode a geohash to lat-/longitude of the (approximate centre of) geohash cell to reasonable precision. |
decode2(geohash, LatLon=None, **LatLon_kwds) Decode a geohash to lat-/longitude of the (approximate center of) geohash cell to reasonable precision. |
decode_error(geohash) DEPRECATED on 2024.07.28, use geohash.decode_error2. |
decode_error2(geohash) Return the lat- and longitude decoding error for a geohash. |
distance_(geohash1, geohash2) Estimate the distance between two geohash (from the cell sizes). |
encode(lat, lon, precision=None, eps=2.220446049250313e-16) Encode a lat-/longitude as a `geohash`, either to the specified precision or if not provided, to an inferred precision. |
equirectangular4(geohash1, geohash2, radius=6371008.771415) Approximate the distance between two geohashes using the pygeodesy.equirectangular formula. |
euclidean_(geohash1, geohash2, **radius_adjust_wrap) Approximate the distance between two geohashes using the pygeodesy.euclidean formula. |
haversine_(geohash1, geohash2, **radius_wrap) Compute the great-circle distance between two geohashes using the pygeodesy.haversine formula. |
neighbors(geohash) Return the Geohashes for all 8 adjacent cells. |
precision(res1, res2=None) Determine the Geohash precisions to meet a or both given (geographic) resolutions. |
resolution2(prec1, prec2=None) Determine the (geographic) resolutions of given Geohash precisions. |
sizes(geohash) DEPRECATED on 2024.07.28, use function pygeodesy.geohash.sizes3. |
sizes3(geohash) Return the lat-, longitudinal and radial size of this Geohash cell. |
vincentys_(geohash1, geohash2, **radius_wrap) Compute the distance between two geohashes using the pygeodesy.vincentys formula. |

Variables
| __all__ = `_ALL_LAZY.geohash`

Function Details

### bounds (geohash, LatLon=None, **LatLon_kwds) |
Returns the lower-left SW and upper-right NE corners of a geohash. Arguments: `geohash` - To be "bound" (Geohash). `LatLon` - Optional class to return the bounds (`LatLon`) or `None`. `LatLon_kwds` - Optional, additional `LatLon` keyword arguments, ignored if `LatLon is None`. Returns: A Bounds2Tuple`(latlonSW, latlonNE)`, each a `LatLon` or if `LatLon is None`, a Bounds4Tuple`(latS, lonW, latN, lonE)`. Raises: `TypeError` - The `geohash` is not a Geohash, `LatLon` or `str` or invalid `LatLon` or invalid `LatLon_kwds`. `GeohashError` - Invalid or `null` `geohash`.

### decode (geohash) |
Decode a geohash to lat-/longitude of the (approximate centre of) geohash cell to reasonable precision. Arguments: `geohash` - To be decoded (Geohash). Returns: 2-Tuple `(latStr, lonStr)`, both `str`. Raises: `TypeError` - The `geohash` is not a Geohash, `LatLon` or `str`. `GeohashError` - Invalid or null `geohash`.

### decode2 (geohash, LatLon=None, **LatLon_kwds) |
Decode a geohash to lat-/longitude of the (approximate center of) geohash cell to reasonable precision. Arguments: `geohash` - To be decoded (Geohash). `LatLon` - Optional class to return the location (`LatLon`) or `None`. `LatLon_kwds` - Optional, addtional `LatLon` keyword arguments, ignored if `LatLon is None`. Returns: LatLon2Tuple`(lat, lon)`, both `degrees` if `LatLon is None`, otherwise a `LatLon` instance. Raises: `TypeError` - The `geohash` is not a Geohash, `LatLon` or `str`. `GeohashError` - Invalid or null `geohash`.

### decode_error (geohash) |
DEPRECATED on 2024.07.28, use geohash.decode_error2. Decorators: `@deprecated_function`

### decode_error2 (geohash) |
Return the lat- and longitude decoding error for a geohash. Arguments: `geohash` - To be decoded (Geohash). Returns: A LatLon2Tuple`(lat, lon)` with the lat- and longitudinal errors in (`degrees`). Raises: `TypeError` - The `geohash` is not a Geohash, `LatLon` or `str`. `GeohashError` - Invalid or null `geohash`.

### distance_ (geohash1, geohash2) |
Estimate the distance between two geohash (from the cell sizes). Arguments: `geohash1` - First geohash (Geohash, `LatLon` or `str`). `geohash2` - Second geohash (Geohash, `LatLon` or `str`). Returns: Approximate distance (`meter`). Raises: `TypeError` - If `geohash1` or `geohash2` is not a Geohash, `LatLon` or `str`.

### encode (lat, lon, precision=None, eps=2.220446049250313e-16) |
Encode a lat-/longitude as a `geohash`, either to the specified precision or if not provided, to an inferred precision. Arguments: `lat` - Latitude (`degrees90`). `lon` - Longitude (`degrees180`). `precision` - The desired geohash length (`int` 1..12) or `None` or `0` for inferred. `eps` - Optional inference tolerance (`degrees`), ignored if `precision` is not `None` or `0`. Returns: The `geohash` (`str`). Raises: `GeohashError` - Invalid `lat`, `lon` or `precision`.

### equirectangular4 (geohash1, geohash2, radius=6371008.771415) |
Approximate the distance between two geohashes using the pygeodesy.equirectangular formula. Arguments: `geohash1` - First geohash (Geohash, `LatLon` or `str`). `geohash2` - Second geohash (Geohash, `LatLon` or `str`). `radius` - Mean earth radius (`meter`) or `None`, see method Geohash.equirectangularTo. Returns: Approximate distance (`meter`, same units as `radius`), see method Geohash.equirectangularTo. Raises: `TypeError` - If `geohash1` or `geohash2` is not a Geohash, `LatLon` or `str`.

### euclidean_ (geohash1, geohash2, **radius_adjust_wrap) |
Approximate the distance between two geohashes using the pygeodesy.euclidean formula. Arguments: `geohash1` - First geohash (Geohash, `LatLon` or `str`). `geohash2` - Second geohash (Geohash, `LatLon` or `str`). `radius_adjust_wrap` - Optional keyword arguments for function pygeodesy.euclidean. Returns: Approximate distance (`meter`, same units as `radius`). Raises: `TypeError` - If `geohash1` or `geohash2` is not a Geohash, `LatLon` or `str`.

### haversine_ (geohash1, geohash2, **radius_wrap) |
Compute the great-circle distance between two geohashes using the pygeodesy.haversine formula. Arguments: `geohash1` - First geohash (Geohash, `LatLon` or `str`). `geohash2` - Second geohash (Geohash, `LatLon` or `str`). `radius_wrap` - Optional keyword arguments for function pygeodesy.haversine. Returns: Great-circle distance (`meter`, same units as `radius`). Raises: `TypeError` - If `geohash1` or `geohash2` is not a Geohash, `LatLon` or `str`.

### neighbors (geohash) |
Return the Geohashes for all 8 adjacent cells. Arguments: `geohash` - Cell for which neighbors are requested (Geohash or `str`). Returns: A Neighbors8Dict`(N, NE, E, SE, S, SW, W, NW)` of Geohashes. Raises: `TypeError` - The `geohash` is not a Geohash, `LatLon` or `str`.

### precision (res1, res2=None) |
Determine the Geohash precisions to meet a or both given (geographic) resolutions. Arguments: `res1` - The required primary (longitudinal) resolution (`degrees`). `res2` - Optional, required secondary (latitudinal) resolution (`degrees`). Returns: The Geohash precision or length (`int`, 1..12). Raises: `GeohashError` - Invalid `res1` or `res2`. See Also: C++ class Geohash.

### resolution2 (prec1, prec2=None) |
Determine the (geographic) resolutions of given Geohash precisions. Arguments: `prec1` - The given primary (longitudinal) precision (`int` 1..12). `prec2` - Optional, secondary (latitudinal) precision (`int` 1..12). Returns: Resolutions2Tuple`(res1, res2)` with the (geographic) resolutions in `degrees`, where `res2 is res1` if no `prec2` is given. Raises: `GeohashError` - Invalid `prec1` or `prec2`. See Also: Karney's C++ class Geohash.

### sizes (geohash) |
DEPRECATED on 2024.07.28, use function pygeodesy.geohash.sizes3. Decorators: `@deprecated_function`

### sizes3 (geohash) |
Return the lat-, longitudinal and radial size of this Geohash cell. Arguments: `geohash` - Cell for which size are required (Geohash or `str`). Returns: A Sizes3Tuple`(height, width, radius)`, all `meter`. Raises: `TypeError` - The `geohash` is not a Geohash, `LatLon` or `str`.

### vincentys_ (geohash1, geohash2, **radius_wrap) |
Compute the distance between two geohashes using the pygeodesy.vincentys formula. Arguments: `geohash1` - First geohash (Geohash, `LatLon` or `str`). `geohash2` - Second geohash (Geohash, `LatLon` or `str`). `radius_wrap` - Optional keyword arguments for function pygeodesy.vincentys. Returns: Distance (`meter`, same units as `radius`). Raises: `TypeError` - If `geohash1` or `geohash2` is not a Geohash, `LatLon` or `str`.