Formats · 6 min read

What is GeoJSON?

GeoJSON is a plain-text way of writing down points, lines and areas on the Earth, together with the facts attached to them. It is the format web maps speak natively, and the one most GIS files end up converted to when they need to travel.

A file you can read

GeoJSON is ordinary JSON — the same curly-bracket notation every web API uses — with a few agreed names. Open one in any text editor and you can read it. That is its main advantage over binary formats like the Shapefile: nothing is hidden, nothing needs a special library to inspect, and a single file holds everything.

The current definition is RFC 7946, published by the IETF in 2016. It replaced an informal 2008 specification, and it tightened several rules that older files often break. When software says it "supports GeoJSON", RFC 7946 is what it should mean.

The three building blocks

Almost every GeoJSON file you meet is a FeatureCollection: a list of Features, each made of a geometry (the shape) and properties (the attributes).

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [28.0473, -26.2041] },
      "properties": { "name": "Johannesburg CBD", "elevation_m": 1753 }
    }
  ]
}

Properties can hold any JSON value — text, numbers, true/false, lists, even nested objects. There is no fixed schema, so two features in the same file can carry different fields. That flexibility is convenient, but it is also why a GeoJSON file converted to a Shapefile sometimes loses columns: the Shapefile needs one fixed table.

The seven geometry types

A polygon ring must be closed: its last coordinate repeats its first. RFC 7946 also asks that outer rings run anticlockwise and holes run clockwise. Most readers tolerate the wrong winding, but some renderers fill a polygon inside-out when it is reversed — if a shape covers the whole world except your site, winding is the reason.

Longitude first — always

GeoJSON writes positions as [longitude, latitude] — east–west first, then north–south. That is the opposite of how people say coordinates out loud and how Google Maps shows them. Swapping the two is the most common GeoJSON bug there is. A Johannesburg point written as [-26.2, 28.0] lands in the Indian Ocean far to the east of Madagascar.

RFC 7946 also fixes the coordinate system: every GeoJSON file is in WGS 84 longitude and latitude, in decimal degrees. The old "crs" member that let files declare another system was removed. If your file contains numbers like [604215.3, 7101833.9], it is in a projected system such as UTM, and it is not valid GeoJSON — it needs reprojecting to degrees before a web map will place it correctly.

How many decimals you need

Many exporters write fifteen decimal places, which describes a position to a fraction of an atom and roughly doubles the file size for no benefit. Six decimals is about 11 centimetres at the equator — enough for survey pegs and building corners. Five decimals (about 1.1 m) is fine for most mapping. Trimming precision is the single easiest way to shrink a GeoJSON file.

When GeoJSON is the right choice

• Use it for web maps (Leaflet, MapLibre, Mapbox, OpenLayers), for APIs, for version control in Git, and for handing a layer to someone whose software you do not know.
• Avoid it for very large datasets — it has no spatial index, so a 500 MB file must be read in full before anything draws. GeoPackage or FlatGeobuf are better there.
• Avoid it when you need to keep a projected coordinate system exactly as surveyed, for example a cadastral layer in a local transverse Mercator system.

Quick checklist

1. Coordinates are longitude, latitude — and within ±180 and ±90.
2. Polygon rings close on their first point.
3. No more than six decimal places.
4. No "crs" member and no projected coordinates.
5. The file validates — RICE's converter checks all of the above when it reads a layer.

Published by RICE, a LocalID Pty Ltd product. Questions or corrections: info@cartesiasa.com.