A Geospatial Library for Java
Pull request Compare This branch is 681 commits ahead, 135 commits behind locationtech:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Spatial4j is a general purpose spatial / geospatial ASL licensed open-source Java library. It’s 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.

The most popular spatial library in Java is probably JTS. JTS is powerful but it is LGPL licensed, and it is not a geospatial library — just spatial. Surprisingly, there is no native circle shape in JTS either. Nevertheless, JTS is very powerful and Spatial4J includes integration classes for it.


  • Shape classes that are geospatially1 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 our dialect of 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.

1 Geospatial awareness means it is aware of the implications of the international dateline and poles. It can’t pretend the earth is flat and infinitely large.

Future Roadmap

  • Better multi-shape aggregates
  • Polygon pole wrap
  • Better and more standardized WKT support and potential use of CQL where it makes sense
  • Polygon support without JTS, maybe via java.awt.geom
  • Better support for other projections (not just WGS-84)
  • Elliptical earth model distance math


Discuss Spatial4j on our mailing list.


Spatial4j has been ported to .NET (C#) where it is appropriately named Spatial4n


Spatial4j began life within Lucene Spatial Playground (LSP) and from this work a generic core spatial library emerged, independent of Lucene. The other parts of LSP were either merged into Lucene / Solr itself or were migrated to Lucene Spatial Extras now.