GeoJSON

date

Mar 6, 2024

slug

geojson

status

Published

Introduction

GeoJSON is a format for encoding geographic data using JSON notation. A GeoJSON object can represent a region of space, a spatially bounded object, or a list of objects.

GeoJSON supports the following geometry types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon and GeometryCollection.

GeoJSON introduces the concept of a Feature object, which contains a geometry object and additional properties, and a FeatureCollection contains a Feature as an array.

Example GeoJSON file

For a demo Xcode project that will show how you can use this data format to display objects on a map, you can look at the link:

GeoJSON

johnnieWa1ker • Updated Apr 9, 2024

Geometry Object

A geometry object must have a type property with a type value.

A geometry object of any type other than GeometryCollection must have a coordinates property which is an array of positions. The structure of elements in this array is determined by the geometry type.

Empty coordinates arrays are interpreted as null objects.

😑

Additional properties are what we, as developers, can use to further configure a geometry object.

But it is important to remember that they do not matter to the interpreter.

Position

The fundamental geometric construct within the coordinates of a geometry object consists of:

one position in the case of Point;

an array of positions in the case of LineString or MultiPoint geometries;

an array of LineString coordinates or a linear ring in the case of Polygon or MultiLineString geometry;

an array of polygon coordinates in the case of MultiPolygon.

The position is an array of numbers. There must be two or more. The first two decimal digits are longitude and latitude, in that order. Height can be included as an optional third element.

😑

Historically, some implementations have used a fourth element containing a timestamp, but in most situations the parser will not be able to interpret these values correctly.

The line between two positions is a straight Cartesian line, the shortest between those two points in the coordinate system. In other words, every point on the line that does not intersect the anti-meridian between points (lon0, lat0) and (lon1, lat1) can be calculated through linear interpolation:

where t is a real number between 0 and 1 (corresponding to the start and end point values)

Interestingly, this line may differ markedly from a straight line on a plane and will not necessarily correspond to the shortest distance between two points on the surface of the Earth.

😑

An anti-meridian is a line of longitude 180°/-180°, located exactly opposite the main meridian (0°). It is often used as the basis for the International Date Line (IDL) as it passes through the open waters of the Pacific Ocean.

Point

For the Point type, the coordinates property represents a single position.

MultiPoint

For the MultiPoint type, the coordinates property is an array positions.

LineString

For the LineString type, the coordinates property is an array of two or more positions.

MultiLineString

For the MultiLineString type, the coordinates property is a two-dimensional array of LineString coordinates.

Polygon

To specify a polygon-specific constraint, it is useful introduce the concept of linear ring:

linear ring is a closed LineString with four or more positions.

The first and last positions are equivalent and must contain identical values;

linear ring is the boundary of a surface or the boundary of a hole in a surface;

linear ring must follow the right-hand rule regarding the area it bounds, i.e. the outer boundary positions are located counter-clockwise in the array, and the holes are located clockwise.

😑

Note: The 2008 specification does not discuss linear ring.

For backward compatibility purposes, parsers should not reject polygons that do not obey the right-hand rule.

Thus, the most popular resource for working with geoJSON geojson.io and the MKGeoJSONDecoder built into MapKit work correctly with such objects. Although you will probably spend extra time on calculations.

Although linear ring is not explicitly represented as a geometry type in GeoJSON, this results in the canonical polygon formulation:

For a Polygon type, the coordinates property must be a two-dimensional array of linear ring coordinates.

For a Polygon with more than one linear ring, the first one must be the outer ring and any others must be the inner rings. The outer ring defines the surface, and the inner ring (if present) defines the holes within the surface.

MultiPolygon

For the MultiPolygon type, the coordinates property is an array of coordinates of Polygon objects

GeometryCollection

A GeoJSON object of type GeometryCollection is a geometry object and has a special property geometries. The geometries value is an array, each element of which represents a geometry object. This array may be empty.

Heterogeneous composition of smaller geometric objects. For example, for geometry in the form of a lowercase letter, an "i" might consist of one Point and one LineString.

😑

This can be convenient when, for example, there is an area of a large city with suburbs that should be considered one object, then instead of a FeatureCollection it is better to consider using a GeometryCollection.

😑

To maximize compatibility, implementations sould avoid nested GeometryCollections, as well as GeometryCollections consisting of one or more multipart objects of type MultiPoint, MultiLineString, or MultiPolygon.

Antimeridian Cutting

😑

Any geometry that crosses the anti-meridian must be cut so that no part crosses the anti-meridian.

⚠️

MKGeoJSONDecoder strictly follows the specification, while other parsers can count meridians in 360* and draw them correctly.

When you try to read such a GeoGSON into MapKit, you will not get the expected result.

Coordinate system

The coordinate system for all GeoJSON objects is the geographic coordinate reference system using the World Geodetic defined in 1984 [WGS84] with units of longitude and latitude expressed in degrees.

The use of alternate coordinate systems has been prohibited because it causes compatibility issues.

Bounding Box

A GeoJSON object may have a bbox property, which can include coordinate range information for its geometry.

The value of bbox must be an array of length 2*n, where n is the number of dimensions represented in the content geometry with all axes of the southwesternmost point followed by all axes of the more northeastern point.

The Poles

When looking at a globe, this bounding box approximates a spherical cap bounded by the minlat latitude value.

Sources

Official Specification.