com.javadocmd.simplelatlng
Class Geohasher

java.lang.Object
  com.javadocmd.simplelatlng.Geohasher

public class Geohasher
extends Object

Implements the Geohash algorithm for hashing latitude and longitude points. Note: this implementation is only "stable" with 12-character hashes. Decoding "s" and re-hashing the result yields "t40000000000". Decoding and re-hashing "t40000000000" yields the same. 12 characters was chosen because this gives us precision up to one-millionth of a degree, like the rest of this library.

Author:

Tyler Coles

Nested Class Summary

protected static class

Geohasher.BitStore Specialization of BitSet to actually keep track of the number of bits that are being usefully employed, regardless of whether or not they are 1 or 0.

Field Summary

protected static BigDecimal[]	LAT_BIT_VALUES
protected static BigDecimal[]	LNG_BIT_VALUES
static int	PRECISION Number of hash characters supported.

Constructor Summary

Geohasher()

Method Summary

protected static double	bitsToDouble(BitSet bits, BigDecimal[] bitValues) Converts the set of bits representing a single value to double.
protected static String	bitsToHash(BitSet bits) Encodes an interleaved set of bits to its base-32 geohash.
static LatLng	decode(String hash) Decodes a geohash string to its LatLng equivalent.
protected static BitSet[]	deInterleave(BitSet bits) De-interleaves a series of bits.
protected static BitSet	doubleToBits(double value, double maxRange) Converts a double value to its bit representation in the geohash specification.
static String	hash(LatLng point) Geohashes a latitude and longitude.
protected static BitSet	hashToBits(String hash) Converts a hash string into a string of bits.
protected static BitSet	interleave(BitSet evenBits, BitSet oddBits) Interleaves two sets of bits.

Methods inherited from class java.lang.Object

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

Field Detail

PRECISION

public static final int PRECISION

Number of hash characters supported.

Translates to binary bits per value by the formula:
BITS = ((PRECISION * 5) / 2) + PRECISION % 2.

BITS in turn translates to numerical precision by the formula:
LATITUDE_ERROR = 90.0 / (2 ^ (BITS + 1))
LONGITUDE_ERROR = 180.0 / (2 ^ (BITS + 1))

See Also:

Constant Field Values

LAT_BIT_VALUES

protected static final BigDecimal[] LAT_BIT_VALUES

LNG_BIT_VALUES

protected static final BigDecimal[] LNG_BIT_VALUES

Constructor Detail

Geohasher

public Geohasher()

Method Detail

decode

public static LatLng decode(String hash)

Decodes a geohash string to its LatLng equivalent.

Parameters:

hash - the geohash string of any precision, although LatLng will still not become more precise than its settings.

Returns:

the decoded point.

hashToBits

protected static BitSet hashToBits(String hash)

Converts a hash string into a string of bits.

deInterleave

protected static BitSet[] deInterleave(BitSet bits)

De-interleaves a series of bits.

Parameters:

bits - the bits to de-interleave.

Returns:

two bit sets: [0] = even bits, [1] = odd bits

bitsToDouble

protected static double bitsToDouble(BitSet bits,
                                     BigDecimal[] bitValues)

Converts the set of bits representing a single value to double. The bit set passed into this function should already be de-interleaved.

Parameters:

bits - the bits for this value.

bitValues - the correct set of pre-computed bit-values to use for the particular value we are decoding: latitude or longitude.

Returns:

the value.

hash

public static String hash(LatLng point)

Geohashes a latitude and longitude.

Parameters:

point - the point to hash.

Returns:

the hash string to the set character precision: PRECISION.

bitsToHash

protected static String bitsToHash(BitSet bits)

Encodes an interleaved set of bits to its base-32 geohash.

Parameters:

bits - the set of bits to encode.

Returns:

the encoded string.

interleave

protected static BitSet interleave(BitSet evenBits,
                                   BitSet oddBits)

Interleaves two sets of bits.

Parameters:

evenBits - the bits to use for even bits. (0, 2, 4,...)

oddBits - the bits to use for odd bits. (1, 3, 5,...)

Returns:

the interleaved bits.

doubleToBits

protected static BitSet doubleToBits(double value,
                                     double maxRange)

Converts a double value to its bit representation in the geohash specification.

Parameters:

value - the value to encode.

maxRange - the max range for the particular value we are encoding: latitude = 90.0, longitude = 180.0.

Returns:

the bit set for this value.