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

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: `GeohashError` - 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 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`.