Skip to content

Jump to hands-on lesson

Overview of GeoJSON (Geo+JSON)

To begin with, JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format.

an old style example the JSON Schema for a geospatial object 

{
  "$id": "https://example.com/geographical-location.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AGIC Venue",
  "description": "A geographical coordinate where this workshop is being taught",
  "required": [ "latitude", "longitude" ],
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    }
  }
}
The location data section of the JSON later describes a point:

{
  "latitude": 34.5510,
  "longitude": -112.4471
}

GeoJSON is a format for encoding a variety of geographic data structures.

A GeoJSON Object may represent a region of space: a Geometry, a Feature, or a list of Features called a FeatureCollection.

Geometry

There are seven types of geometric shapes which can be defined in GeoJSON. Where the "type" can be any of the following:

Type Geometry
Point Point
LineString Linestring
Polygon Polygon
MultiPoint
MultiLineString MultiLineString
MultiPolygon MultiPolygon
GeometryCollection GeometryCollection

  • Point, LineString and Polygon are single type geometry objects

  • MultiPoint, MultiLineString, and MultiPolygon are multipart geometry objects

Each of the examples below represents a valid and complete GeoJSON object:

Point

GeoJSON Point Schema 
{ 
  "type": "Point",
  "coordinates": [-112.4471, 34.5510]
}

A Point geometry is represented by a single set of longitude then latitude coordinates, optionally elevation (above mean sea level) can also be included for a third axis.

LineString

GeoJSON LineString Schema 
{
  "type": "LineString",
  "coordinates": [ 
      [-112.4470, 34.5510], [-112.4695,  34.541]  
    ]
}

A Line geometry uses two or more sets of coordinate pairs to create a line or multi-line.

Polygon

GeoJSON Polygon Schema 
{
  "type": "Polygon",
  "coordinates": [
      [[-112.485, 34.529], [-112.445, 34.529], [-112.445, 34.559], [-112.485, 34.559], [-112.485, 34.529]]
    ]
}

A Polygon has at least three sets of coordinate pairs which close the shape.

MultiPoint

GeoJSON MultiPoint Schema 
{
  "type": "MultiPoint",
  "coordinates": [
      [-112.4470, 34.5510],
      [-112.4695,  34.541] 
    ]
}

A MultiPoint geometry is represented by multiple coordinate point pairs

MultiLineString

GeoJSON MultiLineString Schema 
{
  "type": "MultiLineString",
  "coordinates": [
      [[-112.44708, 34.5510], [-112.46953, 34.540924]], 
      [[-112.4471, 34.5510], [-112.4541,34.54447], [-112.46953, 34.540924]]
    ]    
}

A MultiLineString uses multiple lines which are not connected.

MultiPolygon

GeoJSON MultiPolygon Schema 
{
  "type": "MultiPolygon",
  "coordinates": [
    [
      [[-112.0, 35.0], [-112.0, 34.0],  [-113.0, 34.0],  [-113.0, 35.0],  [-112.0, 35.0]]
    ],
    [
      [[-112.50, 35.50], [-112.50, 34.50], [-113.50, 34.50],  [-113.50, 35.50], [-112.50, 35.50]]
    ],
    [
      [[-111.50, 34.50], [-111.50, 33.50], [-112.50, 33.50],  [-112.50, 34.50], [-111.50, 34.50]]
    ]
  ]
}

A MultiPolygon uses multiple lines to provide more than one set of polygons.

GeometryCollection

GeoJSON GeometryCollection 
{
  "type": "GeometryCollection",
  "geometries": [{
      "type": "Point",
      "coordinates": [-112.4471, 34.5510]
  }, {
      "type": "LineString",
      "coordinates": [
          [-112.4470, 34.5510], [-112.4695,  34.541]  
        ]
  }]
}

The GeometryCollection introduces a new set of braces {} which separate different geometries.

Feature

GeoJSON Feature 
{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [-112.4470, 34.5510]
  },
  "properties": {
    "name": "AGIC Venue"
  }
}

A Feature provides a new set of properties: which allow metadata and annotation of the geometry.

FeatureCollection

GeoJSON FeatureCollection Point 
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "Location Name" : "Prescott Resort and Conference Center"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -112.44677424430846,
          34.55109119815299
        ]
      }
    }
  ]
}

A full FeatureCollection provides us with the ability to create multiple Features

GeoJSON FeatureCollection with multiple attributes 
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            -112.44717121124268,
            34.551069106918945
          ],
          [
            -112.45414495468138,
            34.54447682068866
          ],
          [
            -112.46953010559082,
            34.540924192549795
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [
          -112.44691371917723,
          34.551210490715455
        ]
      }
    }
  ]
}

TopoJSON

TopoJSON is an extension of GeoJSON that encodes topology and is more efficient than GeoJSON.

TopoJSON use "arcs" as a way of connecting coordinate pairs, reducing the size of the file, removing duplicate coordinates, and improving performance in the browser.

TopoJSON Schema 
{
  "type": "Topology",
  "objects": 
  {
    "collection": 
    {
      "type": "Polygon",
      "arcs":[[0]]
    }
  },
  "arcs": [[[0,0],[9999,0],[0,9999],[-9999,0],[0,-9999]]],
  "transform":
  {
    "scale":[0.000004000400040004626,0.0000030003000300024037],
    "translate": [-112.485,34.529]
  },
  "bbox":[-112.485,34.529,-112.445,34.559]
}

Newline-delimited GeoJSON

Newline Delimited GeoJSON is particularly convenient for transformation and processing. Each line can be read independently, parsed, and processed, without the entire file ever having to be parsed in memory, which is great for huge files.

NLD GeoJSON remove "FeatureCollection"

NLD GeoJSON Schema 
{"type":"Feature","properties":{},"geometry":{"type":"Point","coordinates":[-112.44691371917723,34.551210490715455]}}
{"type":"Feature","properties":{},"geometry":{"type":"LineString","coordinates":[[-112.4470,34.5510],[-112.4695,34.541]]}}
{"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-112.485,34.529],[-112.445,34.529],[-112.445,34.559],[-112.485,34.559],[-112.485,34.529]]]}}

GeoJSON Webpages

geojson.io - create, view, edit GeoJSON in your browser

python-geojson

GeoJSON in ArcGIS Online

GeoJSON in BigQuery

JSON Formatter Chrome Plugin

shp2json cross-platform streaming parser for the ESRI Shapefile spatial data format.

Is GeoJSON really 'cloud native'?

Not really. NLD GeoJSON is closer to being cloud-native format than GeoJSON, but both have their short-comings.

The ubiquity of JSON on web and its recommended use in cloud-native formats is why we're teaching it. You'll learn in the later sections GeoJSON is the most common vector for querying cloud optimized data formats.

Chris Holmes recent Blog Post on 'Cloud Native Vectors'

Chris Holmes older blog post on 'Towards a Cloud-Native Geospatial standards baseline'

Hands-On

Step 1 Go to GeoJSON.io

Play around creating different GeoJSON Geometries and Feature Collections

  • Zoom into an area of interest (suggest selecting the geographic area around Prescott, AZ)

geojson.io

GeoJSON.io features a map with either OpenStreetMap or Satellite Base Layer (left), and an example GeoJSON (right) that can be edited & copy/pasted.

  • Practice creating points, lines, polygon, and a multi-polygons.

geojson.io

A Polygon Feature Collection

  • Add additional metadata to the "properties"

geojson.io

Create new metadata

In the "properties" : {} field, add additional metadata:

"type": "Feature",
      "properties": {
        "city name" : "Prescott",
        "state" : "Arizona"
      },

JSON formatting

JSON is very specific when it comes to line spacing, braces {}, quotations "" for strings, and commas , at the end of a line inside a feature.

  • Try to use a text editor with JSON formatting turned on, this will help you to debug hand-written or edited JSON and GeoJSON files that have errors.

  • Spaces between the colons : are optional but may help improve readability.

  • When you add more than one new line, you must use a comma at the end.

Step 2 Export a GeoJSON

  • Click on "Save" on the GeoJSON.io website

  • Select the GeoJSON Format option.

  • Download to your local computer in an easy to relocate folder

geojson.io

Create new metadata

Step 3 Option 1: Open the GeoJSON in QGIS

  • Open QGIS

  • In the "Layers" then "Add Layer" and then "Add Vector Layer"

  • Choose the "Source Type and select "File" for a file on your computer

  • Navigate to your downloads folder and select a downloaded .geojson in the "Source" "Vector Dataset(s)" field.

qgis_geojson_1

Loading a Layer Vector from the localhost in QGIS Layers

qgis_geojson_2

You can select which feature collection you want to load

qgis_geojson_3

After the GeoJSON is loaded you can view it in the display

Loading GeoJSON from HTTP(S)

GeoJSON can be read directly from the web, without downloading them.

Here we're going to use the USGS 3DEP lidar boundaries layer which is hosted on GitHub:

https://github.com/hobuinc/usgs-lidar/raw/master/boundaries/resources.geojson

Using GitHub to view GeoJSON

Note how resources.geojson is visible as a leaflet map directly in GitHub.

GeJSON can also be visualized in VS Code and Jupyter Lab the same way using map extensions for Folium and Leaflet.

qgis_3dep_1

Loading a Layer Vector from an HTTP(s) in QGIS Layers

qgis_3dep_2

QGIS can open the GeoJSON without downloading first.

Troubleshooting import HTTPS GeoJSON layers in QGIS

Change The Environmental Setting Variables In QGIS

  1. Go to Setting Menu >> Options

    In the Options window:

    Go to System

  2. Expand Environment:

    Check the box to Use custom vairables

  3. Then add the following variables

    variable 1: GDAL_HTTP_USERAGENT

    variable value 1: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36

    variable 2: GDAL_HTTP_UNSAFESSL

    variable value 2: YES

  4. Restart QGIS and them try to add the GeoJSON file link again.

Step 3 Option 2: Open the GeoJSON in ArcGIS Online

Log into ArcGIS Online and select the MapViewer

https://ua-gisug.maps.arcgis.com/apps/mapviewer/index.html

arcgis_3dep_2

ArcGIS Online can load GeoJSONs from an HTTP(s)

arcgis_3dep_2

The same USGS 3DEP Boundaries in ArcGIS Online Map Viewer

Open the GeoJSON in an IDE (like VS Code or Jupyter)

VS Code can be used to view and edit JSON and GeoJSON

vscode_geojson_1

VS Code can be used to view and edit JSON and GeoJSON

vscode_geojson_2

VS Code Extensions can be used to render the GeoJSON

vscode_geojson_3

There are a variety of extensions for both GeoJSON and Leaflet

Step 4 (Optional): Convert a SHP file to GeoJSON

QGIS can export .shp as .geojson directly.

qgis_export_1

"Export" and "Save Feature As"

qgis_export_2

If you plan to use your .geojson in a web map, set the CRS to EPSG:4326 - WGS84 and the COORDINATE_PRECISION down to 4-6 decimals (<1-4 ft GSD).

Additional Reading

Applied Use of JSON, GeoJSON, JSON-LD, SPARQL, and IPython Notebooks for Representing and Interacting with Small Datasets - by Sebastian Heath

Last update: 2022-11-15