Home

SimpleLatLng is a Java implementation of common latitude and longitude calculations. It is aimed at being quick to learn and easy to use for basic geo-spatial needs. You shouldn't need to write, test, and debug your own geo-spatial tools when this is a fairly common need in many applications. We have purposefully left out some bells and whistles to keep things streamlined so that you can include this in your project and get on with the work you'd rather be doing.

Getting Started

SimpleLatLng is written and compiled to Java 6 (prior to v1.4.0; as of v1.4.0 the target is Java 8). After you have included the library jar in your project or added it as a dependency in your build tool of choice, you can create a point in latitude and longitude as follows:

LatLng point = new LatLng(33.123123, -127.123123);

The important thing to note is that all latitudes and longitudes are handled in degrees using the convention that positive latitudes are in the northern hemisphere and positive longitudes are east of the Prime Meridian.

This library generally considers degree measurements to the millionth (0.000001) degree. So 33.0000010 is equal to 33.0000015, but not equal to 33.0000020. This yields a resolution of around 1 centimeter which is far more accurate than the distance calculations require.

When a LatLng point is constructed, its latitude and longitude will be normalized to fall within the ±90 degrees latitude, ±180 degree longitude range. Special case: if your LatLng is constructed at a pole (±90 degrees latitude), its longitude will be set to 0 because all longitudes intersect at the poles.

Distance between two points

To calculate the distance between two points, use the static methods in LatLngTool.

LatLng point1 = new LatLng(33.123123, -127.123123);
LatLng point2 = new LatLng(33.321321, -127.321321);
double distanceInMiles = LatLngTool.distance(point1, point2, LengthUnit.MILE);

All supported units of length are contained by the enum LengthUnit. We will add supported units if there is call for them.

Geohashes

A geohash is a way to encode a coordinate into a concise string of alphanumeric characters.

For example, coordinate (57.64911, 10.40744) geohashes to u4pruydqqvj.

Not only are geohashes a little easier to read and share than numeric latitude and longitude, they also have the nice property that geohashes with similar prefixes are roughly spatially close to one another. (See wikipedia for more info.)

SimpleLatLng provides a geohash implementation that works with the LatLng class. Class Geohasher will produce hashes with a length of 12 characters, which corresponds with the default precision of the library. It will decode hashes of any length, but will drop any excess precision. (WARNING: There is a known bug decoding long and empty inputs.)

Geohasher.hash(new LatLng(44.869797, 6.599944)); // spuxq0mctb6u

Geohasher.decode("spuxq0mctb6u"); // LatLng(44.869797, 6.599944)
Geohasher.decode("spuxq0mc");     // LatLng(44.869795, 6.599865)
Geohasher.decode("spux");         // LatLng(44.912109, 6.503906)