Difference between revisions of "GeoJSON draft version 6"

From GeoJSON
Jump to: navigation, search
(Added Non-geographic examples)
 
(misplaced brace)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
  
GeoJSON is a data-interchange format for a variety of geographic data structures.  GeoJSON can be used to represent a geometry, a feature, a collection of geometries, or a collection of features.  The geometry types supported in GeoJSON are Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection, and Box.  Features in GeoJSON are geometry objects with additional properties.  A geometry collection represents a list of geometries and a feature collection represents a list of features.
+
GeoJSON is a data-interchange format for a variety of geographic data structures.  GeoJSON can be used to represent a geometry, a feature, a collection of geometries, or a collection of features.  The geometry types supported in GeoJSON are Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon and GeometryCollection.  Features in GeoJSON are geometry objects with additional properties.  A geometry collection represents a list of geometries and a feature collection represents a list of features.
  
 
A complete GeoJSON data structure is always an object (in JSON terms).  In GeoJSON, an ''object'' consists of a collection of name/value pairs - also called ''members''.  For each ''member'', the name is always a ''string''.  Member ''values'' are either a ''string'', ''number'', ''object'', ''array'' or one of the literals: '''true''', '''false''', and '''null'''.  An ''array'' consists of elements where each element is a ''value'' as described above.  
 
A complete GeoJSON data structure is always an object (in JSON terms).  In GeoJSON, an ''object'' consists of a collection of name/value pairs - also called ''members''.  For each ''member'', the name is always a ''string''.  Member ''values'' are either a ''string'', ''number'', ''object'', ''array'' or one of the literals: '''true''', '''false''', and '''null'''.  An ''array'' consists of elements where each element is a ''value'' as described above.  
Line 15: Line 15:
 
# The GeoJSON object may have any number of members (name/value pairs).
 
# The GeoJSON object may have any number of members (name/value pairs).
 
# The GeoJSON object must have a member with the name "type".  This member's value is a string that determines the type of the GeoJSON object.
 
# The GeoJSON object must have a member with the name "type".  This member's value is a string that determines the type of the GeoJSON object.
## The value of the type member must be one of: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", "GeometryCollection", "Box", "Feature", or "FeatureCollection". "type" must be lower case, the case of the type member values must be as shown here.
+
## The value of the type member must be one of: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", "GeometryCollection", "Feature", or "FeatureCollection". "type" must be lower case, the case of the type member values must be as shown here.
## A geometry is a GeoJSON object where the type member's value is one of: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", "GeometryCollection", or "Box". The case of the type member values must be as shown here.
+
## A geometry is a GeoJSON object where the type member's value is one of: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", or "GeometryCollection". The case of the type member values must be as shown here.
### In addition to the type member, any GeoJSON object that represents a single geometry (referred to as a geometry object below) must have a member with the name "coordinates".  This does not apply to geometry objects of type "GeometryCollection". The value of the coordinates member is always an array (referred to as the coordinates array below). The structure for the elements in this array are determined by the type of geometry.
+
### A GeoJSON geometry object of any type other than "GeometryCollection" must have a member with the name "coordinates". The value of the coordinates member is always an array (referred to as the coordinates array below). The structure for the elements in this array are determined by the type of geometry.
#### For type "Point", each element in the coordinates array is a number representing the point coordinate in one dimension. The order of elements follows x, y, z order (or longitude, latitude, elevation for coordinates in decimal degrees).
+
#### For type "Point", each element in the coordinates array is a number representing the point coordinate in one dimension. There must be at least two elements, and may be more. The order of elements must follow x, y, z order (or longitude, latitude, altitude for coordinates in a geographic coordinate reference system). Any number of additional dimensions are allowed, and interpretation and meaning of these coordinates is beyond the scope of this specification.
 
#### For type "MultiPoint", each element in the coordinates array is a coordinates array as described for type "Point".
 
#### For type "MultiPoint", each element in the coordinates array is a coordinates array as described for type "Point".
 
#### For type "LineString", each element in the coordinates array is a coordinates array as described for type "Point".  The coordinates array for a LineString must have two or more elements.  A LinearRing is a special case of type LineString where the first and last elements in the coordinates array are equivalent (they represent equivalent points).  Though a LinearRing is not explicitly represented as a GeoJSON geometry type, it is referred to in the Polygon geometry type definition.
 
#### For type "LineString", each element in the coordinates array is a coordinates array as described for type "Point".  The coordinates array for a LineString must have two or more elements.  A LinearRing is a special case of type LineString where the first and last elements in the coordinates array are equivalent (they represent equivalent points).  Though a LinearRing is not explicitly represented as a GeoJSON geometry type, it is referred to in the Polygon geometry type definition.
Line 24: Line 24:
 
#### For type "Polygon", each element in the coordinates array is a coordinates array as described for type "LineString".  Furthermore, each LineString in the coordinates array must be a LinearRing.  For Polygons with multiple LinearRings, the first must be the exterior ring and any others must be interior rings or holes.
 
#### For type "Polygon", each element in the coordinates array is a coordinates array as described for type "LineString".  Furthermore, each LineString in the coordinates array must be a LinearRing.  For Polygons with multiple LinearRings, the first must be the exterior ring and any others must be interior rings or holes.
 
#### For type "MultiPolygon", each element in the coordinates array is a coordinates array as described for type "Polygon".
 
#### For type "MultiPolygon", each element in the coordinates array is a coordinates array as described for type "Polygon".
#### For type "Box", the coordinates array must have two elements.  Each element in the coordinates array is a coordinates array as described for type "Point".  The first element in the array represents the minx, miny corner of the box, and the second point represents the maxx, maxy corner of the box.
+
### A GeoJSON geometry object with type "GeometryCollection" is a geometry object which represents a collection of geometry objects.
#### A GeoJSON object with type "GeometryCollection" is a geometry object which represents a collection of geometry objects.
+
#### A geometry collection must have a member with the name "geometries". The value corresponding to "geometries" is an array. Each element in this array is a GeoJSON geometry object.
##### An object of type "GeometryCollection" must have a member with the name "geometries". The value corresponding to "geometries" is an array. Each element in this array is a geometry object as defined above.
+
 
## A GeoJSON object with the type "Feature" represents a geometry with additional properties (referred to as a feature object below).  
 
## A GeoJSON object with the type "Feature" represents a geometry with additional properties (referred to as a feature object below).  
 
### A feature object must have a member with the name "geometry".  The value of the geometry member is a geometry object as defined above or a JSON null value (as in <code>{"type":"Feature", "properties": {"title":"empty"}, "geometry":null}</code>).
 
### A feature object must have a member with the name "geometry".  The value of the geometry member is a geometry object as defined above or a JSON null value (as in <code>{"type":"Feature", "properties": {"title":"empty"}, "geometry":null}</code>).
 
### A feature object must have a member with the name "properties".  The value of the properties member is an object (any JSON object).
 
### A feature object must have a member with the name "properties".  The value of the properties member is an object (any JSON object).
 +
### If a feature has a commonly used identifier, that identifier should be included as a member of the feature object with the name "id".
 
## A GeoJSON object with the type "FeatureCollection" represents a collection of feature objects.
 
## A GeoJSON object with the type "FeatureCollection" represents a collection of feature objects.
 
### An object of type "FeatureCollection" must have a member with the name "features".  The value corresponding to "features" is an array.  Each element in the array is a feature object as defined above.
 
### An object of type "FeatureCollection" must have a member with the name "features".  The value corresponding to "features" is an array.  Each element in the array is a feature object as defined above.
# A GeoJSON object without a member named "crs" contains geometries in a geographic coordinate reference system, using the WGS84 datum, and with units in decimal degrees. A GeoJSON object may have a member with the name "crs". If a GeoJSON object has a member named "crs", it is assumed to represent the coordinate reference system of the included geometry or geometries.
+
# '''''Coordinate Reference Systems''''': The coordinate reference system (CRS) of a GeoJSON object is determined by its "crs" member. If an object has no "crs" member, its parent object's "crs" member may be acquired. If no CRS can be so acquired, the default CRS shall apply to the GeoJSON object.
## The value of a member named "crs" must be an object. This object must have at least two named members: "type" and "properties". The value of the member named "type" must be a string.  The value of the member named "properties" must be an object.  This specification defines no further requirements for the structure of these objects.  Instead, a convention is offered.
+
## '''Default coordinate reference system''': The default is a geographic coordinate reference system, using the WGS84 datum, and with longitude and latitude units of decimal degrees.
### To use EPSG codes to describe coordinate reference system, the "crs" member should have the following structure: <code>"crs": {"type": "EPSG", "properties": {"code": 2805}}</code>. "crs", "type", and "properties" must be lower case. When used as a value, "EPSG" must be upper case.
+
## '''The "crs" member''': The value of a member named "crs" must be an object (referred to as the CRS object below) or null. If the value of CRS is null, it means that no CRS can be assumed.
#### EPSG codes must not be used if 1) the EPSG-defined axes order of the crs is not lon, lat (for a geographic crs) or easting, northing (for a projected crs), or 2) the EPSG-defined coordinate representation of a geographic crs is not decimal degrees (e.g. if is degrees/minutes/seconds).  Instead, such data should use OGC URNs that specify the ordering to be lon, lat (or easting, northing) and/or the coordinate representation to be decimal degrees.
+
### '''The CRS object''': A CRS object has two mandatory members: "type", and "properties".
### To use an OGC URN (http://portal.opengeospatial.org/files/?artifact_id=16339) as a unique identifier of a coordinate reference system, the "crs" member should have the following structure:
+
### ''The "type" member'': The value of this required member must be a string, indicating the type of CRS object.
#### The "type" member must be "OGC".
+
### ''The "properties" member'': The value of this required member must be an object.
#### The properties member must be an object with one member, "urn", that specifies an OGC URN such as "urn:ogc:def:crs:OGC:1.3:CRS84".
+
## '''CRS object types''': This specification defines two types of CRS objects.
#### The URN "urn:ogc:def:crs:OGC:1.3:CRS84" should be used in place of EPSG:4326 to indicate decimal degrees using the WGS84 datum in lon, lat order: the CRS object in this case would look like: <code>{"type":"OGC", "properties": {"urn":"urn:ogc:def:crs:OGC:1.3:CRS84"}}</code>
+
### ''Named'': A CRS object may indicate a coordinate reference system by name. The value of its "properties" member must be an object containing a "name" member. The value of that "name" member must be a string identifying a coordinate reference systems. OGC CRS URNs such as "urn:ogc:def:crs:OGC:1.3:CRS84" shall be preferred over legacy identifiers such as "EPSG:4326".
#### Unless your data falls under one of the exceptions above, you should prefer EPSG codes to OGC URNs.
+
#### Example:<pre>"crs": {"type": "name", "properties": {"name": "urn:ogc:def:crs:OGC:1.3:CRS84"}}</pre>
### To use a URL as a unique identifier to a coordinate reference system, the "crs" member should have the following structure:  
+
### ''Linked'': A CRS object may link to CRS parameters on the Web. In this case the value of its "properties" member must be a Link object (see below).
#### The properties object should contain one member: "url", that specifies a URL for the spatial reference that can be dereferenced by the client.  
+
#### ''The Link object'': A link object has 1 required member: "href", and 1 optional member: "type". The link object is similar to Atom/HTML/RSS links.
#### An optional member, "type", is recommended, specifying the type of information available at the URL. This may be any string: suggestions are "proj4", "ogcwkt", "esriwkt", though others can be used.  Applications may use this "type" member to determine the type of information that is available at the URL.
+
##### The "href" member: The value of this required member must be a dereferenceable URI.
#### The specification does not offer any information on how to convert this URL into a spatial reference system: use is intended to provide users the ability to define their references outside the EPSG namespace *only*.
+
##### The "type" member: The value of this optional member must be a string that hints at the format used to represent CRS parameters at the provided URI. Suggested values are: "proj4", "ogcwkt", "esriwkt", though others can be used.
 +
#### Example:<pre>"crs": {"type": "link", "properties": {"href": "http://example.com/crs/42", "type": "proj4"}}</pre>Relative links may be used to direct processors to CRS parameters in an auxiliary file:<pre>"crs": {"type": "link", "properties": {"href": "data.prj", "type": "proj4"}}</pre>
  
 
== Examples ==
 
== Examples ==
Line 135: Line 136:
 
         }
 
         }
 
     ]
 
     ]
}
 
 
==== Box ====
 
Coordinates of a Box are an array of two Point coordinates.  The first element in the array represents the minimum corner point (minx, miny).  The second element in the array represents the maximum corner point (maxx, maxy).
 
{
 
    "type": "Box",
 
    "coordinates": [[100.0, 0.0], [101.0, 1.0]]
 
 
  }
 
  }
  
Line 224: Line 218:
 
  }
 
  }
  
Same feature collection, with a member named "crs" to represent the coordinate reference system.
+
Same feature collection, with a member named "crs" to represent the coordinate reference system. Note that because this example uses EPSG:4326, it must specify coordinate_order, since EPSG:4326 defines the coordinate order to be "lat, lon", which is the opposite of the GeoJSON default.
 +
 
 
  {
 
  {
 
     "type": "FeatureCollection",
 
     "type": "FeatureCollection",
 
     "crs": {
 
     "crs": {
       "type": "URL",
+
       "type": "EPSG",
 
       "properties": {  
 
       "properties": {  
           "url": "http://spatialreference.org/ref/epsg/2001/proj4/",
+
           "code": 4326,
           "type": "proj4"
+
           "coordinate_order": [1, 0]
 
       }
 
       }
 
     },
 
     },
Line 320: Line 315:
 
         "atom:description": "This content is also valid GeoJDIL."
 
         "atom:description": "This content is also valid GeoJDIL."
 
     }
 
     }
 +
}
 +
 +
=== Including Bounding Box/Envelope ===
 +
 +
To include information on the coordinate range for geometries, features, or feature collections, it is suggested that member named bbox be included in a GeoJSON object.  The value of the bbox member should be a 2*n item array where n is the number of dimensions represented in the contained geometries and lowest values for all axes are followed by highest values.  Axes order of a bbox follows axes order of geometries.  In addition, the spatial reference for the bbox is assumed to match the spatial reference for the GeoJSON object of which it is a member.
 +
 +
Example of a bbox member on a polygon geometry
 +
{
 +
  "bbox": [-180, -90, 180, 90],
 +
  "type": "Polygon",
 +
  "coordinates": [
 +
      [ [-180, 10], [20, 90], [180, -5], [-30, -90] ]
 +
  ]
 +
}
 +
 +
Example of a bbox member on a feature collection (with a bbox on each feature as well)
 +
{
 +
  "type": "FeatureCollection",
 +
  "bbox": [100, 0, 105, 1],
 +
  "features": [
 +
      {
 +
          "type": "Feature",
 +
          "id": "id0",
 +
          "bbox": [102, 0, 105, 1],
 +
          "geometry": {
 +
              "type": "LineString",
 +
              "coordinates": [
 +
                  [102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0]
 +
              ]
 +
          },
 +
          "properties": {
 +
              "prop0": "value0",
 +
              "prop1": "value1"
 +
          }
 +
      },
 +
      {
 +
          "type": "Feature",
 +
          "id": "id1",
 +
          "bbox": [100, 0, 101, 1],
 +
          "geometry": {
 +
              "type": "Polygon",
 +
              "coordinates": [
 +
                  [
 +
                      [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]
 +
                  ]
 +
              ]
 +
          },
 +
          "properties": {
 +
              "prop0": "value0",
 +
              "prop1": "value1"
 +
          }
 +
      }
 +
  ]
 
  }
 
  }
  
Line 343: Line 391:
 
     ],
 
     ],
 
     "location" : {
 
     "location" : {
         "type", "Box",
+
         "type", "Polygon",
         "coordinates": [[-121, 39], [-119, 41]]
+
         "coordinates": [[[-121, 39], [-119, 39], [-119, 41], [-121, 41], [-121, 39]]]
 
       }
 
       }
 
     }
 
     }
 
   }
 
   }
 
   }
 
   }
+
 
 
==Authors==
 
==Authors==
 
* Tim Schaub
 
* Tim Schaub
 
* Allan Doyle
 
* Allan Doyle
 
* Martin Daly
 
* Martin Daly
* Christopher Schmidt
 
 
* Sean Gillies
 
* Sean Gillies
 
* Andrew Turner
 
* Andrew Turner

Latest revision as of 13:59, 23 April 2008

Overview

GeoJSON is a data-interchange format for a variety of geographic data structures. GeoJSON can be used to represent a geometry, a feature, a collection of geometries, or a collection of features. The geometry types supported in GeoJSON are Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon and GeometryCollection. Features in GeoJSON are geometry objects with additional properties. A geometry collection represents a list of geometries and a feature collection represents a list of features.

A complete GeoJSON data structure is always an object (in JSON terms). In GeoJSON, an object consists of a collection of name/value pairs - also called members. For each member, the name is always a string. Member values are either a string, number, object, array or one of the literals: true, false, and null. An array consists of elements where each element is a value as described above.

Definitions

Specification

  1. GeoJSON always consists of a single object. This object (referred to as the GeoJSON object below) represents a geometry, feature, collection of geometries, or collection of features.
  2. The GeoJSON object may have any number of members (name/value pairs).
  3. The GeoJSON object must have a member with the name "type". This member's value is a string that determines the type of the GeoJSON object.
    1. The value of the type member must be one of: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", "GeometryCollection", "Feature", or "FeatureCollection". "type" must be lower case, the case of the type member values must be as shown here.
    2. A geometry is a GeoJSON object where the type member's value is one of: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", or "GeometryCollection". The case of the type member values must be as shown here.
      1. A GeoJSON geometry object of any type other than "GeometryCollection" must have a member with the name "coordinates". The value of the coordinates member is always an array (referred to as the coordinates array below). The structure for the elements in this array are determined by the type of geometry.
        1. For type "Point", each element in the coordinates array is a number representing the point coordinate in one dimension. There must be at least two elements, and may be more. The order of elements must follow x, y, z order (or longitude, latitude, altitude for coordinates in a geographic coordinate reference system). Any number of additional dimensions are allowed, and interpretation and meaning of these coordinates is beyond the scope of this specification.
        2. For type "MultiPoint", each element in the coordinates array is a coordinates array as described for type "Point".
        3. For type "LineString", each element in the coordinates array is a coordinates array as described for type "Point". The coordinates array for a LineString must have two or more elements. A LinearRing is a special case of type LineString where the first and last elements in the coordinates array are equivalent (they represent equivalent points). Though a LinearRing is not explicitly represented as a GeoJSON geometry type, it is referred to in the Polygon geometry type definition.
        4. For type "MultiLineString", each element in the coordinates array is a coordinates array as described for type "LineString".
        5. For type "Polygon", each element in the coordinates array is a coordinates array as described for type "LineString". Furthermore, each LineString in the coordinates array must be a LinearRing. For Polygons with multiple LinearRings, the first must be the exterior ring and any others must be interior rings or holes.
        6. For type "MultiPolygon", each element in the coordinates array is a coordinates array as described for type "Polygon".
      2. A GeoJSON geometry object with type "GeometryCollection" is a geometry object which represents a collection of geometry objects.
        1. A geometry collection must have a member with the name "geometries". The value corresponding to "geometries" is an array. Each element in this array is a GeoJSON geometry object.
    3. A GeoJSON object with the type "Feature" represents a geometry with additional properties (referred to as a feature object below).
      1. A feature object must have a member with the name "geometry". The value of the geometry member is a geometry object as defined above or a JSON null value (as in {"type":"Feature", "properties": {"title":"empty"}, "geometry":null}).
      2. A feature object must have a member with the name "properties". The value of the properties member is an object (any JSON object).
      3. If a feature has a commonly used identifier, that identifier should be included as a member of the feature object with the name "id".
    4. A GeoJSON object with the type "FeatureCollection" represents a collection of feature objects.
      1. An object of type "FeatureCollection" must have a member with the name "features". The value corresponding to "features" is an array. Each element in the array is a feature object as defined above.
  4. Coordinate Reference Systems: The coordinate reference system (CRS) of a GeoJSON object is determined by its "crs" member. If an object has no "crs" member, its parent object's "crs" member may be acquired. If no CRS can be so acquired, the default CRS shall apply to the GeoJSON object.
    1. Default coordinate reference system: The default is a geographic coordinate reference system, using the WGS84 datum, and with longitude and latitude units of decimal degrees.
    2. The "crs" member: The value of a member named "crs" must be an object (referred to as the CRS object below) or null. If the value of CRS is null, it means that no CRS can be assumed.
      1. The CRS object: A CRS object has two mandatory members: "type", and "properties".
      2. The "type" member: The value of this required member must be a string, indicating the type of CRS object.
      3. The "properties" member: The value of this required member must be an object.
    3. CRS object types: This specification defines two types of CRS objects.
      1. Named: A CRS object may indicate a coordinate reference system by name. The value of its "properties" member must be an object containing a "name" member. The value of that "name" member must be a string identifying a coordinate reference systems. OGC CRS URNs such as "urn:ogc:def:crs:OGC:1.3:CRS84" shall be preferred over legacy identifiers such as "EPSG:4326".
        1. Example:
          "crs": {"type": "name", "properties": {"name": "urn:ogc:def:crs:OGC:1.3:CRS84"}}
      2. Linked: A CRS object may link to CRS parameters on the Web. In this case the value of its "properties" member must be a Link object (see below).
        1. The Link object: A link object has 1 required member: "href", and 1 optional member: "type". The link object is similar to Atom/HTML/RSS links.
          1. The "href" member: The value of this required member must be a dereferenceable URI.
          2. The "type" member: The value of this optional member must be a string that hints at the format used to represent CRS parameters at the provided URI. Suggested values are: "proj4", "ogcwkt", "esriwkt", though others can be used.
        2. Example:
          "crs": {"type": "link", "properties": {"href": "http://example.com/crs/42", "type": "proj4"}}
          Relative links may be used to direct processors to CRS parameters in an auxiliary file:
          "crs": {"type": "link", "properties": {"href": "data.prj", "type": "proj4"}}

Examples

Each of the examples below represents a complete GeoJSON object. Note that unquoted whitespace is not significant in JSON. Whitespace is used in the examples to help illustrate the data structures - though it is not required.

Geometries

Point

Point coordinates are in x, y order (longitude, latitude for geographic coordinates).

{
   "type": "Point",
   "coordinates": [100.0, 0.0]
}

LineString

Coordinates of LineString are an array of Point coordinates.

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

Polygon

Coordinates of a Polygon are an array of LinearRing coordinates (LineString coordinates where the first and last points are equivalent). The first element in the array represents the exterior ring. Any subsequent elements represent interior rings (or holes).

No holes

{
   "type": "Polygon",
   "coordinates": [
       [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
   ]
}

With holes

{
   "type": "Polygon",
   "coordinates": [
       [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ],
       [ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ]
   ]
}

MultiPoint

Coordinates of a MultiPoint are an array of Point coordinates.

{
   "type": "MultiPoint",
   "coordinates": [
       [100.0, 0.0], [101.0, 1.0]
   ]
}

MultiLineString

Coordinates of a MultiLineString are an array of LineString coordinates.

{
   "type": "MultiLineString",
   "coordinates": [
       [ [100.0, 0.0], [101.0, 1.0] ],
       [ [102.0, 2.0], [103.0, 3.0] ]
   ]
}

MultiPolygon

Coordinates of a MultiPolygon are an array of Polygon coordinates.

{
   "type": "MultiPolygon",
   "coordinates": [
       [
           [ [102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0] ]
       ],
       [
           [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ],
           [ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ]
       ]
   ]
}

GeometryCollection

Each element in the geometries array of a GeometryCollection is one of the geometry objects described above.

{
   "type": "GeometryCollection",
   "geometries": [
       {
           "type": "Point",
           "coordinates": [100.0, 0.0]
       },
       {
           "type": "LineString",
           "coordinates": [
               [101.0, 0.0], [102.0, 1.0]
           ]
       }
   ]
}

Feature

A Feature is an object with a geometry and additional properties.

{
   "type": "Feature",
   "geometry": {
       "type": "LineString",
       "coordinates": [
           [100.0, 0.0], [101.0, 1.0]
       ]
   },
   "properties": {
       "prop0": "value0",
       "prop1": "value1"
   }
}


Since a GeometryCollection is a geometry type, you can use one inside a Feature:

{
   "type": "Feature",
   "geometry": {
      "type": "GeometryCollection",
      "geometries": [
          {
            "type": "Point",
            "coordinates": [100.0, 0.0]
          },
          {
            "type": "LineString",
            "coordinates": [
                [101.0, 0.0], [102.0, 1.0]
            ]
          }
      ]
   },
   "properties": {
       "prop0": "value0",
       "prop1": "value1"
   }
}

FeatureCollection

Each element in the features array of a FeatureCollection is a Feature object as described above.

{
   "type": "FeatureCollection",
   "features": [
       {
           "type": "Feature",
           "id": "id0",
           "geometry": {
               "type": "LineString",
               "coordinates": [
                   [102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0]
               ]
           },
           "properties": {
               "prop0": "value0",
               "prop1": "value1"
           }
       },
       {
           "type": "Feature",
           "id": "id1",
           "geometry": {
               "type": "Polygon",
               "coordinates": [
                   [
                       [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]
                   ]
               ]
           },
           "properties": {
               "prop0": "value0",
               "prop1": "value1"
           }
       }
   ]
}

Same feature collection, with a member named "crs" to represent the coordinate reference system. Note that because this example uses EPSG:4326, it must specify coordinate_order, since EPSG:4326 defines the coordinate order to be "lat, lon", which is the opposite of the GeoJSON default.

{
   "type": "FeatureCollection",
   "crs": {
      "type": "EPSG",
      "properties": { 
         "code": 4326,
         "coordinate_order": [1, 0]
      }
    },
   "features": [
       {
           "type": "Feature",
           "id": "id0",
           "geometry": {
               "type": "LineString",
               "coordinates": [
                   [102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0]
               ]
           },
           "properties": {
               "prop0": "value0",
               "prop1": "value1"
           }
       },
       {
           "type": "Feature",
           "id": "id1",
           "geometry": {
               "type": "Polygon",
               "coordinates": [
                   [
                       [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]
                   ]
               ]
           },
           "properties": {
               "prop0": "value0",
               "prop1": "value1"
           }
       }
   ]
}

Including additional members

GeoJSON allows additional members at any level in a GeoJSON object (as described in point 2 in the specification).

For example, if you are constructing a Feature type object, three members are required (named "type", "geometry", and "properties"). In addition to these three members, you may add any additional members. The example below adds a member named "foo" with the value "bar".

{
   "type": "Feature",
   "geometry": {
       "type": "LineString",
       "coordinates": [
           [100.0, 0.0], [101.0, 1.0]
       ]
   },
   "properties": {
       "prop0": "value0",
       "prop1": "value1"
   },
   "foo": "bar"
}

If you are working with a data standard that uses namespaces, you can handle those by taking advantage of these extra members. For example, adding a member with the name "@namespaces" is valid in GeoJSON:

{
   "@namespaces":  {"":"http://geojson.org/ns#"},
   "type": "Feature",
   "geometry": {
       "type": "LineString",
       "coordinates": [
           [100.0, 0.0], [101.0, 1.0]
       ]
   },
   "properties": {
       "prop0": "value0",
       "prop1": "value1"
   }
}

Additionally, since all unicode characters are allowed in member names, the following object (with a member named "atom:summary" is valid GeoJSON).

{
   "@namespaces":  {"":"http://geojson.org/ns#", "atom":"http://www.w3.org/2005/Atom"},
   "@type": "atom:item",
   "type": "Feature",
   "geometry": {
       "type": "LineString",
       "coordinates": [
           [100.0, 0.0], [101.0, 1.0]
       ]
   },
   "properties": {
       "atom:summary": "Some GeoJSON Content",
       "atom:description": "This content is also valid GeoJDIL."
   }
}

Including Bounding Box/Envelope

To include information on the coordinate range for geometries, features, or feature collections, it is suggested that member named bbox be included in a GeoJSON object. The value of the bbox member should be a 2*n item array where n is the number of dimensions represented in the contained geometries and lowest values for all axes are followed by highest values. Axes order of a bbox follows axes order of geometries. In addition, the spatial reference for the bbox is assumed to match the spatial reference for the GeoJSON object of which it is a member.

Example of a bbox member on a polygon geometry

{ 
  "bbox": [-180, -90, 180, 90],
  "type": "Polygon",
  "coordinates": [
      [ [-180, 10], [20, 90], [180, -5], [-30, -90] ]
  ]
}

Example of a bbox member on a feature collection (with a bbox on each feature as well)

{
  "type": "FeatureCollection",
  "bbox": [100, 0, 105, 1],
  "features": [
      {
          "type": "Feature",
          "id": "id0",
          "bbox": [102, 0, 105, 1],
          "geometry": {
              "type": "LineString",
              "coordinates": [
                  [102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0]
              ]
          },
          "properties": {
              "prop0": "value0",
              "prop1": "value1"
          }
      },
      {
          "type": "Feature",
          "id": "id1",
          "bbox": [100, 0, 101, 1],
          "geometry": {
              "type": "Polygon",
              "coordinates": [
                  [
                      [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]
                  ]
              ]
          },
          "properties": {
              "prop0": "value0",
              "prop1": "value1"
          }
      }
  ]
}

Using with non-geographic elements

GeoJSON is not a format in itself, but a specification for adding geometry to JSON elements. Therefore, it is possible to GeoJSON within a broader JSON document that has mixed elements - for example a blog.

 {
  "blog" : {
   "posts" : [
     {
       "type" : "atom:item",
       "atom:summary": "post 1",
       "atom:description" : "i love blogging"},
     {
       "type" : "atom:item",
       "atom:summary": "post 2 from CA",
       "atom:description" : "geoblogging in California"
       "location" : {
         "type", "Point",
         "coordinates": [-120, 40]
       }
     },
   ],
   "location" : {
       "type", "Polygon",
       "coordinates": [[[-121, 39], [-119, 39], [-119, 41], [-121, 41], [-121, 39]]]
     }
   }
  }
 }

Authors

  • Tim Schaub
  • Allan Doyle
  • Martin Daly
  • Sean Gillies
  • Andrew Turner