GeoJSON (Geographic JavaScript Object Notation) Reader/Writer

GeoJSON is a standard for encoding spatial data in JSON structured text. FME currently supports the GeoJSON Format Specification Revision 1.0, which is available at https://geojson.org.

Overview

GeoJSON encodes both geometry and feature information into objects. It also provides support for geometry and feature collections.

GeoJSON represents geometry with a single JSON object.

The type of geometry is identified by the value of the type key, which must be present in a GeoJSON object. Possible values of the type key are Point, LineString, Polygon, MultiPoint, MultiLineString, and MultiPolygon. The geometry coordinates are stored in the coordinates key of the geometry object. 

{
	“type”:”LineString”,
	“coordinates”:[ [100.0, 0.0], [101.0, 1.0] ]
}

 

An aggregate geometry is represented by a GeoJSON object which has a type key with value GeometryCollection.

A GeometryCollection object must contain a geometries key whose value is an array containing GeoJSON geometry objects.

{
	“type”:”GeometryCollection”,
	“geometries”: [
		{
			“type”:”LineString”,
			“coordinates”:[ [100.0, 0.0], [101.0, 1.0] ]
		},
		{
			“type”:”MultiPoint”,
			“coordinates”: [ [100.0, 0.0], [101.0, 1.0] ]
		}
	]
}

 

A feature is represented by a GeoJSON object which has a type key with value Feature.

A Feature object may contain a geometry key whose value is a GeoJSON geometry object or a GeoJSON GeometryCollection object. A Feature object may also contain a properties key whose value is an object containing attribute names and values.

{
	“type”:”Feature”,
	“geometry”:{
		“type”:”MultiPoint”,
		“coordinates”: [
			[102.0, 2.0],
			[103.0, 3.0]
		]
	}
}

 

A collection of features is represented by a GeoJSON object which has a type key with value FeatureCollection.

A FeatureCollection must contain a features key whose value is any array containing GeoJSON Feature objects.

{
	“type”:”FeatureCollection”,
	“features”: [
		{
			“type”:”Feature”,
			“geometry”:{
				“type”:”MultiPoint”,
				“coordinates”: [
					[102.0, 2.0],
					[103.0, 3.0]
				]
			}
		},
		{
			“type”:”Feature”,
			“geometry”:{
				“type”:”GeometryCollection”,
				“geometries”: [
					{
						“type”:”LineString”,
						“coordinates”:[ [100.0, 0.0], [101.0, 1.0] ]
					},
					{
						“type”:”MultiPoint”,
						“coordinates”: [ [100.0, 0.0], [101.0, 1.0] ]
					}
				]
			}
		}
	]
}

 

Coordinate systems are supported in GeoJSON through the use of a crs key.

If a GeoJSON object has the crs key, it is assumed to represent the coordinate reference system of the included features or geometries.

The value of the crs key must be an object containing both a type and a properties key.

  • If the crs key is absent, the projection is assumed to be LL84.
  • If the type key is set to "name" , then the feature(s) will be tagged with an OGC CRS URN.
  • If the type key is set to "link", it means that the href key is specified as a URL or a file path that contains the CRS info. In this case, the href parameter will be stored in the json_crs_url attribute, with its corresponding type in the json_crs_url_type attribute.
{
	“type”:”Feature”,
	“crs”: {
		“type”: “name”,
		“properties”: { “name”: “urn:ogc:def:crs:OGC:1.3:CRS84” }
	},
	“geometry”:{
		“type”:”Point”,
		“coordinates”: [100.0, 0.0]
	}
}
{
	“type”:”Feature”,
	“crs”: {
		“type”: “link”,
		“properties”: {
			“href”: “http://spatialreference.org/ref/epsg/2001/proj4/”,
			“type”: “proj4”
		}
	},
	“geometry”:{
		“type”:”Point”,
		“coordinates”: [100.0, 0.0]
	}
}

Reader Overview

The GeoJSON reader is capable of reading several different GeoJSON structures.

  • If the base JSON element is a GeoJSON geometry object, then the reader will return a single FME feature with the given geometry. If the base JSON element is a GeoJSON GeometryCollection object, then the reader returns a single FME feature with an aggregate geometry. In both cases, the FME feature type will be GeoJSON.
  • If the base JSON element is a GeoJSON Feature object, then the GeoJSON reader will return a single FME feature. The feature geometry will be taken from the geometry key of the Feature object, and the feature attributes will be taken from the properties key of the Feature object. If the base JSON element is a GeoJSON FeatureCollection object, then the GeoJSON reader will return an FME feature for each element of the features array of the FeatureCollection object. In both cases, the FME feature type for each feature will be GeoJSON.
  • If the base JSON element is an array, then any GeoJSON objects in the array are converted into FME features as described above.
  • If the base JSON element is an object, but not a GeoJSON object, then any value which is a GeoJSON object is converted into FME features as described above, with the exception that the FME feature type is the key name of the corresponding GeoJSON object.

Reader Coordinate Systems

The GeoJSON reader currently supports coordinate systems in EPSG, OGC URN, or URL format as described in the Overview.

Writer Overview

By default, the GeoJSON writer outputs all features into a single FeatureCollection object. If there are multiple feature types, they will all be combined into this FeatureCollection object.

The writer can be configured to output an array of FeatureCollection objects – one per feature type – or an object which has feature types as keys and FeatureCollection objects as values.

Writer Coordinate Systems

The GeoJSON writer currently supports coordinate systems in EPSG, OGC URN, or URL format as described in the Overview.

To write a URL coordinate system, ensure that the json_crs_url and json_crs_url_type attributes are complete and that no coordinate system is set on the feature.

If a coordinate system is specified that violates the GeoJSON specifications, the coordinate system will be reprojected to LL84.

If no coordinate system is available, no coordinate system will be output. However, it is important to note that the specifications state that GeoJSON objects not specifically tagged with a coordinate reference system are assumed to be the LL84. If multiple coordinate systems exist among features, the first feature will be used to determine the coordinate system for the feature collection.

Writer Geometry

FME feature geometry is written out in a GeoJSON geometry object as the value of the geometry key in a Feature type GeoJSON object. Because GeoJSON only supports linear geometry, arcs will be stroked to lines, and ellipses will be stroked to polygons. Also, paths are simplified to a single line, and an FME feature with text geometry only has its location written; the text value is ignored.

The value of the geometry key for an FME feature with aggregate geometry will be a GeometryCollection object, whose geometries key will have an array of GeoJSON geometry objects as its value.