The GeoJSON file (.geojson, .json)

The basics

What is a GeoJSON file?

Anatomy

What's inside a GeoJSON file

A GeoJSON file is ordinary JSON with an agreed structure. Its building block is the Feature: a geometry (where) plus properties (what). Here is a small but complete file with a point and an area, part by part.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "cafe-1",
      "geometry": {
        "type": "Point",
        "coordinates": [4.895168, 52.370216]
      },
      "properties": {
        "name": "Sample Café",
        "seats": 28
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [5.13, 52.08], [5.14, 52.08],
          [5.14, 52.087], [5.13, 52.087],
          [5.13, 52.08]
        ]]
      },
      "properties": { "name": "Sample park" }
    }
  ]
}

1. 1"type": "FeatureCollection"

   The collection

   Every GeoJSON object has a type. A FeatureCollection is the usual top level: a list of features. A single Feature or a bare geometry is also a valid file.

2. 2"features": [ … ]

   The features

   An array of Feature objects, in any order.

3. 3"type": "Feature"

   A feature

   One thing on the map: a café, a road, a country. It always has a geometry and properties, either of which may be null.

4. 4"id": "cafe-1"

   An identifier

   Optional, a string or a number. Map libraries use it to update or highlight a feature.

5. 5"geometry": { "type": "Point", … }

   The geometry

   Where the feature is. One of seven geometry types, each with its own nesting of coordinates.

6. 6[4.895168, 52.370216]

   A position: longitude first

   Longitude (east-west), then latitude (north-south), in decimal degrees. This is central Amsterdam. Swapped, it would be a point in the Indian Ocean.

7. 7"properties": { … }

   The properties

   Anything you like about the feature, as a JSON object: names, numbers, booleans, lists. GeoJSON doesn't define any property names.

8. 8"type": "Polygon"

   A polygon

   An area. Its coordinates are a list of rings, each a list of positions, which is why there are three levels of brackets.

9. 9[5.13, 52.08] … [5.13, 52.08]

   A closed ring

   A ring's last position repeats its first, and a ring needs at least four positions. This outer ring runs counterclockwise: east, north, west, back south.

The classic mistake

The [longitude, latitude] trap

Under the hood

Geometry types and the rest of the structure

The rules

WGS 84, winding order and coordinate precision

Edge cases

Shapes that cross the antimeridian

{
  "type": "MultiLineString",
  "coordinates": [
    [[170.0, 45.0], [180.0, 45.0]],
    [[-180.0, 45.0], [-170.0, 45.0]]
  ]
}

Comparison

GeoJSON vs KML vs Shapefile vs TopoJSON

How to

How to view, load and convert a GeoJSON file

// Leaflet: fetch the file, then hand the data to L.geoJSON.
// (Leaflet's own functions, like setView, take [latitude, longitude].)
const leafletMap = L.map("map").setView([52.09, 5.12], 6);
L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
  attribution: "© OpenStreetMap contributors",
}).addTo(leafletMap);
fetch("https://example.com/places.geojson")
  .then((response) => response.json())
  .then((data) => L.geoJSON(data).addTo(leafletMap));

// MapLibre GL JS: a geojson source loads the address itself.
maplibreMap.on("load", () => {
  maplibreMap.addSource("places", {
    type: "geojson",
    data: "https://example.com/places.geojson",
  });
  maplibreMap.addLayer({ id: "places", type: "circle", source: "places" });
});

// OpenLayers: a vector source with the GeoJSON format.
const layer = new VectorLayer({
  source: new VectorSource({
    url: "https://example.com/places.geojson",
    format: new GeoJSON(),
  }),
});

Security

Privacy and safety

Free downloads

Sample GeoJSON files to download

Free sample GeoJSON files for testing map libraries, GIS imports, parsers and upload limits. Each one is valid RFC 7946 GeoJSON, checked with Python's geojson and shapely libraries and our own checks for coordinate ranges, precision, ring closure and winding order. Places and properties are made up; coordinates are rough city centres or invented shapes.

Loading…

What's inside sample-places.geojson

JSON has no comments, so this file explains itself through its structure. Open it in a text editor and look for these parts.

1. The FeatureCollection

   type and a features array with eight Point features, the most common shape of a GeoJSON file.

2. A foreign member

   _about is not part of GeoJSON. The standard allows extra members like it, and readers ignore them, which makes it a way to add a note to a file that can't have comments.

3. The bbox

   [-74.005974, -34.603722, 151.20929, 52.370216]: west, south, east and north edges around all eight places, from New York to Sydney.

4. Coordinates in all four quarters of the globe

   Longitude first, six decimal places. New York and Buenos Aires have negative longitudes (west), Buenos Aires, Sydney and Nairobi negative latitudes (south).

5. Properties of every JSON type

   Strings, numbers (rating, seats), booleans (wifi), an array (tags), a nested object (hours) and a null. Formats with flat tables, such as Shapefile, can't hold the array or the nested object as they are.

6. String ids

   Each feature has an id such as "sample-1". Numbers are also allowed, as in the other samples.

7. marker-color

   A simplestyle property. Viewers that support the convention colour each marker; others show it as an ordinary property.

All sample GeoJSON files

• Eight sample places around the world

  sample-places.geojson · 4.8 KB (4,903 bytes)

  A FeatureCollection of made-up cafés and shops at rough city-centre coordinates on six continents, with a bbox, string ids, properties of every JSON type and simplestyle colours.

  • Testing a map library or viewer
  • Catching swapped latitude and longitude
  DownloadOpen

• Every geometry type

  sample-geometries.geojson · 3.9 KB (3,992 bytes)

  One feature per geometry type: a Point with a height, a LineString, a Polygon with a hole, MultiPoint, MultiLineString, MultiPolygon and GeometryCollection, plus a feature with geometry: null.

  • Checking a parser supports every type
  • Testing hole and winding handling
  DownloadOpen

• Shapes cut at the antimeridian

  sample-antimeridian.geojson · 1.5 KB (1,574 bytes)

  A rectangle from 175°E to 175°W stored as a two-part MultiPolygon, and a route split into a two-part MultiLineString, with bounding boxes whose west value is greater than their east.

  • Testing rendering near 180° longitude
  • Checking bbox code handles a crossing box
  DownloadOpen

• Minimal GeoJSON: one Feature

  sample-minimal.geojson · 207 bytes

  A single Feature with a Point and a name, with no FeatureCollection around it. Valid, but some tools only accept collections.

  • Parser smoke tests
  • Checking tools accept a lone Feature
  DownloadOpen

• 100 KB GeoJSON file

  sample-100kb.geojson · 100 KB (102,400 bytes)

  555 generated points in a box over Europe, one feature per line, padded to exactly 102,400 bytes.

  • Upload and size-limit tests
  • Rendering many markers at once
  DownloadOpen

Ways to test with them

• Coordinate order: load sample-places.geojson. The markers should sit in Amsterdam, Utrecht, London, New York, Buenos Aires, Nairobi, Tokyo and Sydney. Markers in the ocean or Antarctica mean something swapped latitude and longitude.
• Holes and winding: in sample-geometries.geojson, the park polygon should show a hole where the pond is. A filled-in pond, or a shape that covers the whole map, points to winding-order trouble.
• The antimeridian: sample-antimeridian.geojson should show a small zone and a short route near Fiji, not bands stretching across the whole world.
• Upload limits: sample-100kb.geojson is exactly 102,400 bytes, so you can test a size limit right at the boundary.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Questions

GeoJSON files, frequently asked