Docs
Docs › Formats › GeoJSON

GeoJSON

GeoJSON is a simple, human-readable format for geospatial vector data. It is used by many web mapping APIs, although formats like TopoJSON, FlatGeobuf, GeoParquet, and vector tiles have replaced it for specific use cases such as large-file efficiency, cloud-optimized access, and tiled rendering.

File extensions: .json, .geojson · Read: ✓ · Write: ✓ · Multi-layer: one layer per file (combinable)

CLI examples

mapshaper input.shp -o provinces.geojson
mapshaper input.shp -o precision=0.001 prettify provinces.geojson

Format-specific input options

  • id-field= — import the value of each Feature's top-level id property into a data field of the given name.
  • json-path= — for files where the GeoJSON object is nested inside a larger JSON document, e.g. json-path=data/regions.

Format-specific output options

  • precision= — round coordinates to a fixed precision. This is a simple way to reduce file size.
  • prettify — pretty-print the JSON with line breaks and indentation.
  • id-field= — promote one or more attribute fields to the GeoJSON id property (comma-separated; first matching field per layer is used).
  • bbox — add a bbox array to the top-level FeatureCollection.
  • extension= — override the default .json extension (e.g. extension=geojson).
  • combine-layers — merge multiple layers into a single GeoJSON output file (geometries are kept separate as Features, attribute schemas are unioned).
  • geojson-type= — output a Feature, FeatureCollection or bare GeometryCollection instead of the default FeatureCollection.
  • no-null-props — emit "properties": {} instead of "properties": null for Features without attributes.
  • hoist= — promote one or more properties out of the properties object onto the Feature itself. Useful for non-standard consumers like tippecanoe.
  • gj2008 — emit pre-RFC-7946 GeoJSON (clockwise outer rings).
  • reverse-winding — reverse the winding order of polygon rings on export.
  • ndjson — write one Feature per line as newline-delimited JSON (works with the json records family of options as well).
  • id-prefix= — prefix layer/feature ids when exporting multiple layers.

Practical notes

  • The GeoJSON spec states that GeoJSON uses WGS-84 coordinates (the lat-long coordinate system used by GPS), but Mapshaper will also export GeoJSON files with projected coordinates.
  • Coordinates are emitted at full precision — consider precision= to reduce file size. precision=0.0001 equates to ~11 m at the equator, ~8 m in New York City, and ~6 m in Reykjavík, Iceland.
  • Polygon ring winding follows RFC 7946 (CCW outer, CW holes); use reverse-winding to write CW outer rings and CCW holes.
  • Output is minified by default; pass prettify for human-readable JSON.
  • If you are loading the data into a web map, see Preparing data for D3 and web maps for notes on WGS84, projected coordinates, polygon winding and D3 rendering.
  • If you are loading the data into a web map and you want the smallest possible file size, consider TopoJSON as an alternative to GeoJSON. For datasets with shared boundaries, file sizes are often a fraction of the equivalent GeoJSON size.
  • precision= rounding can introduce sliver overlaps at boundaries. Pair it with fix-geometry if downstream tools are strict.

Reading very large GeoJSON files

Mapshaper uses a custom GeoJSON parser, so it is not constrained in the same way as tools that must load an entire file into a JavaScript string and call JSON.parse().

In both Node.js and browsers, JSON.parse() workflows hit string-size and memory limits much earlier than the raw file-size limit. In practice, browser imports can fail well below 1 GB, and large files may crash the tab. If a GeoJSON is too big for the web app, use the CLI (or mapshaper-xl) instead.

mapshaper-xl can handle multi-gigabyte files. It allocates 8 GB of memory by default, but you can assign more.

mapshaper-xl huge.geojson -info
mapshaper-xl 32gb huge.geojson -simplify 5% -o huge.topojson

External resources

Edit this page on GitHub