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

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

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 centre 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.77141)
Approximate the distance between two geohashes using the pygeodesy.equirectangular formula.
 
haversine_(geohash1, geohash2, radius=6371008.77141)
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)
Return the lat- and longitudinal size of this Geohash cell.
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) 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.

Example:

>>> geohash.bounds('u120fxw')  #  52.20428467, 0.11810303, 52.20565796, 0.11947632
>>> geohash.decode('u120fxw')  # '52.205',    '0.1188'

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.

Example:

>>> geohash.decode('u120fxw')  # '52.205', '0.1188'
>>> geohash.decode('sunny')  # '23.708', '42.473'  Saudi Arabia
>>> geohash.decode('fur')  # '69.6', '-45.7'  Greenland
>>> geohash.decode('reef')  # '-24.87', '162.95'  Coral Sea
>>> geohash.decode('geek')  # '65.48', '-17.75'  Iceland

decode2 (geohash, LatLon=None, **LatLon_kwds)

 

Decode a geohash to lat-/longitude of the (approximate centre 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.

Example:

>>> geohash.decode_error('u120fxw')  # 0.00068665, 0.00068665
>>> geohash.decode_error('fur')  # 0.703125, 0.703125
>>> geohash.decode_error('fu')  # 2.8125, 5.625
>>> geohash.decode_error('f')  # 22.5, 22.5

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.

Example:

>>> geohash.distance_('u120fxwsh', 'u120fxws0')  # 15.239

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:

Example:

>>> geohash.encode(52.205, 0.119,   7)  # 'u120fxw'
>>> geohash.encode(52.205, 0.119,  12)  # 'u120fxwshvkg'
>>> geohash.encode(52.205, 0.1188, 12)  # 'u120fxws0jre'
>>> geohash.encode(52.205, 0.1188)      # 'u120fxw'
>>> geohash.encode(     0, 0)           # 's00000000000'

equirectangular_ (geohash1, geohash2, radius=6371008.77141)

 

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.
Returns:
Approximate distance (meter, same units as radius).
Raises:
  • TypeError - If geohash1 or geohash2 is not a Geohash, LatLon or str.

Example:

>>> geohash.equirectangular_('u120fxwsh', 'u120fxws0')  # 19.0879

haversine_ (geohash1, geohash2, radius=6371008.77141)

 

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 - Mean earth radius (meter).
Returns:
Great-circle distance (meter, same units as radius).
Raises:
  • TypeError - If geohash1 or geohash2 is not a Geohash, LatLon or str.

Example:

>>> geohash.haversine_('u120fxwsh', 'u120fxws0')  # 11.6978

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.

JS name: neighbours.

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:

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:

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.