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

Module geohash

Class Geohash 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**.

More details at http://www.movable-type.co.uk/scripts/geohash.html. See also http://github.com/vinsci/geohash, http://github.com/davetroy/geohash-js and http://pypi.python.org/pypi/pygeohash.


Version: 17.06.04

Classes
  Geohash
Geohash class, sub-class of str.
Functions
 
bounds(geohash)
Returns the SW and NE lat-/longitude bounds 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 or an automatically evaluated precision.
 
neighbors(geohash)
Return the Geohashes for all 8 adjacent cells.
 
sizes(geohash)
Return the lat- and longitudinal size of this Geohash cell.
Function Details

bounds(geohash)

 

Returns the SW and NE lat-/longitude bounds of a geohash.

Returns:
4-Tuple (latS, lonW, latN, lonE) in (degrees).
Raises:
  • TypeError - The geohash is not a Geohash, LatLon or str.
  • ValueError - 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 (strings).
Raises:
  • TypeError - The geohash is not a Geohash, LatLon or str.
  • ValueError - 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:
2-Tuple (latErr, lonErr) in (degrees).
Raises:
  • TypeError - The geohash is not a Geohash, LatLon or str.
  • ValueError - 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 - A geohash 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 earth radius (meter) or None.
Returns:
Approximate distance (meter, same units as radius).
Raises:
  • TypeError - A geohash 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 earth radius (meter).
Returns:
Great-circle distance (meter, same units as radius).
Raises:
  • TypeError - A geohash 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 or an automatically evaluated precision.

Parameters:
  • lat - Latitude in degrees (scalar).
  • lon - Longitude in degrees (scalar).
  • precision - Desired geohash length (integer).
Returns:
The geohash (string).
Raises:
  • ValueError - Invalid lat, lon or precision.

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 required (Geohash or str).
Returns:
Neighbors (dict(N=, NE=, E= ..., SW=) of Geohashes).
Raises:
  • TypeError - The geohash is not a Geohash, LatLon or str.

JS name: neighbours.

sizes(geohash)

 

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

Parameters:
  • geohash - Cell for which size are required (Geohash or str).
Returns:
2-Tuple (latHeight, lonWidth) in (meter).
Raises:
  • TypeError - The geohash is not a Geohash, LatLon or str.