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.06.23

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 equirectangular formula. |
haversine_(geohash1, geohash2, radius=6371008.77141) Compute the great-circle distance between two geohashes using the 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 keyword arguments for `LatLon`, ignored if `LatLon=None`. Returns: A Bounds2Tuple`(latlonSW, latlonNE)` of `LatLon`s 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 keyword arguments for `LatLon`, ignored if `LatLon=None`. Returns: LatLon2Tuple`(lat, lon)`, both `degrees` if `LatLon=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: `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'

### equirectangular_ (geohash1, geohash2, radius=6371008.77141) |
Approximate the distance between two geohashes using the 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 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: `GeohashError` - Invalid `res1` or `res2`. 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: `GeohashError` - Invalid `prec1` or `prec2`. 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`.