Geohash

from honeybees.library.geohash import plot_geohash_shifts
plot_geohash_shifts(bits=31)
../_images/geohash_31bits.svg 
from honeybees.library.geohash import plot_geohash_shifts
plot_geohash_shifts(bits=32)
../_images/geohash_32bits.svg

Submodule that implements several functions for geohashing. Inspired by https://www.factual.com/blog/how-geohashes-work/.

decode(gh, bits, minx=-180, maxx=180, miny=-90, maxy=90)[source]

Decodes a geohashes into x/y pair for given precision in bits.

Parameters:

  • gh (int64) – Geohash

  • bits (int) – Precision for geohash.

  • minx (Union[int, float]) – Minimum x-value of the entire relevant space.

  • maxx (Union[int, float]) – Maximum x-value of the entire relevant space.

  • miny (Union[int, float]) – Minimum y-value of the entire relevant space.

  • miny – Maximum y-value of the entire relevant space.

Returns:

  • x – Decoded x-value

  • y – Decoded y-value

Return type:

tuple[float, float]

encode(x, y, minx=-180, maxx=180, miny=-90, maxy=90)[source]

Geohashes a x/y pair.

Parameters:

  • x (float) – x-value.

  • y (float) – y-value.

  • minx (Union[int, float]) – Minimum x-value of the entire relevant space.

  • maxx (Union[int, float]) – Maximum x-value of the entire relevant space.

  • miny (Union[int, float]) – Minimum y-value of the entire relevant space.

  • miny – Maximum y-value of the entire relevant space.

Returns:

geohash – Geohash for x/y pair.

encode_locations(locations, minx, maxx, miny, maxy)[source]

Geohash 2d-array of locations.

Parameters:

  • locations (ndarray) – 2d array of locations x and y locations.

  • minx (float) – Minimum x-value of the entire relevant space.

  • maxx (float) – Maximum x-value of the entire relevant space.

  • miny (float) – Minimum y-value of the entire relevant space.

  • miny – Maximum y-value of the entire relevant space.

Returns:

hashcodes – Geohash codes array for all locations.

Return type:

ndarray

encode_precision(x, y, bits, minx=-180, maxx=180, miny=-90, maxy=90)[source]

Geohashes a x/y pair for given precision in bits.

Parameters:

  • x (float) – x-value.

  • y (float) – y-value.

  • bits (int) – Precision for geohash.

  • minx (Union[int, float]) – Minimum x-value of the entire relevant space.

  • maxx (Union[int, float]) – Maximum x-value of the entire relevant space.

  • miny (Union[int, float]) – Minimum y-value of the entire relevant space.

  • miny – Maximum y-value of the entire relevant space.

Returns:

geohash – Geohash for x/y pair.

Return type:

int64

get_precision_tag(bits)[source]

Get a 64-bit integer that can be ORed with a geohash. This is done by setting the most-significant bit to 1.

Parameters:

bits (int) – Number of bits wanted for resulting geohash.

Returns:

precision_tag – 64-bit integer that can be ORed with geohash to set precision.

Return type:

int64

get_shifts(x, y, radius, n_bits, minx=-180, maxx=180, miny=-90, maxy=90, grid='longlat')[source]

Gets the geohash shifts required to cover a circle (x, y) with given radius for given number of bits.

Parameters:

  • x (float) – x-coordinate of circle center.

  • y (float) – y-coordinate of circle center.

  • radius (Union[float, int]) – Circle radius.

  • bits – Precision for geohash.

  • minx (Union[float, int]) – Minimum x-value of the entire relevant space.

  • maxx (Union[float, int]) – Maximum x-value of the entire relevant space.

  • miny (Union[float, int]) – Minimum y-value of the entire relevant space.

  • miny – Maximum y-value of the entire relevant space.

  • grid – The type of grid. Choose from longlat and orthogonal.

Returns:

shifts – Geohash shifts required to cover circle for given number of bits.

Return type:

ndarray

plot_geohash_shifts(lon=4.8945, lat=52.3667, radius=5000, bits=31, show=True)[source]

This function can be used to explore how geohashes can be used to cover a given circle. There is a trade-off between precision of the geohash, speed and how well the shifts represent a circle. This function plots a circle and geohash windows required to cover the circle.

Parameters:

  • lon (float) – Longitude of circle centre.

  • lat (float) – Latitude of cirle centre.

  • radius (Union[float, int]) – Radius of circle.

  • bits (int) – Number of geohash bits used.

  • show (bool) – Whether to show the resulting plot.

Return type:

None

reduce_precision(geohashes, bits, inplace=False)[source]

Reduces the precision of input geohashes.

Parameters:

  • geohashes (ndarray) – Array of geohashes.

  • bits (int) – Required number of bits for output geohashes

  • inplace (bool) – If true, the operation is executed in place, otherwise a new array is returned.

shift(gh, bits, dx, dy)[source]

Shifts a geohash by number of windows in given x and y-direction.

Parameters:

  • gh (int64) – Geohash

  • bits (int) – Precision for geohash.

  • dx (int) – Number of windows to shift in x-direction. Can be negative.

  • negative. (dy. Number of windows to shift in y-direction. Can be)

Returns:

gh – Shifted geohash.

shift_multiple(gh, bits, shifts)[source]

Shifts a geohash by number of windows in given x and y-directions.

Parameters:

  • gh (int64) – Geohash

  • bits (int) – Precision for geohash.

  • shifts (ndarray) – 2-dimensional array with number of windows too shift in x- and y-direction. Can be negative. The first dimension represents a number of shifts, while the second dimension is the x- and y-shift.

Returns:

ghs – Array of shifted geohashes.

Return type:

ndarray

unwiden(bitstring)[source]

To unpack a geohash in its x and y pair, the inverse of widen needs to happen. This function removes a bit from the left of each other bit.

Parameters:

bitstring (int64) – Widened bitstring.

Returns:

unwidened_bitstring – Unwidened bitstring.

Return type:

int64

widen(bitstring)[source]

To interleave the x and y pair of the geohash we widen the bit-values by inserting a 0 value to the left of each of the bits.

Parameters:

bitstring (int64) – Geohash of x or y only.

Returns:

interleaved_bitstring – Interleaved geohash of x or y.

Return type:

int64

window(bits, minx=-180, maxx=180, miny=-90, maxy=90)[source]

Gets the width and height of a geohash window for given precision and area size.

Parameters:

  • bits (int) – Precision for geohash.

  • minx (Union[int, float]) – Minimum x-value of the entire relevant space.

  • maxx (Union[int, float]) – Maximum x-value of the entire relevant space.

  • miny (Union[int, float]) – Minimum y-value of the entire relevant space.

  • miny – Maximum y-value of the entire relevant space.

Returns:

  • window_width – Width of geohash window.

  • window_height – Height of geohash window.

Return type:

tuple[float, float]