geometry-api-java: Esri's geometry engine packaged for the JVM

A geometry engine extracted from the ArcGIS world

The Esri Geometry API for Java enables developers to write custom applications for analysis of spatial data. The repository description is direct about its origin: this API is used in the Esri GIS Tools for Hadoop and other 3rd-party data processing solutions.

The readme gives the same story in more detail. The API can be used to enable spatial data processing in 3rd-party data-processing solutions, and developers of custom MapReduce-based applications for Hadoop can use it for spatial processing of data in the Hadoop system.

What that means in practice is that this is a geometry kernel rather than a mapping application. There is no map, no layer, no renderer. There are geometry objects and operations on them, and a set of formats they can be read from and written to.

The stated use cases beyond Hadoop are the Hive UDFs in Esri's spatial framework for Hadoop, and the readme says the API could be used by developers building geometry functions for third-party applications such as Cassandra, HBase, Storm and many other Java based big data applications.

So the audience is a specific kind of engineer: someone with a spatial data problem inside a distributed Java system, who needs geometry operations that behave the way Esri's tools behave, and who wants them as a library dependency rather than as part of a platform installation. The requirement of familiarity with text based spatial data formats such as JSON or WKT is listed as useful, which tells you the shape of the work.

Three ways in, and the three families of operation

The feature list is short and organised in a way that mirrors how you actually use a geometry library.

For construction, there are API methods to create simple geometries directly with the API, or by importing from supported formats: JSON, WKT, and Shape. That last one is the Esri specific format, and it is the main practical reason to pick this library over another, because reading the shapefile family and the Esri shape records is the fiddly part that everyone otherwise reimplements badly.

For spatial operations, the methods are union, difference, intersect, clip, cut, and buffer. These are the constructive and analytic operations, and the naming matches the common GIS vocabulary, which means existing knowledge transfers directly.

For topological relationship tests, the methods are equals, within, contains, crosses, and touches. These are the predicates, and they are the ones a data pipeline leans on most often, since a spatial join is largely a repeated relationship test.

That three-way split, create, operate, test, is a good mental model for the library. It is also a reminder of what is not here. There is no spatial index, no spatial database, no projection or coordinate transformation service, and no topological correction. The library computes geometry, and the rest of the stack is yours.

The documentation lives in two places, a wiki on the repository and published Javadoc, and the readme points at both. The wiki is where the format specifics and the operator semantics are described, and the Javadoc is where the class and method signatures are.

Building it, and taking it as a Maven dependency

The build instructions cover both a source build and the ordinary dependency route, and the source route is the older, more manual one.

Building the source means you download and unzip the .zip file or clone the repository, then run the mvn compile command from within the cloned directory to build the jar. To deploy it you put esri-geometry-api.jar on the target system and add a reference to it in a Java project. The unit tests run with the mvn test command, also from within the cloned directory.

The project is also available as a Maven dependency:

<dependency>
  <groupId>com.esri.geometry</groupId>
  <artifactId>esri-geometry-api</artifactId>
  <version>2.3.1</version>
</dependency>

In practice the dependency route is what you want, and the jar deployment instructions are a leftover from the era when the library was primarily consumed by copying a jar onto a Hadoop node. If you are working in Hadoop today you are almost certainly using a build tool.

The requirements are Java JDK 1.17 or greater, the Apache Maven build system, and familiarity with text based spatial data formats such as JSON or WKT would be useful.

The JDK floor of 17 is the one to note. That is a modern baseline, which is unusual for a library of this vintage and rules out the older enterprise runtimes that some Hadoop deployments still run.

The repository tree is correspondingly plain for a Java project: a pom.xml, a build.xml for Ant, a src directory, a data directory, a manifest, the .travis.yml, and a license.txt carrying the Apache 2.0 text.

The release history has a five year hole in it

The version numbers tell a story worth reading carefully before you pin a dependency.

The recent releases are v2.3.1 on 2026-10-09, v2.3.0 on 2026-08-25, and v2.2.4 on 2020-09-21. So between 2.2.4 and 2.3.0 there is a gap of close to six years, and the library was not versioned during it. The repository is not archived and the last push was on 2026-10-09, the same day as the 2.3.1 release, so the work is real and current.

What that gap means for an adopter is that the two release lines are years apart in their assumptions, and the jump to 2.3.0 is where any change lands. The readme in this repository does not document what changed between 2.2.4 and 2.3.0, so the upgrade question is answered by the repository history and the changelog rather than by the documentation.

The reason the library moved at all is not stated here, but the context is worth noting: 2.3.0 landing in 2026 alongside a JDK 17 requirement and a refreshed build suggests the long gap was partly a toolchain and platform modernisation, not a feature freeze.

The 2.3.x line is the one to use. Pinning 2.2.4 because something in your dependency graph already wants it is a reasonable tactic, but you are then running a geometry engine that has not been updated since 2020, and a spatial library that old is a category of risk worth avoiding if you can help it.

Where this library is the wrong tool

There are cases where adding this dependency is a mistake, and they are about scope rather than quality.

The first is when you need a spatial database rather than a geometry kernel. The library has no index, no spatial query engine and no storage format of its own. If your requirement is to run spatial joins over hundreds of millions of rows, you want a system built for that, and geometry-api-java is a component you might use inside such a system rather than a replacement for one.

The second is when you need projections. There is no coordinate reference system handling described in the documentation here, so if your data arrives in one projection and your analysis needs another, that transformation is a separate dependency and a separate source of error.

The third is that it is a spatial function library without the rest of Esri's stack. If your task involves geoprocessing tools, projections, raster, network analysis or the ArcGIS runtime, this repository does not include them, and the readme only points at the ArcGIS Geodata Resource Center and the ArcGIS Blog as resources.

The fourth is a light dependency for light work. If the only thing you need is whether a point falls inside a polygon, or a simple buffer, a smaller geometry library will do it, with a smaller transitive footprint. This library carries the weight of an enterprise geometry kernel, and that is worth it only if you use the Esri specific parts, which in practice means the Shape format handling.

The fifth is the general shape of the API. It is a class library with static utility methods rather than something with a modern builder or a stream friendly surface, and that is a normal consequence of its age. The readme does not describe a modern API style, and the wiki and Javadoc are where you would look to see what the calling convention actually is.

Against JTS, and against the Hadoop native route

Two comparisons put the value in place.

The first is against JTS, the long-established open source geometry library for Java. The difference in approach is provenance and format coverage rather than algorithm design. JTS is a community library, while this library comes from Esri's own implementation, so its semantics match the ArcGIS tools, and it understands the Esri shape format natively. If your data arrives as Esri shapefiles and the rest of your pipeline agrees with Esri's notion of geometry, matching that semantics is the reason to choose this. If you want the conventional community choice, JTS is that.

The second is against the Hadoop native route. The API is used in the Esri GIS Tools for Hadoop and in the Hive UDFs of the spatial framework for Hadoop, and the readme also points at building geometry functions for Cassandra, HBase and Storm. So there are two ways to get spatial processing into a big data job: use the vendor's UDF layer that already wraps this library, or depend on the library directly and write your own functions. The direct route gives you control over which operations run and how they are combined, and it also means you own the version compatibility between the library and your Hadoop distribution, which the UDF route handles for you.

That is the real trade. The UDF route is less work and a supported configuration. The direct route is more work and a dependency you have to keep current, which is why the 2026 release matters even if you never call a method that changed.

Editorial conclusion

Adopt geometry-api-java if you need Esri compatible geometry semantics, especially shapefile and Esri shape handling, inside a Java or Hadoop project and do not want to pull in the ArcGIS stack. Skip it if you only need point in polygon or basic buffer work, since a lighter geometry library covers that, and skip it if you need the full desktop or geoprocessing toolset, which this library does not include. Verify first that the operations you rely on are in the version you pick, since the release history shows a long gap between 2.2.4 in 2020 and 2.3.0 in 2026.

Frequently asked questions

Official sources

1. Esri/geometry-api-java on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases