Package pygeodesy :: Module geohash

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: 24.10.12

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.