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**, see Geohashes.

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

Version: 19.01.02

Classes
| Geohash Geohash class, sub-class of str.

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 or if not given, 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, 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 use to return bounds (`LatLon`) or `None`. `kwds` - Optional keyword arguments for LatLon. Returns: 4-Tuple (S, W, N, E) of bounds lat- and longitudes in (`degrees`) if LatLon is `None` otherwise 2-tuple (LatLon(S, W), LatLon(N, E) of the bounds. 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 (`str`). 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, mean 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, mean 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 if not given, an automatically evaluated precision. Parameters: `lat` - Latitude (`degrees`). `lon` - Longitude (`degrees`). `precision` - Optional, desired geohash length (`int`). Returns: The geohash (`str`). 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`.