GeoJSON

On this page 7

GeoJSON is an open, JSON-based format for encoding geographic data: points, lines, polygons and collections of them, each optionally paired with descriptive properties. Among data formats, it is the most widely used text format for exchanging vector geometry between web maps, APIs and geographic information systems.

The format is defined by RFC 7946, published by the Internet Engineering Task Force in 2016, which replaced an earlier community specification from 2008. Because every GeoJSON file is valid JSON, any language with a JSON parser can read it, which explains its dominance in web mapping.

How a GeoJSON document is structured

A GeoJSON document is a single JSON object whose `type` member declares what it represents. The three top-level object kinds are a Geometry, a Feature and a FeatureCollection, and most real files are FeatureCollections.

A Feature combines a geometry member with a properties member, which is an arbitrary JSON object holding attributes such as a name, population or road class. A Feature may also carry an optional id. A FeatureCollection holds an array of Features under the features member, comparable to a table in which each row has a shape.

Object typeRequired membersPurpose
Geometrytype, coordinatesA shape without attributes
Featuretype, geometry, propertiesOne shape plus its attributes
FeatureCollectiontype, featuresA list of Features, like a map layer
Top-level GeoJSON object types

An optional `bbox` member can record the bounding box of any object as an array of minimum and maximum coordinates, which helps clients decide quickly whether data falls inside a map view.

Geometry types and coordinate rules

GeoJSON defines seven geometry types, all built from positions. A position is an array of numbers in the order longitude, latitude, with an optional third value for altitude.

Geometry typeCoordinates structureTypical feature
PointOne positionShop, sensor, address
MultiPointArray of positionsSet of tree locations
LineStringArray of two or more positionsRoad, river, GPS track
MultiLineStringArray of LineString arraysBus route with branches
PolygonArray of linear ringsBuilding, lake, parcel
MultiPolygonArray of Polygon arraysCountry with islands
GeometryCollectionArray of geometries under geometriesMixed shapes in one object
GeoJSON geometry types

A linear ring is a closed line with at least four positions, where the first and last positions are identical. The first ring of a Polygon is the exterior boundary, and any further rings are holes. RFC 7946 specifies the right-hand rule: exterior rings run counterclockwise and holes run clockwise, although parsers are expected to accept either winding order.

Under RFC 7946, all coordinates use the WGS 84 geographic reference system in decimal degrees. The older 2008 specification allowed a crs member for other projections, but the current standard removed custom coordinate systems, which simplifies interoperability. The specification also recommends that coordinate precision not exceed six decimal places, roughly 10 centimeters, because extra digits add file size without real accuracy.

GeoJSON compared with other geospatial formats

GeoJSON trades compactness and performance for readability and universal support. Its closest relatives are the plain JSON and NDJSON formats it builds on, and dedicated geospatial formats that store geometry more efficiently.

FormatEncodingStrengthLimitation
GeoJSONText, JSONHuman-readable, native to web mapsLarge files, slow to parse at scale
ShapefileBinary, multiple filesLegacy support in desktop GISColumn names limited, several files per layer
KMLText, XMLStyling and 3D globe displayVerbose, styling mixed with data
TopoJSONText, JSON extensionShared borders stored once, smallerRequires conversion for most tools
GeoPackageBinary, SQLite databaseMany layers, indexes, large dataNot directly streamable to browsers
GeoParquetBinary, columnarFast analytics on huge datasetsNot human-readable
GeoJSON and alternative vector data formats

A streaming variant, GeoJSON Text Sequences described in RFC 8142, and the related practice of storing one Feature per line in NDJSON style, allow record-by-record processing of very large collections without loading a whole file into memory.

Practical use and tooling

GeoJSON is the default exchange format for web mapping libraries and many location APIs. JavaScript map libraries load it directly as a layer, spatial databases can export query results as GeoJSON, and code hosting platforms render GeoJSON files as interactive maps.

Choosing GeoJSON is a matter of data volume and audience. The following decision guide reflects common practice.

SituationRecommended choiceReason
Small to medium layer for a web mapGeoJSONLoads directly, easy to debug
API returning location resultsGeoJSONSelf-describing, widely parsed
Millions of features for analysisGeoParquet or GeoPackageCompression and indexing
Large interactive map at many zoom levelsVector tilesOnly visible data is transferred
Projected coordinates must be preservedGeoPackageSupports any reference system
When to choose GeoJSON

Media type `application/geo+json` identifies GeoJSON in HTTP responses, and the usual file extensions are .geojson and .json.

Common mistakes with GeoJSON

Most GeoJSON errors come from coordinate order and geometry validity, not from JSON syntax. These problems often pass a JSON validator yet produce empty or misplaced maps.

  • Swapping latitude and longitude: writing latitude first places features in the wrong location, often in the ocean.
  • Using projected coordinates: values in meters from a national grid are invalid under RFC 7946, which expects WGS 84 degrees.
  • Unclosed rings: a Polygon whose last position differs from its first is invalid.
  • Excessive precision: fifteen decimal places multiply file size without adding accuracy.
  • Antimeridian crossing: shapes spanning 180 degrees longitude should be split, or they wrap around the globe.
  • Nested attribute objects: deeply structured properties are valid but many GIS tools flatten or reject them.

The simple explanation

GeoJSON is a plain-text way to describe places on a map. Each place is written as a shape, such as a dot, a line or an outlined area, plus a short list of facts about it, such as its name.

Imagine a guest list where each entry also includes directions to where the guest lives. Because the format is simple text that computers already understand, almost any mapping app can read it and draw the shapes instantly.

How it is used in practice

A city transport office publishes the locations of its 450 bike-sharing stations on a public map. A nightly job queries the station database and writes a FeatureCollection in which each Feature is a Point with longitude and latitude to six decimal places, plus properties for station name, capacity and available bikes.

The resulting file is about 120 kilobytes after compression, small enough for the city website to load it directly into a web map library. A second layer holds cycling lanes as LineString features, and district boundaries are stored as MultiPolygon features.

Because the same file is offered through an open endpoint with the application/geo+json media type, independent developers build route-planning apps on it without any conversion. The outcome is one dataset serving the official map and third-party tools at once.