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 DEFAULT_MAX_HASHES (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 DEFAULT_MAX_HASHES (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

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

MAX_HASH_LENGTH

public static final int MAX_HASH_LENGTH

The standard practical maximum legnth for geohashes.

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:

right

public static String right(String hash)

Returns the adjacent hash to the right (east).

Parameters:

hash -

Returns:

left

public static String left(String hash)

Returns the adjacent hash to the left (west).

Parameters:

hash -

Returns:

top

public static String top(String hash)

Returns the adjacent hash to the top (north).

Parameters:

hash -

Returns:

bottom

public static String bottom(String hash)

Returns the adjacent hash to the bottom (south).

Parameters:

hash -

Returns:

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 -

direction -

steps -

Returns:

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 -

Returns:

encodeHash

public static String encodeHash(double latitude,
                double longitude)

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

Parameters:

latitude - in decimal degrees (WGS84)

longitude - in decimal degrees (WGS84)

Returns:

encodeHash

public static String encodeHash(LatLong p,
                int length)

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

Parameters:

p -

length -

Returns:

encodeHash

public static String encodeHash(LatLong p)

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

Parameters:

p -

Returns:

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)

Returns:

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:

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: