Metadata-Version: 2.4
Name: geojson-diff
Version: 0.1.0
Summary: Feature-level diffs of GeoJSON datasets for code review, pull requests and data pipelines: text, JSON, Markdown, GeoJSON and HTML map reports, git diff driver and CI exit codes.
Author-email: Yusuf Eminoğlu <yusufeminoglu@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/YusufEminoglu/geojson_diff_sdk
Project-URL: Repository, https://github.com/YusufEminoglu/geojson_diff_sdk
Project-URL: Issues, https://github.com/YusufEminoglu/geojson_diff_sdk/issues
Project-URL: Documentation, https://github.com/YusufEminoglu/geojson_diff_sdk#readme
Project-URL: Changelog, https://github.com/YusufEminoglu/geojson_diff_sdk/blob/main/CHANGELOG.md
Keywords: geojson,diff,gis,geospatial,git,code-review,pull-request,data-pipeline,ci,geojsonseq,hausdorff,leaflet,change-detection,data-quality
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: shapely
Requires-Dist: shapely>=2.0.0; extra == "shapely"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# geojson-diff

[![CI](https://github.com/YusufEminoglu/geojson_diff_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/geojson_diff_sdk/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/geojson-diff.svg)](https://pypi.org/project/geojson-diff/)
[![Python](https://img.shields.io/pypi/pyversions/geojson-diff.svg)](https://pypi.org/project/geojson-diff/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Feature-level diffs of GeoJSON datasets** for GIS and data teams that review
changes in git, pull requests and data pipelines.

A line diff of a GeoJSON file tells you that line 18 412 changed. `geojson-diff`
tells you that parcel `1042` got a new height, bus stop `77` moved 21 m, three
buildings were removed and one was added - and it can say so in your terminal, in a
pull-request comment, on a map, or through an exit code that fails a CI job.

- Diffs **FeatureCollections, GeoJSONSeq (RFC 8142) and newline-delimited GeoJSON**.
- Matches features **by id, by property key(s), by geometry hash or spatially**
  (proximity + attribute similarity, deterministic assignment), in a chain.
- Classifies **added / removed / modified / moved / unchanged**.
- **Typed, nested property diffs** with JSON Pointer paths.
- **Tolerance-aware geometry diffs** in metres (haversine) or degrees: Hausdorff
  distance, vertex-level change counts, area and length deltas, bbox of changes.
- Outputs **text** (coloured on a TTY), **JSON** (patch-like), **Markdown** (PR
  comments), a **GeoJSON diff layer** (simplestyle, renders on GitHub) and a
  self-contained **HTML report with a Leaflet map**.
- **Git diff driver / textconv**, a `git-geojson-diff REV1 REV2 PATH` helper and
  **CI exit codes** with `--fail-on` thresholds.
- **Pure Python standard library**, streaming reader, typed (`py.typed`). Optional
  `shapely` extra for exact equality and symmetric-difference areas.

## Installation

```bash
pip install geojson-diff
pip install "geojson-diff[shapely]"   # optional: exact equality + symmetric-difference area
```

Python 3.9 or newer. No required dependencies.

## Quick start

```bash
geojson-diff old.geojson new.geojson [--key id] [--tolerance 0.5m] \
    [--format text|json|md|geojson|html] [-o out]
```

Using the two files in [`examples/`](examples):

```console
$ geojson-diff parcels_v1.geojson parcels_v2.geojson --tolerance 0.5m
geojson-diff parcels_v1.geojson -> parcels_v2.geojson
5 -> 5 features: 1 added, 1 removed, 1 modified, 1 moved, 2 unchanged
matched by id, hash; tolerance 0.5 m

+ added     6  Point
      name: "New cafe"
      amenity: "cafe"
- removed   3  Polygon
      name: "Old shed"
      height: 3
~ modified  1  Polygon
      height: 12 -> 14.5 (integer -> number)
      tags.use: "residential" -> "mixed"
      + tags.levels: 4
> moved     4  LineString
      + surface: "asphalt"
      geometry: Hausdorff 21.0 m, centroid shift 5.6 m, vertices 1 moved (4 -> 4), length +3.3 m

bbox of changes: [29.000000, 41.000000, 29.004500, 41.001800]
area delta -93.5 m2, length delta -35.7 m
$ echo $?
1
```

Bus stop `2` was nudged by about 9 cm, which is inside the 0.5 m tolerance, so it is
reported as unchanged. Without `--tolerance` the comparison is exact and the stop
shows up as `moved`.

## How features are classified

| Status | Meaning |
|---|---|
| `added` | only in the new file |
| `removed` | only in the old file |
| `modified` | matched, properties (or the feature `id`) changed, geometry within tolerance |
| `moved` | matched, geometry changed beyond the tolerance (property changes are listed too) |
| `unchanged` | matched, nothing changed |

A geometry is **unchanged** when both versions have the same layout and every vertex
stayed within the tolerance, or - when the vertex layout differs - when the Hausdorff
distance between them is within the tolerance. Rotating a ring's start vertex,
flipping its orientation or inserting a collinear vertex therefore does not count
as a change. Z values are compared against the tolerance value in metres (exactly
for degree tolerances).

### Tolerances

| `--tolerance` | Meaning |
|---|---|
| `0` (default) | exact comparison |
| `0.5m`, `10cm`, `5mm`, `1km`, `2ft` | metres; haversine on longitude/latitude data |
| `1e-6deg`, `0.00001°`, `0.00001` | coordinate units (degrees for RFC 7946 data) |

Longitude/latitude data is detected automatically; projected data (coordinates
outside +-180/+-90, or `--crs projected`) is measured in CRS units and reported with
`units` instead of metres.

### Matching strategies

`--match` takes an ordered chain; features that one strategy cannot match are offered
to the next.

| Strategy | Matches on | Notes |
|---|---|---|
| `id` | the feature's top-level `id` | `1` and `"1"` are the same key |
| `key` | one or more properties (`--key parcel_id`, `--key block --key lot`) | dotted paths for nested keys (`meta.ref`); `id` falls back to the feature id, `@id` always means the feature id |
| `hash` | a normalised geometry hash | rounded to `--precision` decimals (7); insensitive to ring start, orientation and part order |
| `spatial` | centroid proximity + attribute similarity | `--max-distance 50m`, `--attribute-weight 0.5`, `--min-score 0.5`; same geometry family only |
| `auto` (default) | `key` if `--key` is given, else `id` then `hash` | |

Spatial matching scores every candidate pair as
`(1 - w) * (1 - distance / max_distance) + w * similarity` and assigns pairs greedily
by score, then distance, then input order, so the result is always the same for the
same inputs. Duplicate keys are paired in input order and reported as warnings.

```bash
geojson-diff old.geojson new.geojson --key parcel_id
geojson-diff old.geojson new.geojson --key block,lot --ignore-property updated_at
geojson-diff old.geojson new.geojson --match id,hash,spatial --max-distance 25m
```

### Property diffs

Nested objects are compared key by key and equal-length arrays element by element;
paths are RFC 6901 JSON Pointers (`/properties/tags/0`). `1` and `1.0` are equal
unless `--strict-types` is given; `true` and `1`, or `"1"` and `1`, never are, and
type changes are reported (`integer -> number`). `--ignore-property` (repeatable,
dotted for nested keys) skips noisy attributes such as timestamps.

## Output formats

`--format` (or the extension of `-o`) selects the output:

| Format | Use |
|---|---|
| `text` | terminal; coloured when stdout is a TTY (`--color`, `NO_COLOR`, `FORCE_COLOR`) |
| `json` | machine-readable, JSON-Patch-like |
| `md` | pull-request comments and CI job summaries |
| `geojson` | a diff layer for QGIS, geojson.io or GitHub's map viewer |
| `html` | a single-file report with a Leaflet before/after map |

### Markdown

```console
$ geojson-diff parcels_v1.geojson parcels_v2.geojson -t 0.5m -f md
```

```markdown
### GeoJSON diff: parcels&#95;v1.geojson → parcels&#95;v2.geojson

**4 feature changes** (5 → 5 features; matched by id, hash; tolerance 0.5 m)

| Added | Removed | Modified | Moved | Unchanged |
|---:|---:|---:|---:|---:|
| 1 | 1 | 1 | 1 | 2 |

bbox of changes 29.000000, 41.000000, 29.004500, 41.001800 · area Δ -93.5 m² · length Δ -35.7 m

<details open><summary>Feature changes (4)</summary>

| Change | Feature | Geometry | Details |
|---|---|---|---|
| added | 6 | Point | name: "New cafe"<br>amenity: "cafe" |
| removed | 3 | Polygon | name: "Old shed"<br>height: 3 |
| modified | 1 | Polygon | height: 12 → 14.5 (integer → number)<br>tags.use: "residential" → "mixed"<br>+ tags.levels: 4 |
| moved | 4 | LineString | + surface: "asphalt"<br>geometry: Hausdorff 21.0 m, centroid shift 5.6 m, vertices 1 moved (4 → 4), length +3.3 m |

</details>

<sub>Generated by geojson-diff</sub>
```

Every data value is escaped (HTML entities for Markdown syntax, `@` and `#`), so a
property value cannot inject markup, links, table columns or user mentions.
`--md-map` appends the diff layer as a ` ```geojson ` block, which GitHub renders as
an interactive map; `--max-rows` limits the table.

### JSON

```console
$ geojson-diff parcels_v1.geojson parcels_v2.geojson -t 0.5m -f json
```

The document holds `options`, a `summary` and one entry per change. Property changes
use JSON Patch vocabulary with the old value and JSON types added:

```json
{
  "op": "modify",
  "status": "modified",
  "key": "1",
  "old_index": 0,
  "new_index": 0,
  "matched_by": "id",
  "patch": [
    {"op": "replace", "path": "/properties/height", "old": 12, "old_type": "integer",
     "value": 14.5, "new_type": "number"},
    {"op": "replace", "path": "/properties/tags/use", "old": "residential",
     "old_type": "string", "value": "mixed", "new_type": "string"},
    {"op": "add", "path": "/properties/tags/levels", "value": 4, "new_type": "integer"}
  ],
  "geometry": {"changed": false, "old_type": "Polygon", "new_type": "Polygon",
               "units": "m", "vertices": 4},
  "area_delta": 0.0,
  "length_delta": 0.0,
  "bbox": [29.001, 41.001, 29.0014, 41.0013]
}
```

`moved` entries add `{"op": "replace", "path": "/geometry", ...}` to the patch and a
`geometry` block with `hausdorff`, `max_vertex_shift`, `centroid_shift`,
`vertices_added/removed/moved`, `area_old/new/delta`, `length_old/new/delta`, `bbox`
and (with `--shapely`) `symmetric_difference_area`. `added` / `removed` entries carry
the whole feature.

### GeoJSON diff layer

`-f geojson` writes a FeatureCollection in which every changed feature is styled with
[simplestyle-spec](https://github.com/mapbox/simplestyle-spec) properties (`stroke`,
`fill`, `fill-opacity`, `marker-color`, `title`, `description`) - green for added,
red for removed, orange for modified, blue for moved, with a grey `before` outline for
moved features. GitHub renders `.geojson` files with that styling. The change itself
is described by `diff:status`, `diff:role` (`change` or `before`), `diff:key`,
`diff:changed` and `diff:hausdorff`.

### HTML report

```bash
geojson-diff old.geojson new.geojson -t 0.5m -o review.html
```

A single file with summary cards, a Leaflet map (before and after layers, popups) and
a table of changes. Leaflet 1.9.4 is loaded from unpkg with Subresource Integrity and
OpenStreetMap tiles are attributed. Data is embedded as escaped JSON and rendered
with `textContent`, and the table is HTML-escaped, so hostile property values cannot
run script. The OpenStreetMap tile servers may refuse requests from `file://` pages
that send no referrer; serve the report over HTTP (for example as a CI artifact or
`python -m http.server`) or pass your own tile server through the Python API
(`render(result, "html", tiles=..., attribution=...)`).

## Git integration

### Readable `git diff` with a textconv filter

`--textconv` prints a stable, line-per-attribute rendering (features sorted by id,
properties sorted by key, coordinates rounded), so the ordinary line diff becomes
meaningful. Tell git which files to treat this way in `.gitattributes`:

```gitattributes
*.geojson  diff=geojson
*.geojsons diff=geojson
```

and define the `geojson` diff driver once in your git configuration (run this
yourself; it is per repository unless you add `--global`):

```bash
git config diff.geojson.textconv "geojson-diff --textconv"
git config diff.geojson.cachetextconv true
```

### Feature-level `git diff` with an external diff driver

Instead of (or as well as) textconv, git can hand both versions to `geojson-diff`:

```bash
git config diff.geojson.command "geojson-diff --git --tolerance 0.5m"
git diff                 # uses the driver for *.geojson
git log -p --ext-diff -- data/parcels.geojson
git diff --no-ext-diff   # plain line diff when you need it
```

Git calls the command with `path old-file old-hex old-mode new-file new-hex new-mode`
(nine arguments for renames); `/dev/null` stands for the missing side of an added or
deleted file. In this mode `geojson-diff` always exits 0 unless the input is broken,
because git aborts the whole diff when an external driver fails. Any option can be
added to the command (`--key`, `--format md`, ...).

### Diffing revisions: `git-geojson-diff`

```bash
git-geojson-diff HEAD~1 HEAD data/parcels.geojson
git-geojson-diff main data/parcels.geojson             # main vs. working tree
git geojson-diff v1.2 v1.3 data/parcels.geojson --format html -o review.html
```

Because the script is on your `PATH` as `git-geojson-diff`, git also runs it as
`git geojson-diff`. A file missing at one revision counts as empty, so added and
deleted files work. It takes every `geojson-diff` option and uses the same exit codes.

## CI usage

| Exit code | Meaning |
|---|---|
| `0` | no changes (or none above the `--fail-on` thresholds) |
| `1` | changes found |
| `2` | error (unreadable or invalid input, bad arguments) |

```bash
geojson-diff old.geojson new.geojson --fail-on removed            # fail only on removals
geojson-diff old.geojson new.geojson --fail-on removed:10,moved:0 # allow up to 10 removals
geojson-diff old.geojson new.geojson --fail-on any:5 -q           # any category above 5
geojson-diff old.geojson new.geojson --exit-zero -f md >> "$GITHUB_STEP_SUMMARY"
```

`--fail-on` takes `added`, `removed`, `modified`, `moved` or `any`, each with an
optional `:N` allowance (exit 1 when the count exceeds N; default 0).

### GitHub Actions: post the summary on pull requests

[`examples/github-actions/geojson-diff.yml`](examples/github-actions/geojson-diff.yml)
diffs every changed `*.geojson` file between the pull-request base and head, posts a
single Markdown comment (updated on later pushes), copies it to the job summary and
fails the check when features were removed. The core of it:

```yaml
      - name: Diff changed GeoJSON files
        id: diff
        shell: bash
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          set +e  # exit status 1 means "changes found", not a failure of this step
          status=0
          : > geojson-diff.md
          while IFS= read -r -d '' path; do
            git-geojson-diff "$BASE_SHA" HEAD "$path" \
              --format md --title "GeoJSON diff: $path" \
              --tolerance 0.5m --fail-on removed --max-rows 50 >> geojson-diff.md
            rc=$?
            echo >> geojson-diff.md
            if [ "$rc" -eq 2 ]; then echo "::error file=$path::geojson-diff failed"; status=2; fi
            if [ "$rc" -eq 1 ] && [ "$status" -eq 0 ]; then status=1; fi
          done < <(git diff -z --name-only "$BASE_SHA" HEAD -- '*.geojson' '*.geojsons')
          cat geojson-diff.md >> "$GITHUB_STEP_SUMMARY"
          echo "status=$status" >> "$GITHUB_OUTPUT"

      - name: Post the summary on the pull request
        if: github.event.pull_request.head.repo.full_name == github.repository
        env:
          GH_TOKEN: ${{ github.token }}
          PR: ${{ github.event.pull_request.number }}
        run: gh pr comment "$PR" --body-file geojson-diff.md --edit-last --create-if-none
```

The checkout needs `fetch-depth: 0` and the job `pull-requests: write`; see the full
file for the remaining steps.

## Python API

```python
from geojson_diff import DiffOptions, diff, render, diff_layer

result = diff(
    "old.geojson",
    "new.geojson",
    keys=["parcel_id"],              # or match=["id", "hash", "spatial"]
    tolerance="0.5m",
    ignore_properties=["updated_at"],
)

print(result.counts)        # e.g. {'added': 1, 'removed': 1, 'modified': 1, 'moved': 1, 'unchanged': 2}
print(result.has_changes, result.bbox, result.area_delta)

for change in result.changes:            # unchanged features are kept with keep_unchanged=True
    print(change.status, change.key, change.matched_by)
    for prop in change.properties:
        print("  ", prop.op, prop.path, prop.old, "->", prop.new, prop.old_type, prop.new_type)
    if change.geometry and change.geometry.changed:
        print("   hausdorff", change.geometry.hausdorff, "m")

markdown = render(result, "md", max_rows=50)
html = render(result, "html", title="Parcel update 2026-11")
layer = diff_layer(result)                    # dict, ready for json.dump
payload = result.to_dict()                    # the JSON output as a dict
```

`diff()` accepts paths, `"-"` (stdin), open files, parsed GeoJSON objects or plain
iterables of features. Lower-level helpers are public as well:
`compare_features`, `compare_geometry`, `diff_properties`, `hausdorff_distance`,
`haversine`, `geometry_area`, `geometry_length`, `geometry_hash`, `iter_features`,
`parse_tolerance`.

## Large files

The reader decodes one feature at a time: the `features` array of a
FeatureCollection is streamed, as are GeoJSONSeq and newline-delimited files. The
old file is indexed by key; when the first strategy is `id`, `key` or `hash`, the new
file is streamed against that index and unchanged features are dropped as soon as
they are compared, so memory grows with the old file plus the changes. Geometry
metrics are computed only for geometries that actually changed. On a laptop, two
66 MB FeatureCollections with 100 000 polygons each diff in about 8 seconds, most of
it JSON decoding.

## Optional shapely extra

With `pip install "geojson-diff[shapely]"` and `--shapely` (`use_shapely=True`):

- with an exact tolerance (`0`), geometries are compared for topological equality
  (`shapely.equals`), and
- moved polygons report `symmetric_difference_area` (square metres via a local
  projection for longitude/latitude data).

## Limitations

- The Hausdorff distance is measured from every vertex to the other geometry's
  segments in both directions. It is exact for points; for lines and polygons it can
  slightly underestimate when the farthest point lies inside an edge rather than at a
  vertex.
- Areas use a spherical model (WGS84 semi-major axis), accurate to well under 1 % for
  the parcel- to city-scale changes reviewed in practice.
- `moved` means "geometry changed beyond tolerance"; a reshaped polygon is `moved` too.

## Development

```bash
python -m pip install -e ".[dev,shapely]"
python -m pytest --cov=geojson_diff
python -m ruff check . && python -m ruff format --check src tests
python -m mypy src
```

## License and citation

MIT License - see [LICENSE](LICENSE). If you use `geojson-diff` in research, please
cite it using [CITATION.cff](CITATION.cff).

Author: Yusuf Eminoğlu
