Status message

This proposal has been approved and the Spatial4j project has been created.


This proposal is in the Project Proposal Phase (as defined in the Eclipse Development Process) and is written to declare its intent and scope. We solicit additional participation and input from the community. Please login and add your feedback in the comments section.
Parent Project: 

Spatial4j came about as a subset of a body of Java spatial code in support of spatial information-retrieval for Apache Lucene and Solr. Spatial4j is the subset that deals solely with defining shapes, computing distances, shape intersection, and parsing and writing shape strings. To my knowledge, it is only used by Lucene 4's spatial module. Spatial4j is an independent part of Lucene spatial for two reasons: Most importantly, it uses (albeit optionally) the 3rd party JTS library which is LGPL licensed. The Apache Software Foundations forbids a dependency, even an optional one, on LGPL licensed software. The second reason is that Spatial4j should be independently useful on its own. I don't know of the geodetic shape intersection algorithms it has existing in any other open-source software. Perhaps I didn't look hard enough but that is to the best of my knowledge.

Andrew Ross contacted David & Ryan extolling the benefits of LocationTech and we are interested. This has the opportunity to get better visibility to Spatial4j which currently exists in the shadow of Lucene spatial.


Spatial4j has a fairly limited scope largely centered around geometric shape implementations:

  • Define geometric shapes, both classic Euclidean/Cartesian two-dimensional ones and geodetic (surface-of-sphere) ones.  Some sample shapes are: point, rectangle, circle (aka point-distance), polygon, linestring
  • Compute the bounding box of a shape
  • Compute the intersection case between a pair of shapes, especially where one of them is a point or rectangle. Intersection cases are intersects, contains, within, and disjoint. 
  • Compute the area of a shape
  • Compute the distance between points (plus other misc. distance / angle calculations)
  • Compute a geohash string for a point, and vice-versa, and compute the rectangle for a geohash, (plus other misc. geohash calculations)
  • Encode and decode a shape to and from a serialized representation. An example is Well Known Text (WKT).

Spatial4j is a general purpose spatial / geospatial ASL licensed open-source Java library. Its core capabilities are 3-fold: to provide common geospatially-aware shapes, to provide distance calculations and other math, and to read and write the shapes to strings.


  • Shape classes that are geospatially aware(*)
    • Shapes: Point, Rectangle, Circle, Polygon (via JTS)
    • shape intersection logic, yielding: disjoint, contains, within, intersects
    • bounding box
    • area calculation
  • Distance math
    • Spherical: Law of Cosines, Haversine, Vincenty
  • Input and Output of shapes to strings using WKT
  • Integration with JTS to adapt its shapes to Spatial4j’s interfaces, including adding some geospatial awareness
  • No runtime dependencies unless JTS is needed

In addition, the code is well tested and it’s monitored via Travis-CI continuous integration.

(*) Geospatial awareness, AKA "geodetic" means it is aware of the implications of the international dateline and poles. It can’t pretend the earth is flat and infinitely large.

Why Here?: 

I hope that Spatial4j will get more visibility so that it will be used more and ultimately so that more people might contribute.  Also, the additional processes will make the project better managed from an intellecutal property point of view, which could in turn make it easier to consume for corporations that are more discerning in which open-source libraries they use.  Finally, joining LocationTech can bring internship opportunities to improve Spatial4j.

Project Scheduling: 

Frankly there isn't any schedule.  The last release was over a year ago -- Spatial4j v0.3, August 31 2012.  It's overdue for a new release and I'm working on features I want in that release.

Future Work: 
WKT native to Spatial4j is in progress, plus some general API enhancements.
* a geodetic buffered LineString implementation.  The current one isn't geodetic.
* an un-buffered LineString (geodetic & not)
* a non-geodetic polygon implementation based on java.awt.geom.  Maybe add dateline and pole encompass support, akin to how I've done it with JTS.
* a polygon (and linestring) point densifier that densifies according to a geodetic distance error threshold
* binary shape read/writing (not WKB) 
* a geodetic polygon *might* be contributed by someone I know at Raytheon
* projections via Proj4
Source Repository Type: 
Initial Contribution: 


The layout of the code in source control is built with Maven and it uses Maven's default layout for organization.  It's a single module.  As of 2012-09 (1 year ago) I measured ~ 2055 "Non-Comment Source Statements". There has been some development in the last year plus the tests are substantial and don't count towards that number.  If you look in the git history, it's apparent that the code was originally named Lucene Spatial Playground (LSP) and once included code for Lucene, Solr, and a demo webapp. Those parts now exist elsewhere and this code, Spatial4j, focuses on what's left -- the shapes.  There is a mailing list with very light traffic.  

There exists a port of Spatial4j to .NET called, unsurprisingly, Spatial4n.  This was done by Itamar Syn-Hershko so that the RavenDB database can use it in conjunction with a port of Lucene's spatial module to the .NET platform.


All code is licensed under the Apache Software License, v2. 


All source files are copyrighted by the Apache Software Foundation. It's likely copyright is effectively also held by those who wrote/contributed it originally, but nevertheless the source files all indicate copyright to only Apache.  See "Code origins" next.

Code origins (who originally wrote what code):

This information may not matter as it's all copyrighted to the ASF.  Most of the code was originally written by David Smiley, Ryan McKinley, and Chris Male, in that order.  All are current committers and PMC members to the Apache Lucene/Solr joint project.  The only exceptions are GeohashUtils and DistanceUtils which were (orignally) written by Patrick O'Leary years ago (a former Apache Lucene committer. They have both been modified substantially since but are recognizable to their origins.  A small number of "very minor" contributions have been made by other parties to the existing code.

Compile Dependencies:

  • JTS Topology Suite.  It's LGPL licensed.  JTS is optional to Spatial4j users if you don't use certain features -- namely polygons.

Test Dependencies: (do these matter?)