GeoJSON Diff

A Ruby library for diffing GeoJSON files

GeoJSON Diff takes two GeoJSON files representing the same geometry (or geometries) at two points in time, and generates three GeoJSON files representing the added, removed, and unchanged geometries (including changed properties).

These three GeoJSON files can be used to generate a visual representation of the changes (proposed or realized), e.g., by coloring the added elements green and the removed elements red. GeoJSON Diff is what powers GeoJSON diffing on GitHub.

See GeoJSON diff in action! Here's a diff of Illinois's famed 4th congressional district after undergoing redistricting in 2011:

GeoJSON Diff will even diff properties within the geometry when they change:

diff = GeojsonDiff.new geojson_before, geojson_after

diff.added
# => {"type":"Feature"... (valid GeoJSON representing the added geometries)

diff.removed
# => {"type":"Feature"... (valid GeoJSON representing the removed geometries)

diff.unchanged
# => {"type":"Feature"... (valid GeoJSON representing the unchanged geometries)

For practical examples, take a look at the test/fixtures directory.

Every geometry within the resulting GeoJSON files will be appended with standard GeoJSON properties in the _geojson_diff namespace.

• type - this field contains either added, removed, or unchanged and describes the state of the geometry as it relates to the initial GeoJSON file.
• added, removed, changed - these fields contain an array of property keys. If a given key is in the added array, that property existed in the resulting geometry, but not in the initial geometry. Likewise, if a key is in removed array it existed in the initial geometry, but not the resulting geometry, and if the key is in the changed array, it existed in both the initial and resulting geometry, but was changed.
• For changed properties, the values of the after GeoJSON file will be marked up as a Diffy :html diff and will represent the inline diff of the changed value.

GeoJSON Diff is based on rgeo, rgeo-geojson, geos, ffi-geos, and diffy.

If you're on OS X and have Homebrew installed, you'll first want to run brew install geos to install the GEOS geospatial library. On other systems, consult the GEOS installation instructions.

Add the following to your project's Gemfile and run bundle install:

gem 'geojson-diff'

Because the library depends on GEOS, which can be finicky on some systems, the set-it-and-forget-it way to get everything set up is to:

1. Add gem 'geojson-diff' to your project's Gemfile
2. Copy the contents of script/bootstrap
3. cd to your project's root directory and paste/run the commands

This will install GEOS and configure the necessary environmental values.

script/bootstrap

script/cibuild

script/console

On some environments, prior to running your application or running bundle install, you'll need to run the following commands to properly configure your execution environment for Ruby to find the GEOS library:

export GEOS_LIBRARY_PATH=`geos-config --prefix`/lib
bundle config --local build.rgeo --with-geos-dir="$GEOS_LIBRARY_PATH"

MIT

1. Fork the project
2. Create a descriptively named feature branch
3. Make your changes
4. Submit a pull request