What Is GeoJSON? Format, Geometry Types, and Production Pitfalls

GeoJSON is the JSON-based format that every modern web map can read. If you have ever drawn a polygon on a Leaflet map, styled a vector layer in MapLibre, or stored a service area in PostGIS, you have been working with GeoJSON, even if the file extension said something else.

This guide explains what GeoJSON actually is, what its geometry types mean, where it shows up in real systems, and the pitfalls that bite teams when GeoJSON files leave a developer's laptop and hit production.

What GeoJSON Really Is

GeoJSON is an open format for encoding geographic data structures, standardised by the IETF as RFC 7946 in 2016. It is a strict subset of JSON: every GeoJSON document is valid JSON, but the spec adds rules about which keys are allowed, how geometry is structured, and how coordinates are ordered.

The format is intentionally small. There are only nine top-level object types in the entire spec, and a competent developer can hold all of them in their head. That smallness is why GeoJSON has become the lingua franca of web mapping: it is easy to read, easy to write, and easy to validate.

Coordinates are always written as [longitude, latitude] (with optional altitude as a third value), and the coordinate reference system is fixed to WGS84, the same datum your phone's GPS uses. There is no negotiation, no projection metadata, no axis order debate. One datum, one ordering, everywhere.

Geometry Types

GeoJSON defines seven geometry types. The first three are the primitives:

• Point: a single coordinate, used for pins, addresses, and individual sensors
• LineString: an ordered list of two or more coordinates, used for routes, roads, and rivers
• Polygon: a closed ring of coordinates (first and last point identical), used for buildings, parcels, and admin boundaries

The next three are simply collections of those primitives:

• MultiPoint: many points in one geometry, useful for representing a chain of stores as a single feature
• MultiLineString: many line strings, used for fragmented routes or river systems
• MultiPolygon: many polygons, the right choice for any country with islands (so, almost all of them)

The seventh, GeometryCollection, can hold a mix of any of the above. The spec discourages it because most consumers handle it poorly, and you almost never need it. If you reach for GeometryCollection, it is usually a sign that the model wants to be a FeatureCollection instead.

Feature and FeatureCollection

A geometry alone is rarely useful. You need to know what it represents. That is what Feature is for: a Feature wraps a geometry with a properties object that holds arbitrary metadata.

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [4.8952, 52.3702]
  },
  "properties": {
    "name": "Amsterdam Centraal",
    "type": "station",
    "platforms": 15
  }
}

A FeatureCollection is a list of Features. Almost every real GeoJSON file you will encounter in the wild is a FeatureCollection, because real datasets have many things in them.

The crucial design choice is that properties is open. The spec says nothing about what keys it can contain or what types those values should be. That is a feature, not a bug: it means GeoJSON works for street furniture, electoral boundaries, delivery zones, and AIS ship tracks without having to extend the format. It also means consumers have to be careful: if you depend on properties.population existing, validate it yourself, because RFC 7946 will not.

Where GeoJSON Shows Up

Once you start looking, GeoJSON is everywhere in the geospatial stack:

• Map libraries: MapLibre GL, Mapbox GL, Leaflet, and OpenLayers all consume GeoJSON natively as a data source for layers
• Vector tile pipelines: tools like Tippecanoe take GeoJSON in and produce MVT (Mapbox Vector Tile) sets out
• Map style specs: the Mapbox Style Specification, used by MapLibre, references GeoJSON as a first-class source type
• Spatial databases: PostGIS, BigQuery GIS, and Snowflake all import and export GeoJSON via dedicated functions
• API outputs: most modern geocoding, isochrone, and routing APIs return GeoJSON Features for results, so the response can be dropped straight onto a map
• Route polylines: navigation responses commonly include a LineString geometry for the route, ready to render
• Data sharing: open data portals, OpenStreetMap exports, and government boundary releases default to GeoJSON when they target web users

If a tool can speak any geospatial format at all, it almost certainly speaks GeoJSON.

Pitfalls in Production

GeoJSON is forgiving on day one and unforgiving on day ninety. The traps that catch teams:

Longitude first. RFC 7946 fixes the order as [lon, lat]. Humans, addresses, and most documentation write lat, lon. Swapping them is the single most common GeoJSON bug, and your point ends up in the wrong ocean.

Polygon winding order. RFC 7946 specifies that exterior rings must be counter-clockwise and interior rings (holes) clockwise. Many older GeoJSON files ignore this. Some renderers do not care, others (notably Mapbox GL with antimeridian-crossing polygons) render the polygon as the inverse of what you wanted: a tiny island becomes a hole in the ocean covering the rest of the world.

Antimeridian handling. Geometry crossing the 180/-180 meridian needs to be split per the spec. Naive polygons drawn across the Pacific render as a thin strip wrapped the long way around the planet.

No native CRS support beyond WGS84. RFC 7946 deliberately removed the older crs member. If your data is in a national grid (British National Grid, RD New, EPSG:3857), you must reproject to WGS84 before serialising. Tools that emit non-WGS84 GeoJSON are technically non-conformant.

File size. A FeatureCollection with millions of detailed polygons can balloon to gigabytes. For browser delivery, switch to vector tiles, simplify geometry with Douglas-Peucker, or stream with newline-delimited GeoJSON (.ndjson).

Validation. Use a linter such as GeoJSONLint or the geojson-validation library in CI. Catching invalid winding order or swapped coordinates at build time is cheaper than catching it from a customer ticket.

GeoJSON in MapAtlas

GeoJSON is the default data exchange format across the MapAtlas platform. The Dynamic Maps product accepts GeoJSON sources directly for custom overlays, styling, and interactive layers, with no preprocessing required.

The Geocoding API returns matched addresses as GeoJSON Features, so a forward geocode result can be dropped straight onto a map or stored in PostGIS without remapping fields. The Isochrone API returns travel-time areas as GeoJSON polygons, which means a "places reachable in 15 minutes" query is one fetch and one addSource call away from being on screen.

GeoJSON is not glamorous. It is a small, opinionated subset of JSON with a fixed coordinate order and a handful of geometry types. But it is the format that lets every layer of a modern location stack, from spatial database to map canvas, agree on what a place is. Get the longitude order right, validate the winding, and the rest of the stack tends to take care of itself.