1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
<html>
<head>
<title>GeoJSON</title>
</head>
<body bgcolor="#ffffff">
<h1>GeoJSON</h1>
<p>This driver implements read/write support for access to features encoded in
<a href="http://geojson.org/">GeoJSON</a> format. The GeoJSON is a dialect based on the
<a href="http://json.org/">JavaScript Object Notation (JSON)</a>. The JSON is a lightweight
plain text format for data interchange and GeoJSON is nothing other than its specialization for geographic content.</p>
<p>At the moment of writing this, GeoJSON is supported as output format of services implemented by
<a href="http://featureserver.org/">FeatureServer</a>, <a href="http://docs.codehaus.org/display/GEOSDOC/GeoJSON+Output+Format">GeoServer</a>
and <a href="http://exportgge.sourceforge.net/kml/">CartoWeb</a>.</p>
<p>The OGR GeoJSON driver translates a GeoJSON encoded data to objects of <a href="/ogr/ogr_arch.html">OGR Simple Features model</a>:
Datasource, Layer, Feature, Geometry.
The implementation is based on <a href="http://wiki.geojson.org/GeoJSON_draft_version_5">GeoJSON Specification draft, v5.0</a>.</p>
<p>Starting with OGR 1.8.0, the GeoJSON driver can read the JSON output of Feature Service request 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></p>
<h2>Datasource</h2>
<p>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>
<p>A GeoJSON datasource is translated to single OGRLayer object with pre-defined name <em>OGRGeoJSON</em>:
<pre>
ogrinfo -ro http://featureserver/data/.geojson OGRGeoJSON
</pre>
It's also valid to assume that OGRDataSource::GetLayerCount() for GeoJSON datasource always returns 1.
</p>
<p>Accessing Web Service as a datasource (ie. 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.</p>
<p>If a top-level member of GeoJSON data is of any other type than <em>FeatureCollection</em>, the driver will
produce a layer with only one feature. Otherwise, a layer will consists of a set of features.</p>
<h2>Feature</h2>
<p>The OGR GeoJSON driver maps each object of following types to new <em>OGRFeature</em> object:
Point, LineString, Polygon, GeometryCollection, Feature.</p>
<p>According to the <em>GeoJSON Specification</em>, only the <em>Feature</em> object must have a member with
name <em>properties</em>. Each and every member of <em>properties</em> is translated to OGR object of type of
OGRField and added to corresponding OGRFeature object.</p>
<p>The <em>GeoJSON Specification</em> does not require all <em>Feature</em> objects in a collection must
have the same schema of properties. If <em>Feature</em> objects in a set defined by <em>FeatureCollection</em>
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 <em>Feature</em> properties.</p>
<p>It is possible to tell the driver to not to process attributes by setting environment variable
<strong>ATTRIBUTES_SKIP=YES</strong>. Default behavior is to preserve all attributes (as an union, see previous paragraph),
what is equal to setting <strong>ATTRIBUTES_SKIP=NO</strong>.</p>
<h2>Geometry</h2>
<p>Similarly to the issue with mixed-properties features, the <em>GeoJSON Specification</em> draft does not require
all <em>Feature</em> 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.</p>
<p>However, sometimes there is a need to generate 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 environment variable <strong>GEOMETRY_AS_COLLECTION=YES</strong> (default is <strong>NO</strong>).</p>
<h2>Environment variables</h2>
<ul>
<li><b>GEOMETRY_AS_COLLECTION</b> - used to control translation of geometries: YES - wrap geometries with OGRGeometryCollection type</li>
<li><b>ATTRIBUTES_SKIP</b> - controls translation of attributes: YES - skip all attributes</li>
</ul>
<h2>Layer creation option</h2>
<ul>
<li><b>WRITE_BBOX</b> = YES/NO : (OGR >= 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><b>COORDINATE_PRECISION</b> = int_number : (OGR >= 1.9.0) Maximum number of figures after decimal separator to write in coordinates.
Default to 15. "Smart" truncation will occur to remove trailing zeros.</li>
</ul>
<h2>VSI Virtual File System API support</h2>
(Some features below might require OGR >= 1.9.0)<p>
The driver supports reading and writing to files managed by VSI Virtual File System API, which include
"regular" files, as well as files in the /vsizip/ (read-write) , /vsigzip/ (read-write) , /vsicurl/ (read-only) domains.<p>
Writing to /dev/stdout or /vsistdout/ is also supported.<p>
<h2>Example</h2>
<p>How to dump content of .geojson file:
<pre>
ogrinfo -ro point.geojson
</pre>
</p>
<p>How to query features from remote service with filtering by attribute:
<pre>
ogrinfo -ro http://featureserver/cities/.geojson OGRGeoJSON -where "name=Warsaw"
</pre>
</p>
<p>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>
</p>
<p>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&outfields=*&f=json"
</pre>
</p>
<h2>See Also</h2>
<p>
<ul>
<li><a href="http://geojson.org/">GeoJSON</a> - encoding geographic content in JSON</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>
</p>
</body>
</html>
|
