EVOLUTION-MANAGER

Edit File: drv_geojson.html

<html>
<head>
<title>GeoJSON</title>
</head>

<h1>GeoJSON</h1>

This driver implements read/write support for access to features encoded in
<a href="http://geojson.org/">GeoJSON</a> format. GeoJSON is a dialect based on the
<a href="http://json.org/">JavaScript Object Notation (JSON)</a>. JSON is a lightweight
plain text format for data interchange and GeoJSON is nothing other than its specialization for geographic content.

GeoJSON is supported as an output format of a number of services:
<a href="http://featureserver.org/">FeatureServer</a>,
<a href="http://docs.geoserver.org/2.6.x/en/user/services/wfs/outputformats.html">GeoServer</a>,
<a href="http://exportgge.sourceforge.net/kml/">CartoWeb</a>, etc.

The OGR GeoJSON driver translates GeoJSON encoded data to objects of the <a href="ogr_arch.html">OGR Simple Features model</a>:
Datasource, Layer, Feature, Geometry.
The implementation is based on <a href="http://geojson.org/geojson-spec.html">GeoJSON Specification, v1.0</a>.

Starting with OGR 1.8.0, the GeoJSON driver can read the JSON output of Feature Service requests following the
<a href="http://www.esri.com/industries/landing-pages/geoservices/geoservices.html">GeoServices REST Specification</a>, like
implemented by <a href="http://help.arcgis.com/en/arcgisserver/10.0/apis/rest/index.html">ArcGIS Server REST API</a>.
Starting with OGR 2.0, the GeoJSON driver can scroll through such result sets that
are spread over multiple pages (for ArcGIS servers &gt;= 10.3). This is automatically enabled
if URL does not contain an explicit resultOffset parameter. If it contains
this parameter and scrolling is still desired, the FEATURE_SERVER_PAGING open option must be set to YES.
The page size can be explicitly set with the resultRecordCount parameter (but
is subject to a server limit). If it is not set, OGR will set it to the maximum
value allowed by the server.

Starting with OGR 1.11, the GeoJSON driver can read the <a href="https://github.com/mbostock/topojson/wiki/Specification">TopoJSON format</a>

Starting with GDAL 2.1.0, the GeoJSON driver supports updating existing
GeoJSON files. In that case, the default value for the NATIVE_DATA open option
will be YES.

<h2>Datasource</h2>

The OGR GeoJSON driver accepts three types of sources of data:
<ul>
<li>Uniform Resource Locator (<a href="http://en.wikipedia.org/wiki/URL">URL</a>) - a Web address to
perform <a href="http://en.wikipedia.org/wiki/HTTP">HTTP</a> request</li>
<li>Plain text file with GeoJSON data - identified from the file extension .geojson or .json</li>
<li>Text passed directly and encoded in GeoJSON</li>
</ul>
<h2>Layer</h2>

A GeoJSON datasource is translated to single OGRLayer object with pre-defined name OGRGeoJSON:
<pre>
ogrinfo -ro http://featureserver/data/.geojson OGRGeoJSON
</pre>
It's also valid to assume that OGRDataSource::GetLayerCount() for GeoJSON datasource always returns 1.

Starting with GDAL 2.2, the layer name is built with the following logic:
<ol>
<li>If a "name" member is found at the FeatureCollection level, it is used.</li>
<li>Otherwise if the filename is regular (ie not a URL with query parameters), then
the filename without extension and path is used as the layer name.</li>
<li>Otherwise OGRGeoJSON is used.</li>
</ol>

Accessing Web Service as a datasource (i.e. FeatureServer), each request will produce new layer.
This behavior conforms to stateless nature of HTTP transaction and is similar to how Web browsers operate:
single request == single page.

If a top-level member of GeoJSON data is of any other type than FeatureCollection, the driver will
produce a layer with only one feature. Otherwise, a layer will consists of a set of features.

If the NATIVE_DATA open option is set to YES, members at the level of the FeatureCollection will be
stored as a serialized JSon object in the NATIVE_DATA item of the NATIVE_DATA metadata domain of the
layer object (and "application/vnd.geo+json" in the NATIVE_MEDIA_TYPE of the NATIVE_DATA metadata domain).

<h2>Feature</h2>

The OGR GeoJSON driver maps each object of following types to new OGRFeature object:
Point, LineString, Polygon, GeometryCollection, Feature.

According to the GeoJSON Specification, only the Feature object must have a member with
name properties. Each and every member of properties is translated to OGR object of type of
OGRField and added to corresponding OGRFeature object.

The GeoJSON Specification does not require all Feature objects in a collection to
have the same schema of properties. If Feature objects in a set defined by FeatureCollection
object have different schema of properties, then resulting schema of fields in OGRFeatureDefn is generated as
<a href="http://en.wikipedia.org/wiki/Union_(set_theory)">union</a> of all Feature properties.

Schema detection will recognized fields of type String, Integer, Real, StringList, IntegerList and RealList.
Starting with GDAL 2.0, Integer(Boolean), Date, Time and DateTime fields are also recognized.

It is possible to tell the driver to not to process attributes by setting environment variable
ATTRIBUTES_SKIP=YES. Default behavior is to preserve all attributes (as an union, see previous paragraph),
what is equal to setting ATTRIBUTES_SKIP=NO.

If the NATIVE_DATA open option is set to YES, the Feature JSon object will be
stored as a serialized JSon object in the NativeData property of the OGRFeature object
(and "application/vnd.geo+json" in the NativeMediaType property). On write, if
a OGRFeature to be written has its NativeMediaType property set to "application/vnd.geo+json"
and its NativeData property set to a string that is a serialized JSon object, then
extra members of this object (i.e. not the "property" dictionary, nor the first 3
dimensions of geometry coordinates) will be used to enhance the created JSon object from
the OGRFeature. See <a href="https://trac.osgeo.org/gdal/wiki/rfc60_improved_roundtripping_in_ogr">RFC 60</a> for more details.

<h2>Geometry</h2>

Similarly to the issue with mixed-properties features, the GeoJSON Specification draft does not require
all Feature objects in a collection must have geometry of the same type. Fortunately, OGR objects model does
allow to have geometries of different types in single layer - a heterogeneous layer. By default, the GeoJSON driver
preserves type of geometries.

However, sometimes there is a need to generate a homogeneous layer from a set of heterogeneous features.
For this purpose, it's possible to tell the driver to wrap all geometries with OGRGeometryCollection type as a common denominator.
This behavior may be controlled by setting GEOMETRY_AS_COLLECTION=YES in the environment (default is NO).

<h2>Environment variables</h2>

<ul>
<li>GEOMETRY_AS_COLLECTION - used to control translation of geometries: YES - wrap geometries with OGRGeometryCollection type</li>
<li>ATTRIBUTES_SKIP - controls translation of attributes: YES - skip all attributes</li>
</ul>

<h2>Open options</h2>

(GDAL &gt;= 2.0)

<ul>
<li>FLATTEN_NESTED_ATTRIBUTES = YES/NO: Whether to
recursively explore nested objects and produce flatten OGR attributes. Defaults to NO.</li>
<li>NESTED_ATTRIBUTE_SEPARATOR = character: Separator between components
of nested attributes. Defaults to '_'</li>
<li>FEATURE_SERVER_PAGING = YES/NO: Whether to automatically scroll through
results with a ArcGIS Feature Service endpoint.</li>
<li>NATIVE_DATA = YES/NO: (GDAL &gt;= 2.1) Whether to store the native JSon representation at FeatureCollection and Feature level.
Defaults to NO. This option can be used to improve round-tripping from GeoJSON to GeoJSON by preserving some extra
JSon objects that would otherwise be ignored by the OGR abstraction. Note that
ogr2ogr by default enable this option, unless you specify its -noNativeData switch.</li>
<li>ARRAY_AS_STRING = YES/NO: (GDAL &gt;= 2.1) Whether to expose JSon arrays
of strings, integers or reals as a OGR String. Default is NO. Can also be set with
the OGR_GEOJSON_ARRAY_AS_STRING configuration option.</li>
</ul>

To explain FLATTEN_NESTED_ATTRIBUTES, consider the following GeoJSON fragment:

<pre>
{
 "type": "FeatureCollection",
 "features":
 [
 {
 "type": "Feature",
 "geometry": {
 "type": "Point",
 "coordinates": [ 2, 49 ]
 },
 "properties": {
 "a_property": "foo",
 "some_object": {
 "a_property": 1,
 "another_property": 2
 }
 }
 }
 ]
}
</pre>

"ogrinfo test.json -al -oo FLATTEN_NESTED_ATTRIBUTES=yes" reports:

<pre>
OGRFeature(OGRGeoJSON):0
 a_property (String) = foo
 some_object_a_property (Integer) = 1
 some_object_another_property (Integer) = 2
 POINT (2 49)
</pre>

<h2>Layer creation options</h2>

<ul>
<li>WRITE_BBOX = YES/NO: (OGR &gt;= 1.9.0) Set to YES to write a bbox property with the bounding box of the geometries at the feature and feature
collection level. Defaults to NO.</li>
<li>COORDINATE_PRECISION = int_number: (OGR &gt;= 1.9.0) Maximum number of figures after decimal separator to write in coordinates.
Default to 15 for GeoJSON 2008, and 7 for RFC 7946. "Smart" truncation will occur to remove trailing zeros.</li>
<li>SIGNIFICANT_FIGURES = int_number: (OGR &gt;= 2.1) Maximum number of significant figures when writing floating-point numbers.
Default to 17. If explicitly specified, and COORDINATE_PRECISION is not, this will also apply to coordinates.</li>
<li>NATIVE_DATA=string. (OGR &gt;= 2.1) Serialized JSon object that contains extra properties to store at FeatureCollection level.</li>
<li>NATIVE_MEDIA_TYPE=string. (OGR &gt;= 2.1) Format of NATIVE_DATA. Must be "application/vnd.geo+json", otherwise NATIVE_DATA will be ignored.</li>
<li>RFC7946=YES/NO. (OGR &gt;= 2.2) Whether to use
<a href="https://tools.ietf.org/html/rfc7946">RFC 7946</a> standard.
Otherwise <a href="http://geojson.org/geojson-spec.html">GeoJSON 2008</a> initial version will be used.
Default is NO (thus GeoJSON 2008)</li>
<li>WRITE_NAME=YES/NO. (OGR &gt;= 2.2) Whether to write a "name" property
at feature collection level with layer name. Defaults to YES.</li>
<li>DESCRIPTION=string. (OGR &gt;= 2.2) (Long) description to write in a
"description" property at feature collection level. On reading, this will be
reported in the DESCRIPTION metadata item of the layer.</li>
</ul>

<h2>VSI Virtual File System API support</h2>

Some features below require OGR &gt;= 1.9.0.

The driver supports reading and writing to files managed by VSI Virtual File System API, which includes
"regular" files, as well as files in the /vsizip/ (read-write), /vsigzip/ (read-write), /vsicurl/ (read-only) domains.

Writing to /dev/stdout or /vsistdout/ is also supported.

<h2>Round-tripping of extra JSon members</h2>

See <a href="https://trac.osgeo.org/gdal/wiki/rfc60_improved_roundtripping_in_ogr">RFC 60</a> for more details.

Starting with GDAL 2.1, extra JSon members at the FeatureCollection, Feature or
geometry levels that are not normally reflected in the OGR abstraction,
such as the ones called "extra_XXXXX_member" in the below
snippet, are by default preserved when executing ogr2ogr with GeoJSON both at the
source and destination. This also applies to extra values in position tuples
of geometries, beyond the 3rd dimension (100, 101 in the below example), if the
transformation preserves the geometry structure (for example, reprojection is allowed, but not
change in the number of coordinates).

<pre>
{
 "type": "FeatureCollection",
 "extra_fc_member": "foo",
 "features":
 [
 {
 "type": "Feature",
 "extra_feat_member": "bar",
 "geometry": {
 "type": "Point",
 "extra_geom_member": "baz",
 "coordinates": [ 2, 49, 3, 100, 101 ]
 },
 "properties": {
 "a_property": "foo",
 }
 }
 ]
}
</pre>

This behaviour can be turned off by specifying the -noNativeData switch
of the ogr2ogr utility.

<h2>RFC 7946 write support</h2>

By default, the driver will write GeoJSON files following GeoJSON 2008 specification.
When specifying the RFC7946=YES creation option, the RFC 7946 standard will be
used instead.

The differences between the 2 versions are mentioned in <a href="https://tools.ietf.org/html/rfc7946#appendix-B">
Appendix B of RFC 7946</a> and recalled here for what matters to the driver:
<ul>
<li>Coordinates must be in longitude/latitude over the WGS 84 ellipsoid, hence
if the spatial reference system specified at layer creation time is not EPSG:4326,
on-the-fly reprojection will be done by the driver.</li>
<li>Polygons will be written such as to follow the right-hand rule for orientation
(counterclockwise external rings, clockwise internal rings).</li>
<li>The values of a "bbox" array are "[west, south, east, north]", not
"[minx, miny, maxx, maxy]"</li>
<li>Some extension member names (see previous section about round/tripping) are
forbidden in the FeatureCollection, Feature and Geometry objects.</li>
<li>The default coordinate precision is 7 decimal digits after decimal separator.</li>
</ul>

<h2>Example</h2>

How to dump content of .geojson file:
<pre>
ogrinfo -ro point.geojson
</pre>

How to query features from remote service with filtering by attribute:
<pre>
ogrinfo -ro http://featureserver/cities/.geojson OGRGeoJSON -where "name=Warsaw"
</pre>

How to translate number of features queried from FeatureServer to ESRI Shapefile:
<pre>
ogr2ogr -f "ESRI Shapefile" cities.shp http://featureserver/cities/.geojson OGRGeoJSON
</pre>

How to translate a ESRI Shapefile into a RFC 7946 GeoJSON file:
<pre>
ogr2ogr -f GeoJSON cities.json cities.shp -lco RFC7946=YES
</pre>

Read the result of a FeatureService request against a GeoServices REST server:
<pre>
ogrinfo -ro -al "http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Hydrography/Watershed173811/FeatureServer/0/query?where=objectid+%3D+objectid&amp;outfields=*&amp;f=json"
</pre>

<ul>
<li><a href="http://geojson.org/">GeoJSON</a> - encoding geographic content in JSON</li>
<li><a href="https://tools.ietf.org/html/rfc7946">RFC 7946</a> standard.</li>
<li><a href="http://geojson.org/geojson-spec.html">GeoJSON 2008</a> specification (obsoleted by RFC 7946).</li>
<li><a href="http://json.org/">JSON</a> - JavaScript Object Notation</li>
<li><a href="http://oss.metaparadigm.com/json-c/">JSON-C</a> - A JSON implementation in C</li>
<li><a href="http://lists.osgeo.org/pipermail/gdal-dev/2007-November/014746.html">[Gdal-dev] OGR GeoJSON Driver</a> - driver announcement</li>
<li><a href="http://www.esri.com/industries/landing-pages/geoservices/geoservices.html">GeoServices REST Specification</a></li>
</ul>

</body>
</html>