com.github.davidmoten.geo

Class GeoHash

java.lang.Object

com.github.davidmoten.geo.GeoHash

public final class GeoHash
extends Object

Utility functions for geohashing.

Author:

dave

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_MAX_HASHES Default maximum number of hashes for covering a bounding box.
static int	MAX_HASH_LENGTH The standard practical maximum legnth for geohashes.

Method Summary

Methods

Modifier and Type	Method and Description
static String	adjacentHash(String hash, Direction direction) Returns the adjacent hash in given Direction.
static String	adjacentHash(String hash, Direction direction, int steps) Returns the adjacent hash N steps in the given Direction.
static String	bottom(String hash) Returns the adjacent hash to the bottom (south).
static Coverage	coverBoundingBox(double topLeftLat, double topLeftLon, double bottomRightLat, double bottomRightLon) Returns the result of coverBoundingBoxMaxHashes with a maxHashes value of GeoHash.DEFAULT_MAX_HASHES.
static Coverage	coverBoundingBox(double topLeftLat, double topLeftLon, double bottomRightLat, double bottomRightLon, int length) Returns the hashes of given length that are required to cover the given bounding box.
static Coverage	coverBoundingBoxMaxHashes(double topLeftLat, double topLeftLon, double bottomRightLat, double bottomRightLon, int maxHashes) Returns the hashes that are required to cover the given bounding box.
static LatLong	decodeHash(String geohash) Returns a latitude,longitude pair as the centre of the given geohash.
static String	encodeHash(double latitude, double longitude) Returns a geohash of length MAX_HASH_LENGTH (12) for the given WGS84 point (latitude,longitude).
static String	encodeHash(double latitude, double longitude, int length) Returns a geohash of given length for the given WGS84 point (latitude,longitude).
static String	encodeHash(LatLong p) Returns a geohash of of length MAX_HASH_LENGTH (12) for the given WGS84 point.
static String	encodeHash(LatLong p, int length) Returns a geohash of given length for the given WGS84 point.
static String	gridAsString(String hash, int fromRight, int fromBottom, int toRight, int toBottom) Returns a String of lines of hashes to represent the relative positions of hashes on a map.
static String	gridAsString(String hash, int fromRight, int fromBottom, int toRight, int toBottom, Set<String> highlightThese) Returns a String of lines of hashes to represent the relative positions of hashes on a map.
static String	gridAsString(String hash, int size, Set<String> highlightThese) Returns a String of lines of hashes to represent the relative positions of hashes on a map.
static boolean	hashContains(String hash, double lat, double lon) Returns true if and only if the bounding box corresponding to the hash contains the given lat and long.
static int	hashLengthToCoverBoundingBox(double topLeftLat, double topLeftLon, double bottomRightLat, double bottomRightLon) Returns the maximum length of hash that covers the bounding box.
static double	heightDegrees(int n) Returns height in degrees of all geohashes of length n.
static String	left(String hash) Returns the adjacent hash to the left (west).
static List<String>	neighbours(String hash) Returns a list of the 8 surrounding hashes for a given hash in order left,right,top,bottom,left-top,left-bottom,right-top,right-bottom.
static String	right(String hash) Returns the adjacent hash to the right (east).
static String	top(String hash) Returns the adjacent hash to the top (north).
static double	widthDegrees(int n) Returns width in degrees of all geohashes of length n.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_HASH_LENGTH

public static final int MAX_HASH_LENGTH

The standard practical maximum legnth for geohashes.

See Also:

Constant Field Values

DEFAULT_MAX_HASHES

public static final int DEFAULT_MAX_HASHES

Default maximum number of hashes for covering a bounding box.

See Also:

Constant Field Values

Method Detail

adjacentHash

public static String adjacentHash(String hash,
                  Direction direction)

Returns the adjacent hash in given Direction. Based on https://github.com/davetroy/geohash-js/blob/master/geohash.js. This method is an improvement on the original js method because it works at borders too (at the poles and the -180,180 longitude boundaries).

Parameters:

hash -

direction -

Returns:

hash of adjacent hash

right

public static String right(String hash)

Returns the adjacent hash to the right (east).

Parameters:

hash - to check

Returns:

hash on right of given hash

left

public static String left(String hash)

Returns the adjacent hash to the left (west).

Parameters:

hash - origin

Returns:

hash on left of origin hash

top

public static String top(String hash)

Returns the adjacent hash to the top (north).

Parameters:

hash - origin

Returns:

hash above origin hash

bottom

public static String bottom(String hash)

Returns the adjacent hash to the bottom (south).

Parameters:

hash - origin

Returns:

hash below (south) of origin hash

adjacentHash

public static String adjacentHash(String hash,
                  Direction direction,
                  int steps)

Returns the adjacent hash N steps in the given Direction. A negative N will use the opposite Direction.

Parameters:

hash - origin hash

direction - to desired hash

steps - number of hashes distance to desired hash

Returns:

hash at position in direction a number of hashes away (steps)

neighbours

public static List<String> neighbours(String hash)

Returns a list of the 8 surrounding hashes for a given hash in order left,right,top,bottom,left-top,left-bottom,right-top,right-bottom.

Parameters:

hash - source

Returns:

a list of neighbour hashes

encodeHash

public static String encodeHash(double latitude,
                double longitude)

Returns a geohash of length MAX_HASH_LENGTH (12) for the given WGS84 point (latitude,longitude).

Parameters:

latitude - in decimal degrees (WGS84)

longitude - in decimal degrees (WGS84)

Returns:

hash at given point of default length

encodeHash

public static String encodeHash(LatLong p,
                int length)

Returns a geohash of given length for the given WGS84 point.

Parameters:

p - point

length - length of hash

Returns:

hash at point of given length

encodeHash

public static String encodeHash(LatLong p)

Returns a geohash of of length MAX_HASH_LENGTH (12) for the given WGS84 point.

Parameters:

p - point

Returns:

hash of default length

encodeHash

public static String encodeHash(double latitude,
                double longitude,
                int length)

Returns a geohash of given length for the given WGS84 point (latitude,longitude). If latitude is not between -90 and 90 throws an IllegalArgumentException.

Parameters:

latitude - in decimal degrees (WGS84)

longitude - in decimal degrees (WGS84)

length - length of desired hash

Returns:

geohash of given length for the given point

decodeHash

public static LatLong decodeHash(String geohash)

Returns a latitude,longitude pair as the centre of the given geohash. Latitude will be between -90 and 90 and longitude between -180 and 180.

Parameters:

geohash -

Returns:

lat long point

hashLengthToCoverBoundingBox

public static int hashLengthToCoverBoundingBox(double topLeftLat,
                               double topLeftLon,
                               double bottomRightLat,
                               double bottomRightLon)

Returns the maximum length of hash that covers the bounding box. If no hash can enclose the bounding box then 0 is returned.

Parameters:

topLeftLat -

topLeftLon -

bottomRightLat -

bottomRightLon -

Returns:

hashContains

public static boolean hashContains(String hash,
                   double lat,
                   double lon)

Returns true if and only if the bounding box corresponding to the hash contains the given lat and long.

Parameters:

hash -

lat -

lon -

Returns:

coverBoundingBox

public static Coverage coverBoundingBox(double topLeftLat,
                        double topLeftLon,
                        double bottomRightLat,
                        double bottomRightLon)

Returns the result of coverBoundingBoxMaxHashes with a maxHashes value of GeoHash.DEFAULT_MAX_HASHES.

Parameters:

topLeftLat -

topLeftLon -

bottomRightLat -

bottomRightLon -

Returns:

coverBoundingBoxMaxHashes

public static Coverage coverBoundingBoxMaxHashes(double topLeftLat,
                                 double topLeftLon,
                                 double bottomRightLat,
                                 double bottomRightLon,
                                 int maxHashes)

Returns the hashes that are required to cover the given bounding box. The maximum length of hash is selected that satisfies the number of hashes returned is less than maxHashes. Returns null if hashes cannot be found satisfying that condition. Maximum hash length returned will be GeoHash.MAX_HASH_LENGTH.

Parameters:

topLeftLat -

topLeftLon -

bottomRightLat -

bottomRightLon -

maxHashes -

Returns:

coverBoundingBox

public static Coverage coverBoundingBox(double topLeftLat,
                        double topLeftLon,
                        double bottomRightLat,
                        double bottomRightLon,
                        int length)

Returns the hashes of given length that are required to cover the given bounding box.

Parameters:

topLeftLat -

topLeftLon -

bottomRightLat -

bottomRightLon -

length -

Returns:

heightDegrees

public static double heightDegrees(int n)

Returns height in degrees of all geohashes of length n. Results are deterministic and cached to increase performance.

Parameters:

n -

Returns:

widthDegrees

public static double widthDegrees(int n)

Returns width in degrees of all geohashes of length n. Results are deterministic and cached to increase performance (might be unnecessary, have not benchmarked).

Parameters:

n -

Returns:

gridAsString

public static String gridAsString(String hash,
                  int size,
                  Set<String> highlightThese)

Returns a String of lines of hashes to represent the relative positions of hashes on a map. The grid is of height and width 2*size centred around the given hash. Highlighted hashes are displayed in upper case. For example, gridToString("dr",1,Collections.emptySet()) returns:

 f0 f2 f8 
 dp dr dx 
 dn dq dw
 

Parameters:

hash -

size -

highlightThese -

Returns:

gridAsString

public static String gridAsString(String hash,
                  int fromRight,
                  int fromBottom,
                  int toRight,
                  int toBottom)

Returns a String of lines of hashes to represent the relative positions of hashes on a map.

Parameters:

hash -

fromRight - top left of the grid in hashes to the right (can be negative).

fromBottom - top left of the grid in hashes to the bottom (can be negative).

toRight - bottom righth of the grid in hashes to the bottom (can be negative).

toBottom - bottom right of the grid in hashes to the bottom (can be negative).

Returns:

gridAsString

public static String gridAsString(String hash,
                  int fromRight,
                  int fromBottom,
                  int toRight,
                  int toBottom,
                  Set<String> highlightThese)

Returns a String of lines of hashes to represent the relative positions of hashes on a map. Highlighted hashes are displayed in upper case. For example, gridToString("dr",-1,-1,1,1,Sets.newHashSet("f2","f8")) returns:

 f0 F2 F8 
 dp dr dx 
 dn dq dw
 

Parameters:

hash -

fromRight - top left of the grid in hashes to the right (can be negative).

fromBottom - top left of the grid in hashes to the bottom (can be negative).

toRight - bottom righth of the grid in hashes to the bottom (can be negative).

toBottom - bottom right of the grid in hashes to the bottom (can be negative).

highlightThese -

Returns: