geofix

Fast, dependency-light GeoJSON validator and repairer for the command line, pre-commit hooks and CI. It checks files against RFC 7946 (structure, coordinates, winding, bounding boxes) and polygon topology (self-intersections, holes), tells you where each problem is, and can repair most of them, reporting every change it makes.

• Pure Python, no required dependencies (only tomli on Python < 3.11 for reading pyproject.toml). Topology checks run without shapely or GEOS.
• Streams large files: a FeatureCollection is read one feature at a time, and newline-delimited GeoJSON (GeoJSONSeq / RFC 8142, .geojsonl, .ndgeojson) one record at a time.
• Made for CI: exit codes, --format github annotations, --format json, --select/--ignore rule codes, [tool.geofix] configuration, a pre-commit hook.
• Explains CRS mistakes: "this looks like EPSG:3857 Web Mercator (the centre would be lon 28.99762, lat 40.97734)", UTM/TM eastings, swapped [lat, lon] axes.
• Repairs safely: geofix fix never changes data without a recorded change, leaves valid files byte-for-byte untouched, and is idempotent.

pip install geofix            # pure Python
pip install "geofix[shapely]"  # + shapely.make_valid for complex topology repairs

Command line

geofix check

$ geofix check examples/bad.geojson
examples/bad.geojson:2:1: GF212 warning: exterior ring is clockwise [$.features[0].geometry.coordinates[0]]
    hint: Reverse the ring (ogr2ogr -lco RFC7946=YES writes the right order).
examples/bad.geojson:3:1: GF220 error: ring crosses itself at (29.025, 41.005) [$.features[1].geometry.coordinates[0]]
    hint: Split bow-ties into separate polygons or rebuild with shapely.make_valid.
examples/bad.geojson:4:1: GF109 warning: 1 consecutive duplicate position(s), first [29.05, 41] [$.features[2].geometry.coordinates[0][2]]
    hint: Remove the repeated positions.
examples/bad.geojson:4:1: GF210 error: ring is not closed: first position [29.04, 41], last [29.04, 41.01] [$.features[2].geometry.coordinates[0]]
    hint: Repeat the first position at the end of the ring.
examples/bad.geojson:4:1: GF108 info: 1 of 5 position(s) have more than 7 decimals [$.features[2].geometry.coordinates[0][3]]
    hint: Round coordinates; 6 decimals is ~10 cm, 7 is ~1 cm (RFC 7946 section 11.2).
examples/bad.geojson:5:1: GF006 warning: id 'parcel-3' is also used by $.features[2] [$.features[3].id]
    hint: Give every feature its own id, or drop ids that are not identifiers.
examples/bad.geojson:5:1: GF107 error: coordinates (x 3.228e+06..3.228e+06, y 5.009e+06..5.009e+06) look projected, not WGS 84 longitude/latitude: this looks like EPSG:3857 Web Mercator (the centre would be lon 28.99762, lat 40.97734) or a Gauss-Kruger/TM grid with zone-prefixed eastings [$.features[3].geometry.coordinates]
    hint: Reproject to EPSG:4326, e.g. ogr2ogr -t_srs EPSG:4326 -lco RFC7946=YES out.geojson in.geojson.
examples/bad.geojson:6:1: GF106 warning: latitude 129.0 is out of range while every longitude is within +/-90: positions look like [lat, lon] [$.features[4].geometry.coordinates[0]]
    hint: GeoJSON order is longitude first; swap x and y (EPSG:4326 axis order is a common cause).
examples/bad.geojson:7:1: GF200 warning: MultiPolygon has empty coordinates [$.features[5].geometry]
    hint: Remove the feature, or use "geometry": null for features without a location.
examples/bad.geojson:1:1: GF301 error: "bbox" [29, 41, 29.03, 41.01] does not contain the coordinates (extent [29, 41, 3228000.5, 5009000.25]) [$.bbox]
    hint: Recompute the bbox from the coordinates.

Found 10 issues (4 errors, 5 warnings, 1 info) in 1 of 1 file.
$ echo $?
1

Each line is file:line:column: CODE severity: message [JSON path]. The line is where the feature (or record) starts; the JSON path points inside it. Directories are searched recursively for .geojson, .geojsonl, .geojsons, .geojsonseq, .ndgeojson and .geo.json files; - reads standard input.

Useful options: --select GF2,GF3, --ignore GF007,GF108 (codes or prefixes, ALL), --fail-on error|warning|info, --precision N, --statistics, --no-hints, --format text|json|github.

geofix fix

$ geofix fix examples/bad.geojson -o fixed.geojson --no-hints
examples/bad.geojson: fixed 9 problems (GF108 x1, GF109 x1, GF200 x1, GF210 x1, GF212 x2, GF220 x2, GF301 x1)
examples/bad.geojson:5:1: GF006 warning: id 'parcel-3' is also used by $.features[2] [$.features[3].id]
examples/bad.geojson:5:1: GF107 error: coordinates (x 3.228e+06..3.228e+06, y 5.009e+06..5.009e+06) look projected, not WGS 84 longitude/latitude: this looks like EPSG:3857 Web Mercator (the centre would be lon 28.99762, lat 40.97734) or a Gauss-Kruger/TM grid with zone-prefixed eastings [$.features[3].geometry.coordinates]
examples/bad.geojson:6:1: GF106 warning: latitude 129.0 is out of range while every longitude is within +/-90: positions look like [lat, lon] [$.features[4].geometry.coordinates[0]]

Applied 9 fixes to 1 file. Found 3 remaining issues (1 error, 2 warnings) in 1 of 1 file.

What it did: rewound the clockwise shell, split the bow-tie into a two-part MultiPolygon, removed the duplicate vertex, closed the open ring, rounded the over-precise coordinate, removed the feature with an empty geometry and recomputed the collection bbox. It did not guess a CRS or swap axes: those are reported for a human to decide.

• geofix fix FILE writes the result to standard output (the report goes to stderr); -o OUT writes a file; -i/--in-place rewrites inputs only when something changed; --dry-run reports what would change and exits 1 if anything would.
• --show-changes lists every change instead of a per-file summary; --exit-nonzero-on-fix exits 1 when a file was modified; --no-shapely keeps repairs pure Python.
• Collections are written one feature per line (readable diffs); --indent N pretty-prints single objects. Collection members keep their order, except bbox, which is written after features because it can only be computed once every feature has been repaired.
• Repairs run in this order: round (GF108), drop duplicates (GF109), close rings (GF210), drop degenerate holes/parts (GF211/GF214), topology (GF220-GF222), rewind (GF212/GF213), recompute bboxes (GF300-GF302). A second geofix fix on the output changes nothing.
• Rounding to the configured precision (7 decimals by default, ~1 cm) is a repair like any other: disable it with --ignore GF108 or change it with --precision 9.

geofix stats and geofix rules

$ geofix stats examples/bad.geojson
examples/bad.geojson
  kind:            FeatureCollection
  size:            1.2 kB
  features:        6
  geometry types:  Polygon 3, Point 1, LineString 1, MultiPolygon 1
  null / empty:    0 / 1
  positions:       18 (0 with z)
  max decimals:    10
  bbox:            [29, 41, 3.228e+06, 5.009e+06]
  ids:             6 (5 unique)
  properties:      name (5)
  read in:         0.00 s

geofix rules lists every rule (--format text|json|markdown).

Exit codes

Warnings do not fail a run by default; use --fail-on warning (or fail-on = "warning" in the configuration) for strict RFC 7946 conformance, e.g. ring winding.

Rules

Notes on the checks:

• Topology is planar, in the coordinate space of the file, like the OGC simple feature rules: within a ring any contact between non-adjacent edges is an error (crossing, touching, or a collinear spike); between rings, crossings and shared edges are errors, while a single touching point is allowed. Overlap between the parts of a MultiPolygon is not checked.
• Antimeridian: RFC 7946 3.1.9 asks for geometries crossing 180 degrees to be cut into multi-part geometries. GF230 flags segments that jump more than 180 degrees of longitude; geofix does not cut them (use ogr2ogr -wrapdateline or the antimeridian package). A bbox with west > east is accepted as an antimeridian-crossing box (RFC 7946 5.2).
• CRS heuristics (GF106/GF107) look at each geometry's extent. Values beyond +/-1000 are treated as metres; eastings of 100 000-900 000 m suggest UTM or a national TM grid (for example TUREF/TM), values within the Web Mercator square are back-projected so you can see where the data would land if it were EPSG:3857. [lat, lon] is only detectable when a latitude falls outside +/-90 while every longitude is within +/-90.
• Precision (GF108) counts decimals of the shortest representation of each longitude and latitude (elevations are not checked).

Configuration

geofix reads [tool.geofix] from the nearest pyproject.toml (or --config FILE; --isolated ignores it). Command-line options override it.

[tool.geofix]
select = ["ALL"]            # codes or prefixes, e.g. ["GF0", "GF2"]
ignore = ["GF007"]          # foreign members are fine for us
fail-on = "warning"         # error | warning | info
precision = 6               # GF108 threshold and fix rounding
shapely = true              # let `geofix fix` use shapely.make_valid when installed
format = "text"             # text | json | github

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/YusufEminoglu/geofix_sdk
    rev: v0.1.0
    hooks:
      - id: geofix          # validate
      # - id: geofix-fix    # or repair in place (the commit stops if a file changed)

Both hooks run on .geojson, .geojsonl, .geojsons, .geojsonseq and .ndgeojson files and honour [tool.geofix]. Pass options with args, e.g. args: [--fail-on, warning].

GitHub Actions

# .github/workflows/geojson.yml
name: GeoJSON
on: [push, pull_request]
jobs:
  geofix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.13"
      - run: pip install geofix
      - run: geofix check --format github data/

--format github prints workflow commands so issues appear as annotations on the pull request diff, at the line where each feature starts:

::warning file=examples/bad.geojson,line=2,col=1,title=geofix GF212 (exterior-clockwise)::exterior ring is clockwise at $.features[0].geometry.coordinates[0]%0Ahint: Reverse the ring (ogr2ogr -lco RFC7946=YES writes the right order).
::error file=examples/bad.geojson,line=3,col=1,title=geofix GF220 (self-intersection)::ring crosses itself at (29.025, 41.005) at $.features[1].geometry.coordinates[0]%0Ahint: Split bow-ties into separate polygons or rebuild with shapely.make_valid.

Python API

import geofix

# Validate a parsed object, a JSON string/bytes, or a file (streamed).
issues = geofix.check({"type": "Point", "coordinates": [3228000.0, 5009000.0]})
issues = geofix.check_file("parcels.geojson", ignore=["GF007"], precision=6)
for issue in issues:
    print(issue.code, issue.severity, issue.line, issue.path, issue.message, issue.hint)

# Repair. The input is never modified; every modification is a Change.
result = geofix.fix(my_feature_collection)
result.data      # repaired object
result.changes   # [Change(code="GF212", path="$.features[0]...", message="rewound ...")]
result.issues    # what is still wrong after the repair

# Repair a file feature by feature (dst may equal src; None is a dry run; "-" is stdout).
result = geofix.fix_file("in.geojson", "out.geojson", use_shapely=False)

# Options can be shared.
opts = geofix.Options(select=["GF2", "GF3"], fail_on="warning", precision=7)
geofix.check_file("in.geojson", opts)

# Streaming building blocks.
with open("big.geojsonl", encoding="utf-8") as fh:
    for path, feature in geofix.iter_features(fh):
        ...

stats = geofix.stats_file("in.geojson")   # counts, bbox, property keys, max decimals
geofix.RULES["GF220"].summary             # rule registry

geofix.Validator and geofix.Repairer are the incremental engines behind these functions (feed them features one at a time); geofix.Reader produces the streaming events.

Performance

Pure Python 3.12 on an AMD Ryzen 4000-series laptop CPU (single thread, Windows), synthetic files (numbers vary with hardware; the test-suite only asserts generous limits):

Repairing every feature of the 100 000-polygon file (all clockwise and over-precise: 200 000 changes) and writing the result takes about 21 s; a second run finds nothing to do in 5.4 s.

How: positions are validated with C-level map/itemgetter passes; the precision test is a regex over the repr of a whole coordinate list (exact round() only runs when it matches); convex rings skip the segment search; larger rings are split into x/y-monotone chains (whose own segments cannot meet) and only chains with overlapping boxes are bisected against each other, as in GEOS, with a uniform grid for zig-zag data. Memory is bounded by the largest single feature, not the file.

How geofix compares

Use shapely/GEOS when you need full OGC validity semantics on arbitrary geometries (geofix calls shapely.make_valid for cases it cannot repair itself), and GDAL when you need to reproject or convert formats; geofix is the lightweight gate that tells you which of those you need, in a form CI understands.

Development

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

License

MIT, see LICENSE. Citation metadata: CITATION.cff.