The Lucene 3.x spatial contrib module is deprecated as of Lucene 3.6. In Lucene 4 there is a new spatial
module that should be used instead.
For further information, see
LUCENE-2599.
The old documentation follows below:
This package makes it possible to filter and sort according to geographical constraints. For example, filter to include only restaurants within 2 miles of a specified latitude/longitude, sorting by distance ascending.
See here for details on the technical approach.
Unfortunately, this package is still very new, and has little to no documentation. It's best to ask for pointers on java-user@lucene.apache.org, and look at the unit tests included in the source distribution.
There are also known issues, eg at least LUCENE-1781 and LUCENE-1815.
NOTE: This package is still in flux and might change in incompatible ways in the next release.