Package pygeodesy3 :: Package grids :: Module geohash

Module geohash

Geohash en-/decoding.

Classes Geohash and GeohashError and several functions to encode, decode and inspect geohashes.

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

See also Geohash, Geohash, PyGeohash and Geohash-Javascript.

Version: 24.02.20

Classes
	Geohash Geohash class, a named `str`.
	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`.

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)
Return the relative lat-/longitude decoding errors for this geohash.

distance_(geohash1, geohash2)
Estimate the distance between two geohash (from the cell sizes).

encode(lat, lon, precision=None)
Encode a lat-/longitude as a geohash, either to the specified precision or if not provided, to an automatically evaluated precision.

equirectangular_(geohash1, geohash2, radius=6371008.771415)
Approximate the distance between two geohashes using the equirectangular formula.

euclidean_(geohash1, geohash2, **radius_adjust_wrap)
Approximate the distance between two geohashes using the euclidean formula.

haversine_(geohash1, geohash2, **radius_wrap)
Compute the distance between two geohashes using the 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)
Return the lat- and longitudinal size of this Geohash cell.

vincentys_(geohash1, geohash2, **radius_wrap)
Compute the distance between two geohashes using the vincentys formula.

Variables
	__all__ = `_ALL_LAZY.grids_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) of LatLons 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)

Return the relative lat-/longitude decoding errors for this 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)

Encode a lat-/longitude as a geohash, either to the specified precision or if not provided, to an automatically evaluated precision.

Arguments:

lat - Latitude (degrees).
lon - Longitude (degrees).
precision - Optional, the desired geohash length (int 1..12).

Returns:

The geohash (str).

Raises:

GeohashError - Invalid lat, lon or precision.

equirectangular_ (geohash1, geohash2, radius=6371008.771415)

Approximate the distance between two geohashes using the 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 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 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 distance between two geohashes using the haversine formula.

Arguments:

geohash1 - First geohash (Geohash, LatLon or str).
geohash2 - Second geohash (Geohash, LatLon or str).
radius_wrap - Optional keyword arguments for function haversine.

Returns:

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 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)

Return the lat- and longitudinal size of this Geohash cell.

Arguments:

geohash - Cell for which size are required (Geohash or str).

Returns:

A LatLon2Tuple(lat, lon) with the latitudinal height and longitudinal width in (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 vincentys formula.

Arguments:

geohash1 - First geohash (Geohash, LatLon or str).
geohash2 - Second geohash (Geohash, LatLon or str).
radius_wrap - Optional keyword arguments for function vincentys.

Returns:

Distance (meter, same units as radius).

Raises:

TypeError - If geohash1 or geohash2 is not a Geohash, LatLon or str.