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

Module geohash

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

Transcribed 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: 19.10.12

Classes
  GeohashError
Geohash encode, decode or other Geohash issue.
  Geohash
Geohash class, a _NamedStr.
Functions
 
bounds(geohash, LatLon=None, **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.
 
decode_error(geohash)
Return the relative lat-/longitude decoding errors for this geohash.
 
distance1(geohash1, geohash2)
Estimate the distance between two geohash (from the cell sizes).
 
distance2(geohash1, geohash2, radius=6371008.77141)
Approximate the distance between two geohashes (with Pythagoras' theorem).
 
distance3(geohash1, geohash2, radius=6371008.77141)
Compute the great-circle distance between two geohashes (using the Haversine formula).
 
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.
 
neighbors(geohash)
Return the Geohashes for all 8 adjacent cells.
 
precision(res1, res2=None)
Determine the Geohash precisions to meet a 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.
Function Details

bounds(geohash, LatLon=None, **kwds)

 

Returns the lower-left SW and upper-right NE corners of a geohash.

Parameters:
  • geohash - To be bound (Geohash).
  • LatLon - Optional (sub-)class to return the bounds (LatLon) or None.
  • kwds - Optional keyword arguments for LatLon.
Returns:
A Bounds2Tuple(latlonSW, latlonNE) as LatLon or a Bounds4Tuple(latS, lonW, latN, lonE) if LatLon is None.
Raises:
  • TypeError - The geohash is not a Geohash, LatLon or str.
  • 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.

Parameters:
  • geohash - To be decoded (Geohash).
Returns:
2-Tuple "(latStr, lonStr)" in (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

decode_error(geohash)

 

Return the relative lat-/longitude decoding errors for this geohash.

Parameters:
  • 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

distance1(geohash1, geohash2)

 

Estimate the distance between two geohash (from the cell sizes).

Parameters:
  • geohash1 - First geohash (Geohash).
  • geohash2 - Second geohash (Geohash).
Returns:
Approximate distance (meter).
Raises:
  • TypeError - If geohash1 or geohash2 is not a Geohash, LatLon or str.

Example:

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

distance2(geohash1, geohash2, radius=6371008.77141)

 

Approximate the distance between two geohashes (with Pythagoras' theorem).

Parameters:
  • geohash1 - First geohash (Geohash).
  • geohash2 - Second geohash (Geohash).
  • radius - Optional, 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.distance2('u120fxwsh', 'u120fxws0')  # 19.0879

distance3(geohash1, geohash2, radius=6371008.77141)

 

Compute the great-circle distance between two geohashes (using the Haversine formula).

Parameters:
  • geohash1 - First geohash (Geohash).
  • geohash2 - Second geohash (Geohash).
  • radius - Optional, 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.distance3('u120fxwsh', 'u120fxws0')  # 11.6978

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.

Parameters:
  • 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'

neighbors(geohash)

 

Return the Geohashes for all 8 adjacent cells.

Parameters:
  • 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 given (geographic) resolutions.

Parameters:
  • res1 - The required, primary (longitudinal) resolution (degrees).
  • res2 - Optional, required, secondary (latitudinal resolution (degrees).
Returns:
The Geohash precision or length (int 1..12).

See Also: C++ class Geohash.

resolution2(prec1, prec2=None)

 

Determine the (geographic) resolutions of given Geohash precisions.

Parameters:
  • prec1 - The given primary (longitudinal) precision (int 1..12).
  • prec2 - Optional, secondary (latitudinal) precision (int 1..12).
Returns:
2-Tuple (res1, res2) with the (geographic) resolutions (degrees) where res2 is res1 if no prec2 is given.

See Also: C++ class Geohash.

sizes(geohash)

 

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

Parameters:
  • 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.