Skip to content

Instantly share code, notes, and snippets.

@tmcw
Created June 21, 2018 02:22
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save tmcw/8a12b164454505c78554d949b14e579d to your computer and use it in GitHub Desktop.
Save tmcw/8a12b164454505c78554d949b14e579d to your computer and use it in GitHub Desktop.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head profile="http://dublincore.org/documents/2008/08/04/dc-html/">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="robots" content="index,follow" />
<meta name="creator" content="rfcmarkup version 1.127" />
<link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" />
<meta name="DC.Relation.Replaces" content="draft-butler-geojson" />
<meta name="DC.Identifier" content="urn:ietf:rfc:7946" />
<meta name="DC.Date.Issued" content="August, 2016" />
<meta name="DC.Creator" content="Gillies, Sean" />
<meta name="DC.Creator" content="Butler, H." />
<meta name="DC.Creator" content="Daly, M." />
<meta name="DC.Creator" content="Doyle, A." />
<meta name="DC.Creator" content="Schaub, T." />
<meta name="DC.Description.Abstract" content="GeoJSON is a geospatial data interchange format based on JavaScript
Object Notation (JSON). It defines several types of JSON objects and
the manner in which they are combined to represent data about
geographic features, their properties, and their spatial extents.
GeoJSON uses a geographic coordinate reference system, World Geodetic
System 1984, and units of decimal degrees." />
<meta name="DC.Title" content="The GeoJSON Format" />
<link rel="icon" href="/images/rfc.png" type="image/png" />
<link rel="shortcut icon" href="/images/rfc.png" type="image/png" />
<title>RFC 7946 - The GeoJSON Format</title>
<style type="text/css">
@media only screen
and (min-width: 992px)
and (max-width: 1199px) {
body { font-size: 14pt; }
div.content { width: 96ex; margin: 0 auto; }
}
@media only screen
and (min-width: 768px)
and (max-width: 991px) {
body { font-size: 14pt; }
div.content { width: 96ex; margin: 0 auto; }
}
@media only screen
and (min-width: 480px)
and (max-width: 767px) {
body { font-size: 11pt; }
div.content { width: 96ex; margin: 0 auto; }
}
@media only screen
and (max-width: 479px) {
body { font-size: 8pt; }
div.content { width: 96ex; margin: 0 auto; }
}
@media only screen
and (min-device-width : 375px)
and (max-device-width : 667px) {
body { font-size: 9.5pt; }
div.content { width: 96ex; margin: 0 1px; }
}
@media only screen
and (min-device-width: 1200px) {
body { font-size: 10pt; margin: 0 4em; }
div.content { width: 96ex; margin: 0; }
}
h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6 {
font-weight: bold;
line-height: 0pt;
display: inline;
white-space: pre;
font-family: monospace;
font-size: 1em;
font-weight: bold;
}
pre {
font-size: 1em;
margin-top: 0px;
margin-bottom: 0px;
}
.pre {
white-space: pre;
font-family: monospace;
}
.header{
font-weight: bold;
}
.newpage {
page-break-before: always;
}
.invisible {
text-decoration: none;
color: white;
}
a.selflink {
color: black;
text-decoration: none;
}
@media print {
body {
font-family: monospace;
font-size: 10.5pt;
}
h1, h2, h3, h4, h5, h6 {
font-size: 1em;
}
a:link, a:visited {
color: inherit;
text-decoration: none;
}
.noprint {
display: none;
}
}
@media screen {
.grey, .grey a:link, .grey a:visited {
color: #777;
}
.docinfo {
background-color: #EEE;
}
.top {
border-top: 7px solid #EEE;
}
.bgwhite { background-color: white; }
.bgred { background-color: #F44; }
.bggrey { background-color: #666; }
.bgbrown { background-color: #840; }
.bgorange { background-color: #FA0; }
.bgyellow { background-color: #EE0; }
.bgmagenta{ background-color: #F4F; }
.bgblue { background-color: #66F; }
.bgcyan { background-color: #4DD; }
.bggreen { background-color: #4F4; }
.legend { font-size: 90%; }
.cplate { font-size: 70%; border: solid grey 1px; }
}
</style>
<!--[if IE]>
<style>
body {
font-size: 13px;
margin: 10px 10px;
}
</style>
<![endif]-->
<script type="text/javascript"><!--
function addHeaderTags() {
var spans = document.getElementsByTagName("span");
for (var i=0; i < spans.length; i++) {
var elem = spans[i];
if (elem) {
var level = elem.getAttribute("class");
if (level == "h1" || level == "h2" || level == "h3" || level == "h4" || level == "h5" || level == "h6") {
elem.innerHTML = "<"+level+">"+elem.innerHTML+"</"+level+">";
}
}
}
}
var legend_html = "Colour legend:<br /> <table> <tr><td>Unknown:</td> <td><span class='cplate bgwhite'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Draft:</td> <td><span class='cplate bgred'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Informational:</td> <td><span class='cplate bgorange'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Experimental:</td> <td><span class='cplate bgyellow'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Best Common Practice:</td> <td><span class='cplate bgmagenta'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Proposed Standard:</td> <td><span class='cplate bgblue'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Draft Standard (old designation):</td> <td><span class='cplate bgcyan'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Internet Standard:</td> <td><span class='cplate bggreen'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Historic:</td> <td><span class='cplate bggrey'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Obsolete:</td> <td><span class='cplate bgbrown'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> </table>";
function showElem(id) {
var elem = document.getElementById(id);
elem.innerHTML = eval(id+"_html");
elem.style.visibility='visible';
}
function hideElem(id) {
var elem = document.getElementById(id);
elem.style.visibility='hidden';
elem.innerHTML = "";
}
// -->
</script>
</head>
<body onload="addHeaderTags()">
<div class="content">
<div style="height: 13px;">
<div onmouseover="this.style.cursor='pointer';"
onclick="showElem('legend');"
onmouseout="hideElem('legend')"
style="height: 6px; position: absolute;"
class="pre noprint docinfo bgblue"
title="Click for colour legend." > </div>
<div id="legend"
class="docinfo noprint pre legend"
style="position:absolute; top: 4px; left: 4ex; visibility:hidden; background-color: white; padding: 4px 9px 5px 7px; border: solid #345 1px; "
onmouseover="showElem('legend');"
onmouseout="hideElem('legend');">
</div>
</div>
<span class="pre noprint docinfo top">[<a href="../html/" title="Document search and retrieval page">Docs</a>] [<a href="/rfc/rfc7946.txt" title="Plaintext version of this document">txt</a>|<a href="/pdf/rfc7946" title="PDF version of this document">pdf</a>] [<a href="./draft-ietf-geojson" title="draft-ietf-geojson">draft-ietf-geojson</a>] [<a href='https://datatracker.ietf.org/doc/rfc7946' title='IESG Datatracker information for this document'>Tracker</a>] [<a href="/rfcdiff?difftype=--hwdiff&amp;url2=rfc7946" title="Inline diff (wdiff)">Diff1</a>] [<a href="/rfcdiff?url2=rfc7946" title="Side-by-side diff">Diff2</a>] [<a href="https://www.rfc-editor.org/errata_search.php?rfc=7946">Errata</a>]</span><br />
<span class="pre noprint docinfo"> </span><br />
<span class="pre noprint docinfo"> PROPOSED STANDARD</span><br />
<span class="pre noprint docinfo"> <span style='color: #C00;'>Errata Exist</span></span><br />
<pre>
Internet Engineering Task Force (IETF) H. Butler
Request for Comments: 7946 Hobu Inc.
Category: Standards Track M. Daly
ISSN: 2070-1721 Cadcorp
A. Doyle
S. Gillies
Mapbox
S. Hagen
T. Schaub
Planet Labs
August 2016
<span class="h1">The GeoJSON Format</span>
Abstract
GeoJSON is a geospatial data interchange format based on JavaScript
Object Notation (JSON). It defines several types of JSON objects and
the manner in which they are combined to represent data about
geographic features, their properties, and their spatial extents.
GeoJSON uses a geographic coordinate reference system, World Geodetic
System 1984, and units of decimal degrees.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in <a href="./rfc7841#section-2">Section&nbsp;2 of RFC 7841</a>.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
<a href="http://www.rfc-editor.org/info/rfc7946">http://www.rfc-editor.org/info/rfc7946</a>.
<span class="grey">Butler, et al. Standards Track [Page 1]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-2" id="page-2" href="#page-2" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to <a href="./bcp78">BCP 78</a> and the IETF Trust's Legal
Provisions Relating to IETF Documents
(<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
<a href="#section-1">1</a>. Introduction . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
<a href="#section-1.1">1.1</a>. Requirements Language . . . . . . . . . . . . . . . . . . <a href="#page-4">4</a>
<a href="#section-1.2">1.2</a>. Conventions Used in This Document . . . . . . . . . . . . <a href="#page-4">4</a>
<a href="#section-1.3">1.3</a>. Specification of GeoJSON . . . . . . . . . . . . . . . . <a href="#page-4">4</a>
<a href="#section-1.4">1.4</a>. Definitions . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-1.5">1.5</a>. Example . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-2">2</a>. GeoJSON Text . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-6">6</a>
<a href="#section-3">3</a>. GeoJSON Object . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-6">6</a>
<a href="#section-3.1">3.1</a>. Geometry Object . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-3.1.1">3.1.1</a>. Position . . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-3.1.2">3.1.2</a>. Point . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-8">8</a>
<a href="#section-3.1.3">3.1.3</a>. MultiPoint . . . . . . . . . . . . . . . . . . . . . <a href="#page-8">8</a>
<a href="#section-3.1.4">3.1.4</a>. LineString . . . . . . . . . . . . . . . . . . . . . <a href="#page-8">8</a>
<a href="#section-3.1.5">3.1.5</a>. MultiLineString . . . . . . . . . . . . . . . . . . . <a href="#page-8">8</a>
<a href="#section-3.1.6">3.1.6</a>. Polygon . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
<a href="#section-3.1.7">3.1.7</a>. MultiPolygon . . . . . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
<a href="#section-3.1.8">3.1.8</a>. GeometryCollection . . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
<a href="#section-3.1.9">3.1.9</a>. Antimeridian Cutting . . . . . . . . . . . . . . . . <a href="#page-10">10</a>
<a href="#section-3.1.10">3.1.10</a>. Uncertainty and Precision . . . . . . . . . . . . . . <a href="#page-11">11</a>
<a href="#section-3.2">3.2</a>. Feature Object . . . . . . . . . . . . . . . . . . . . . <a href="#page-11">11</a>
<a href="#section-3.3">3.3</a>. FeatureCollection Object . . . . . . . . . . . . . . . . <a href="#page-12">12</a>
<a href="#section-4">4</a>. Coordinate Reference System . . . . . . . . . . . . . . . . . <a href="#page-12">12</a>
<a href="#section-5">5</a>. Bounding Box . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-12">12</a>
<a href="#section-5.1">5.1</a>. The Connecting Lines . . . . . . . . . . . . . . . . . . <a href="#page-14">14</a>
<a href="#section-5.2">5.2</a>. The Antimeridian . . . . . . . . . . . . . . . . . . . . <a href="#page-14">14</a>
<a href="#section-5.3">5.3</a>. The Poles . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-14">14</a>
<a href="#section-6">6</a>. Extending GeoJSON . . . . . . . . . . . . . . . . . . . . . . <a href="#page-15">15</a>
<a href="#section-6.1">6.1</a>. Foreign Members . . . . . . . . . . . . . . . . . . . . . <a href="#page-15">15</a>
<a href="#section-7">7</a>. GeoJSON Types Are Not Extensible . . . . . . . . . . . . . . <a href="#page-16">16</a>
7.1. Semantics of GeoJSON Members and Types Are Not Changeable 16
<a href="#section-8">8</a>. Versioning . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-17">17</a>
<span class="grey">Butler, et al. Standards Track [Page 2]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-3" id="page-3" href="#page-3" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<a href="#section-9">9</a>. Mapping 'geo' URIs . . . . . . . . . . . . . . . . . . . . . <a href="#page-17">17</a>
<a href="#section-10">10</a>. Security Considerations . . . . . . . . . . . . . . . . . . . <a href="#page-18">18</a>
<a href="#section-11">11</a>. Interoperability Considerations . . . . . . . . . . . . . . . <a href="#page-18">18</a>
<a href="#section-11.1">11.1</a>. I-JSON . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-18">18</a>
<a href="#section-11.2">11.2</a>. Coordinate Precision . . . . . . . . . . . . . . . . . . <a href="#page-18">18</a>
<a href="#section-12">12</a>. IANA Considerations . . . . . . . . . . . . . . . . . . . . . <a href="#page-19">19</a>
<a href="#section-13">13</a>. References . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-20">20</a>
<a href="#section-13.1">13.1</a>. Normative References . . . . . . . . . . . . . . . . . . <a href="#page-20">20</a>
<a href="#section-13.2">13.2</a>. Informative References . . . . . . . . . . . . . . . . . <a href="#page-21">21</a>
<a href="#appendix-A">Appendix A</a>. Geometry Examples . . . . . . . . . . . . . . . . . <a href="#page-22">22</a>
<a href="#appendix-A.1">A.1</a>. Points . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-22">22</a>
<a href="#appendix-A.2">A.2</a>. LineStrings . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-22">22</a>
<a href="#appendix-A.3">A.3</a>. Polygons . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-23">23</a>
<a href="#appendix-A.4">A.4</a>. MultiPoints . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-24">24</a>
<a href="#appendix-A.5">A.5</a>. MultiLineStrings . . . . . . . . . . . . . . . . . . . . <a href="#page-24">24</a>
<a href="#appendix-A.6">A.6</a>. MultiPolygons . . . . . . . . . . . . . . . . . . . . . . <a href="#page-25">25</a>
<a href="#appendix-A.7">A.7</a>. GeometryCollections . . . . . . . . . . . . . . . . . . . <a href="#page-26">26</a>
<a href="#appendix-B">Appendix B</a>. Changes from the Pre-IETF GeoJSON Format
Specification . . . . . . . . . . . . . . . . . . . <a href="#page-26">26</a>
<a href="#appendix-B.1">B.1</a>. Normative Changes . . . . . . . . . . . . . . . . . . . . <a href="#page-26">26</a>
<a href="#appendix-B.2">B.2</a>. Informative Changes . . . . . . . . . . . . . . . . . . . <a href="#page-27">27</a>
<a href="#appendix-C">Appendix C</a>. GeoJSON Text Sequences . . . . . . . . . . . . . . . <a href="#page-27">27</a>
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-27">27</a>
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-28">28</a>
<span class="h2"><a class="selflink" name="section-1" href="#section-1">1</a>. Introduction</span>
GeoJSON is a format for encoding a variety of geographic data
structures using JavaScript Object Notation (JSON) [<a href="./rfc7159" title="&quot;The JavaScript Object Notation (JSON) Data Interchange Format&quot;">RFC7159</a>]. A
GeoJSON object may represent a region of space (a Geometry), a
spatially bounded entity (a Feature), or a list of Features (a
FeatureCollection). GeoJSON supports the following geometry types:
Point, LineString, Polygon, MultiPoint, MultiLineString,
MultiPolygon, and GeometryCollection. Features in GeoJSON contain a
Geometry object and additional properties, and a FeatureCollection
contains a list of Features.
The format is concerned with geographic data in the broadest sense;
anything with qualities that are bounded in geographical space might
be a Feature whether or not it is a physical structure. The concepts
in GeoJSON are not new; they are derived from preexisting open
geographic information system standards and have been streamlined to
better suit web application development using JSON.
GeoJSON comprises the seven concrete geometry types defined in the
OpenGIS Simple Features Implementation Specification for SQL [<a href="#ref-SFSQL" title="&quot;OpenGIS Simple Features Specification For SQL Revision 1.1&quot;">SFSQL</a>]:
0-dimensional Point and MultiPoint; 1-dimensional curve LineString
and MultiLineString; 2-dimensional surface Polygon and MultiPolygon;
<span class="grey">Butler, et al. Standards Track [Page 3]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-4" id="page-4" href="#page-4" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
and the heterogeneous GeometryCollection. GeoJSON representations of
instances of these geometry types are analogous to the well-known
binary (WKB) and well-known text (WKT) representations described in
that same specification.
GeoJSON also comprises the types Feature and FeatureCollection.
Feature objects in GeoJSON contain a Geometry object with one of the
above geometry types and additional members. A FeatureCollection
object contains an array of Feature objects. This structure is
analogous to that of the Web Feature Service (WFS) response to
GetFeatures requests specified in [<a href="#ref-WFSv1" title="&quot;Web Feature Service Implementation Specification&quot;">WFSv1</a>] or to a Keyhole Markup
Language (KML) Folder of Placemarks [<a href="#ref-KMLv2.2" title="&quot;OGC KML&quot;">KMLv2.2</a>]. Some implementations
of the WFS specification also provide GeoJSON-formatted responses to
GetFeature requests, but there is no particular service model or
Feature type ontology implied in the GeoJSON format specification.
Since its initial publication in 2008 [<a href="#ref-GJ2008" title="&quot;The GeoJSON Format Specification&quot;">GJ2008</a>], the GeoJSON format
specification has steadily grown in popularity. It is widely used in
JavaScript web-mapping libraries, JSON-based document databases, and
web APIs.
<span class="h3"><a class="selflink" name="section-1.1" href="#section-1.1">1.1</a>. Requirements Language</span>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[<a href="./rfc2119" title="&quot;Key words for use in RFCs to Indicate Requirement Levels&quot;">RFC2119</a>].
<span class="h3"><a class="selflink" name="section-1.2" href="#section-1.2">1.2</a>. Conventions Used in This Document</span>
The ordering of the members of any JSON object defined in this
document MUST be considered irrelevant, as specified by [<a href="./rfc7159" title="&quot;The JavaScript Object Notation (JSON) Data Interchange Format&quot;">RFC7159</a>].
Some examples use the combination of a JavaScript single-line comment
(//) followed by an ellipsis (...) as placeholder notation for
content deemed irrelevant by the authors. These placeholders must of
course be deleted or otherwise replaced, before attempting to
validate the corresponding JSON code example.
Whitespace is used in the examples inside this document to help
illustrate the data structures, but it is not required. Unquoted
whitespace is not significant in JSON.
<span class="h3"><a class="selflink" name="section-1.3" href="#section-1.3">1.3</a>. Specification of GeoJSON</span>
This document supersedes the original GeoJSON format specification
[<a href="#ref-GJ2008" title="&quot;The GeoJSON Format Specification&quot;">GJ2008</a>].
<span class="grey">Butler, et al. Standards Track [Page 4]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-5" id="page-5" href="#page-5" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h3"><a class="selflink" name="section-1.4" href="#section-1.4">1.4</a>. Definitions</span>
o JavaScript Object Notation (JSON), and the terms object, member,
name, value, array, number, true, false, and null, are to be
interpreted as defined in [<a href="./rfc7159" title="&quot;The JavaScript Object Notation (JSON) Data Interchange Format&quot;">RFC7159</a>].
o Inside this document, the term "geometry type" refers to seven
case-sensitive strings: "Point", "MultiPoint", "LineString",
"MultiLineString", "Polygon", "MultiPolygon", and
"GeometryCollection".
o As another shorthand notation, the term "GeoJSON types" refers to
nine case-sensitive strings: "Feature", "FeatureCollection", and
the geometry types listed above.
o The word "Collection" in "FeatureCollection" and
"GeometryCollection" does not have any significance for the
semantics of array members. The "features" and "geometries"
members, respectively, of these objects are standard ordered JSON
arrays, not unordered sets.
<span class="h3"><a class="selflink" name="section-1.5" href="#section-1.5">1.5</a>. Example</span>
A GeoJSON FeatureCollection:
{
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [102.0, 0.5]
},
"properties": {
"prop0": "value0"
}
}, {
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[102.0, 0.0],
[103.0, 1.0],
[104.0, 0.0],
[105.0, 1.0]
]
},
"properties": {
<span class="grey">Butler, et al. Standards Track [Page 5]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-6" id="page-6" href="#page-6" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
"prop0": "value0",
"prop1": 0.0
}
}, {
"type": "Feature",
"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": {
"this": "that"
}
}
}]
}
<span class="h2"><a class="selflink" name="section-2" href="#section-2">2</a>. GeoJSON Text</span>
A GeoJSON text is a JSON text and consists of a single GeoJSON
object.
<span class="h2"><a class="selflink" name="section-3" href="#section-3">3</a>. GeoJSON Object</span>
A GeoJSON object represents a Geometry, Feature, or collection of
Features.
o A GeoJSON object is a JSON object.
o A GeoJSON object has a member with the name "type". The value of
the member MUST be one of the GeoJSON types.
o A GeoJSON object MAY have a "bbox" member, the value of which MUST
be a bounding box array (see <a href="#section-5">Section 5</a>).
o A GeoJSON object MAY have other members (see <a href="#section-6">Section 6</a>).
<span class="grey">Butler, et al. Standards Track [Page 6]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-7" id="page-7" href="#page-7" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h3"><a class="selflink" name="section-3.1" href="#section-3.1">3.1</a>. Geometry Object</span>
A Geometry object represents points, curves, and surfaces in
coordinate space. Every Geometry object is a GeoJSON object no
matter where it occurs in a GeoJSON text.
o The value of a Geometry object's "type" member MUST be one of the
seven geometry types (see <a href="#section-1.4">Section 1.4</a>).
o A GeoJSON Geometry object of any type other than
"GeometryCollection" has a member with the name "coordinates".
The value of the "coordinates" member is an array. The structure
of the elements in this array is determined by the type of
geometry. GeoJSON processors MAY interpret Geometry objects with
empty "coordinates" arrays as null objects.
<span class="h4"><a class="selflink" name="section-3.1.1" href="#section-3.1.1">3.1.1</a>. Position</span>
A position is the fundamental geometry construct. The "coordinates"
member of a Geometry object is composed of either:
o one position in the case of a Point geometry,
o an array of positions in the case of a LineString or MultiPoint
geometry,
o an array of LineString or linear ring (see <a href="#section-3.1.6">Section 3.1.6</a>)
coordinates in the case of a Polygon or MultiLineString geometry,
or
o an array of Polygon coordinates in the case of a MultiPolygon
geometry.
A position is an array of numbers. There MUST be two or more
elements. The first two elements are longitude and latitude, or
easting and northing, precisely in that order and using decimal
numbers. Altitude or elevation MAY be included as an optional third
element.
Implementations SHOULD NOT extend positions beyond three elements
because the semantics of extra elements are unspecified and
ambiguous. Historically, some implementations have used a fourth
element to carry a linear referencing measure (sometimes denoted as
"M") or a numerical timestamp, but in most situations a parser will
not be able to properly interpret these values. The interpretation
and meaning of additional elements is beyond the scope of this
specification, and additional elements MAY be ignored by parsers.
<span class="grey">Butler, et al. Standards Track [Page 7]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-8" id="page-8" href="#page-8" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
A line between two positions is a straight Cartesian line, the
shortest line between those two points in the coordinate reference
system (see <a href="#section-4">Section 4</a>).
In other words, every point on a line that does not cross the
antimeridian between a point (lon0, lat0) and (lon1, lat1) can be
calculated as
F(lon, lat) = (lon0 + (lon1 - lon0) * t, lat0 + (lat1 - lat0) * t)
with t being a real number greater than or equal to 0 and smaller
than or equal to 1. Note that this line may markedly differ from the
geodesic path along the curved surface of the reference ellipsoid.
The same applies to the optional height element with the proviso that
the direction of the height is as specified in the coordinate
reference system.
Note that, again, this does not mean that a surface with equal height
follows, for example, the curvature of a body of water. Nor is a
surface of equal height perpendicular to a plumb line.
Examples of positions and geometries are provided in <a href="#appendix-A">Appendix A</a>,
"Geometry Examples".
<span class="h4"><a class="selflink" name="section-3.1.2" href="#section-3.1.2">3.1.2</a>. Point</span>
For type "Point", the "coordinates" member is a single position.
<span class="h4"><a class="selflink" name="section-3.1.3" href="#section-3.1.3">3.1.3</a>. MultiPoint</span>
For type "MultiPoint", the "coordinates" member is an array of
positions.
<span class="h4"><a class="selflink" name="section-3.1.4" href="#section-3.1.4">3.1.4</a>. LineString</span>
For type "LineString", the "coordinates" member is an array of two or
more positions.
<span class="h4"><a class="selflink" name="section-3.1.5" href="#section-3.1.5">3.1.5</a>. MultiLineString</span>
For type "MultiLineString", the "coordinates" member is an array of
LineString coordinate arrays.
<span class="grey">Butler, et al. Standards Track [Page 8]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-9" id="page-9" href="#page-9" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h4"><a class="selflink" name="section-3.1.6" href="#section-3.1.6">3.1.6</a>. Polygon</span>
To specify a constraint specific to Polygons, it is useful to
introduce the concept of a linear ring:
o A linear ring is a closed LineString with four or more positions.
o The first and last positions are equivalent, and they MUST contain
identical values; their representation SHOULD also be identical.
o A linear ring is the boundary of a surface or the boundary of a
hole in a surface.
o A linear ring MUST follow the right-hand rule with respect to the
area it bounds, i.e., exterior rings are counterclockwise, and
holes are clockwise.
Note: the [<a href="#ref-GJ2008" title="&quot;The GeoJSON Format Specification&quot;">GJ2008</a>] specification did not discuss linear ring winding
order. For backwards compatibility, parsers SHOULD NOT reject
Polygons that do not follow the right-hand rule.
Though a linear ring is not explicitly represented as a GeoJSON
geometry type, it leads to a canonical formulation of the Polygon
geometry type definition as follows:
o For type "Polygon", the "coordinates" member MUST be an array of
linear ring coordinate arrays.
o For Polygons with more than one of these rings, the first MUST be
the exterior ring, and any others MUST be interior rings. The
exterior ring bounds the surface, and the interior rings (if
present) bound holes within the surface.
<span class="h4"><a class="selflink" name="section-3.1.7" href="#section-3.1.7">3.1.7</a>. MultiPolygon</span>
For type "MultiPolygon", the "coordinates" member is an array of
Polygon coordinate arrays.
<span class="h4"><a class="selflink" name="section-3.1.8" href="#section-3.1.8">3.1.8</a>. GeometryCollection</span>
A GeoJSON object with type "GeometryCollection" is a Geometry object.
A GeometryCollection has a member with the name "geometries". The
value of "geometries" is an array. Each element of this array is a
GeoJSON Geometry object. It is possible for this array to be empty.
<span class="grey">Butler, et al. Standards Track [Page 9]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-10" id="page-10" href="#page-10" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
Unlike the other geometry types described above, a GeometryCollection
can be a heterogeneous composition of smaller Geometry objects. For
example, a Geometry object in the shape of a lowercase roman "i" can
be composed of one point and one LineString.
GeometryCollections have a different syntax from single type Geometry
objects (Point, LineString, and Polygon) and homogeneously typed
multipart Geometry objects (MultiPoint, MultiLineString, and
MultiPolygon) but have no different semantics. Although a
GeometryCollection object has no "coordinates" member, it does have
coordinates: the coordinates of all its parts belong to the
collection. The "geometries" member of a GeometryCollection
describes the parts of this composition. Implementations SHOULD NOT
apply any additional semantics to the "geometries" array.
To maximize interoperability, implementations SHOULD avoid nested
GeometryCollections. Furthermore, GeometryCollections composed of a
single part or a number of parts of a single type SHOULD be avoided
when that single part or a single object of multipart type
(MultiPoint, MultiLineString, or MultiPolygon) could be used instead.
<span class="h4"><a class="selflink" name="section-3.1.9" href="#section-3.1.9">3.1.9</a>. Antimeridian Cutting</span>
In representing Features that cross the antimeridian,
interoperability is improved by modifying their geometry. Any
geometry that crosses the antimeridian SHOULD be represented by
cutting it in two such that neither part's representation crosses the
antimeridian.
For example, a line extending from 45 degrees N, 170 degrees E across
the antimeridian to 45 degrees N, 170 degrees W should be cut in two
and represented as a MultiLineString.
{
"type": "MultiLineString",
"coordinates": [
[
[170.0, 45.0], [180.0, 45.0]
], [
[-180.0, 45.0], [-170.0, 45.0]
]
]
}
<span class="grey">Butler, et al. Standards Track [Page 10]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-11" id="page-11" href="#page-11" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
A rectangle extending from 40 degrees N, 170 degrees E across the
antimeridian to 50 degrees N, 170 degrees W should be cut in two and
represented as a MultiPolygon.
{
"type": "MultiPolygon",
"coordinates": [
[
[
[180.0, 40.0], [180.0, 50.0], [170.0, 50.0],
[170.0, 40.0], [180.0, 40.0]
]
],
[
[
[-170.0, 40.0], [-170.0, 50.0], [-180.0, 50.0],
[-180.0, 40.0], [-170.0, 40.0]
]
]
]
}
<span class="h4"><a class="selflink" name="section-3.1.10" href="#section-3.1.10">3.1.10</a>. Uncertainty and Precision</span>
As in [<a href="./rfc5870" title="&quot;A Uniform Resource Identifier for Geographic Locations ('geo' URI)&quot;">RFC5870</a>], the number of digits of the values in coordinate
positions MUST NOT be interpreted as an indication to the level of
uncertainty.
<span class="h3"><a class="selflink" name="section-3.2" href="#section-3.2">3.2</a>. Feature Object</span>
A Feature object represents a spatially bounded thing. Every Feature
object is a GeoJSON object no matter where it occurs in a GeoJSON
text.
o A Feature object has a "type" member with the value "Feature".
o A Feature object has a member with the name "geometry". The value
of the geometry member SHALL be either a Geometry object as
defined above or, in the case that the Feature is unlocated, a
JSON null value.
o A Feature object has a member with the name "properties". The
value of the properties member is an object (any JSON object or a
JSON null value).
<span class="grey">Butler, et al. Standards Track [Page 11]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-12" id="page-12" href="#page-12" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
o If a Feature has a commonly used identifier, that identifier
SHOULD be included as a member of the Feature object with the name
"id", and the value of this member is either a JSON string or
number.
<span class="h3"><a class="selflink" name="section-3.3" href="#section-3.3">3.3</a>. FeatureCollection Object</span>
A GeoJSON object with the type "FeatureCollection" is a
FeatureCollection object. A FeatureCollection object has a member
with the name "features". The value of "features" is a JSON array.
Each element of the array is a Feature object as defined above. It
is possible for this array to be empty.
<span class="h2"><a class="selflink" name="section-4" href="#section-4">4</a>. Coordinate Reference System</span>
The coordinate reference system for all GeoJSON coordinates is a
geographic coordinate reference system, using the World Geodetic
System 1984 (WGS 84) [<a href="#ref-WGS84" title="&quot;Department of Defense World Geodetic System 1984: Its Definition and Relationships with Local Geodetic Systems&quot;">WGS84</a>] datum, with longitude and latitude units
of decimal degrees. This is equivalent to the coordinate reference
system identified by the Open Geospatial Consortium (OGC) URN
urn:ogc:def:crs:OGC::CRS84. An OPTIONAL third-position element SHALL
be the height in meters above or below the WGS 84 reference
ellipsoid. In the absence of elevation values, applications
sensitive to height or depth SHOULD interpret positions as being at
local ground or sea level.
Note: the use of alternative coordinate reference systems was
specified in [<a href="#ref-GJ2008" title="&quot;The GeoJSON Format Specification&quot;">GJ2008</a>], but it has been removed from this version of
the specification because the use of different coordinate reference
systems -- especially in the manner specified in [<a href="#ref-GJ2008" title="&quot;The GeoJSON Format Specification&quot;">GJ2008</a>] -- has
proven to have interoperability issues. In general, GeoJSON
processing software is not expected to have access to coordinate
reference system databases or to have network access to coordinate
reference system transformation parameters. However, where all
involved parties have a prior arrangement, alternative coordinate
reference systems can be used without risk of data being
misinterpreted.
<span class="h2"><a class="selflink" name="section-5" href="#section-5">5</a>. Bounding Box</span>
A GeoJSON object MAY have a member named "bbox" to include
information on the coordinate range for its Geometries, Features, or
FeatureCollections. The value of the bbox member MUST be an array of
length 2*n where n is the number of dimensions represented in the
contained geometries, with all axes of the most southwesterly point
followed by all axes of the more northeasterly point. The axes order
of a bbox follows the axes order of geometries.
<span class="grey">Butler, et al. Standards Track [Page 12]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-13" id="page-13" href="#page-13" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
The "bbox" values define shapes with edges that follow lines of
constant longitude, latitude, and elevation.
Example of a 2D bbox member on a Feature:
{
"type": "Feature",
"bbox": [-10.0, -10.0, 10.0, 10.0],
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-10.0, -10.0],
[10.0, -10.0],
[10.0, 10.0],
[-10.0, -10.0]
]
]
}
//...
}
Example of a 2D bbox member on a FeatureCollection:
{
"type": "FeatureCollection",
"bbox": [100.0, 0.0, 105.0, 1.0],
"features": [
//...
]
}
Example of a 3D bbox member with a depth of 100 meters:
{
"type": "FeatureCollection",
"bbox": [100.0, 0.0, -100.0, 105.0, 1.0, 0.0],
"features": [
//...
]
}
<span class="grey">Butler, et al. Standards Track [Page 13]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-14" id="page-14" href="#page-14" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h3"><a class="selflink" name="section-5.1" href="#section-5.1">5.1</a>. The Connecting Lines</span>
The four lines of the bounding box are defined fully within the
coordinate reference system; that is, for a box bounded by the values
"west", "south", "east", and "north", every point on the northernmost
line can be expressed as
(lon, lat) = (west + (east - west) * t, north)
with 0 &lt;= t &lt;= 1.
<span class="h3"><a class="selflink" name="section-5.2" href="#section-5.2">5.2</a>. The Antimeridian</span>
Consider a set of point Features within the Fiji archipelago,
straddling the antimeridian between 16 degrees S and 20 degrees S.
The southwest corner of the box containing these Features is at 20
degrees S and 177 degrees E, and the northwest corner is at 16
degrees S and 178 degrees W. The antimeridian-spanning GeoJSON
bounding box for this FeatureCollection is
"bbox": [177.0, -20.0, -178.0, -16.0]
and covers 5 degrees of longitude.
The complementary bounding box for the same latitude band, not
crossing the antimeridian, is
"bbox": [-178.0, -20.0, 177.0, -16.0]
and covers 355 degrees of longitude.
The latitude of the northeast corner is always greater than the
latitude of the southwest corner, but bounding boxes that cross the
antimeridian have a northeast corner longitude that is less than the
longitude of the southwest corner.
<span class="h3"><a class="selflink" name="section-5.3" href="#section-5.3">5.3</a>. The Poles</span>
A bounding box that contains the North Pole extends from a southwest
corner of "minlat" degrees N, 180 degrees W to a northeast corner of
90 degrees N, 180 degrees E. Viewed on a globe, this bounding box
approximates a spherical cap bounded by the "minlat" circle of
latitude.
"bbox": [-180.0, minlat, 180.0, 90.0]
<span class="grey">Butler, et al. Standards Track [Page 14]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-15" id="page-15" href="#page-15" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
A bounding box that contains the South Pole extends from a southwest
corner of 90 degrees S, 180 degrees W to a northeast corner of
"maxlat" degrees S, 180 degrees E.
"bbox": [-180.0, -90.0, 180.0, maxlat]
A bounding box that just touches the North Pole and forms a slice of
an approximate spherical cap when viewed on a globe extends from a
southwest corner of "minlat" degrees N and "westlon" degrees E to a
northeast corner of 90 degrees N and "eastlon" degrees E.
"bbox": [westlon, minlat, eastlon, 90.0]
Similarly, a bounding box that just touches the South Pole and forms
a slice of an approximate spherical cap when viewed on a globe has
the following representation in GeoJSON.
"bbox": [westlon, -90.0, eastlon, maxlat]
Implementers MUST NOT use latitude values greater than 90 or less
than -90 to imply an extent that is not a spherical cap.
<span class="h2"><a class="selflink" name="section-6" href="#section-6">6</a>. Extending GeoJSON</span>
<span class="h3"><a class="selflink" name="section-6.1" href="#section-6.1">6.1</a>. Foreign Members</span>
Members not described in this specification ("foreign members") MAY
be used in a GeoJSON document. Note that support for foreign members
can vary across implementations, and no normative processing model
for foreign members is defined. Accordingly, implementations that
rely too heavily on the use of foreign members might experience
reduced interoperability with other implementations.
For example, in the (abridged) Feature object shown below
{
"type": "Feature",
"id": "f1",
"geometry": {...},
"properties": {...},
"title": "Example Feature"
}
the name/value pair of "title": "Example Feature" is a foreign
member. When the value of a foreign member is an object, all the
descendant members of that object are themselves foreign members.
<span class="grey">Butler, et al. Standards Track [Page 15]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-16" id="page-16" href="#page-16" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
GeoJSON semantics do not apply to foreign members and their
descendants, regardless of their names and values. For example, in
the (abridged) Feature object below
{
"type": "Feature",
"id": "f2",
"geometry": {...},
"properties": {...},
"centerline": {
"type": "LineString",
"coordinates": [
[-170, 10],
[170, 11]
]
}
}
the "centerline" member is not a GeoJSON Geometry object.
<span class="h2"><a class="selflink" name="section-7" href="#section-7">7</a>. GeoJSON Types Are Not Extensible</span>
Implementations MUST NOT extend the fixed set of GeoJSON types:
FeatureCollection, Feature, Point, LineString, MultiPoint, Polygon,
MultiLineString, MultiPolygon, and GeometryCollection.
<span class="h3"><a class="selflink" name="section-7.1" href="#section-7.1">7.1</a>. Semantics of GeoJSON Members and Types Are Not Changeable</span>
Implementations MUST NOT change the semantics of GeoJSON members and
types.
The GeoJSON "coordinates" and "geometries" members define Geometry
objects. FeatureCollection and Feature objects, respectively, MUST
NOT contain a "coordinates" or "geometries" member.
The GeoJSON "geometry" and "properties" members define a Feature
object. FeatureCollection and Geometry objects, respectively, MUST
NOT contain a "geometry" or "properties" member.
The GeoJSON "features" member defines a FeatureCollection object.
Feature and Geometry objects, respectively, MUST NOT contain a
"features" member.
<span class="grey">Butler, et al. Standards Track [Page 16]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-17" id="page-17" href="#page-17" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h2"><a class="selflink" name="section-8" href="#section-8">8</a>. Versioning</span>
The GeoJSON format can be extended as defined here, but no explicit
versioning scheme is defined. A specification that alters the
semantics of GeoJSON members or otherwise modifies the format does
not create a new version of this format; instead, it defines an
entirely new format that MUST NOT be identified as GeoJSON.
<span class="h2"><a class="selflink" name="section-9" href="#section-9">9</a>. Mapping 'geo' URIs</span>
'geo' URIs [<a href="./rfc5870" title="&quot;A Uniform Resource Identifier for Geographic Locations ('geo' URI)&quot;">RFC5870</a>] identify geographic locations and precise (not
uncertain) locations can be mapped to GeoJSON Geometry objects.
For this section, as in [<a href="./rfc5870" title="&quot;A Uniform Resource Identifier for Geographic Locations ('geo' URI)&quot;">RFC5870</a>], "lat", "lon", "alt", and "unc" are
placeholders for 'geo' URI latitude, longitude, altitude, and
uncertainty values, respectively.
A 'geo' URI with two coordinates and an uncertainty ('u') parameter
that is absent or zero, and a GeoJSON Point geometry may be mapped to
each other. A GeoJSON Point is always converted to a 'geo' URI that
has no uncertainty parameter.
'geo' URI:
geo:lat,lon
GeoJSON:
{"type": "Point", "coordinates": [lon, lat]}
The mapping between 'geo' URIs and GeoJSON Points that specify
elevation is shown below.
'geo' URI:
geo:lat,lon,alt
GeoJSON:
{"type": "Point", "coordinates": [lon, lat, alt]}
GeoJSON has no concept of uncertainty; imprecise or uncertain 'geo'
URIs thus cannot be mapped to GeoJSON geometries.
<span class="grey">Butler, et al. Standards Track [Page 17]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-18" id="page-18" href="#page-18" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h2"><a class="selflink" name="section-10" href="#section-10">10</a>. Security Considerations</span>
GeoJSON shares security issues common to all JSON content types. See
<a href="./rfc7159#section-12">[RFC7159], Section&nbsp;12</a> for additional information. GeoJSON does not
provide executable content.
GeoJSON does not provide privacy or integrity services. If sensitive
data requires privacy or integrity protection, those must be provided
by the transport -- for example, Transport Layer Security (TLS) or
HTTPS. There will be cases in which stored data need protection,
which is out of scope for this document.
As with other geographic data formats, e.g., [<a href="#ref-KMLv2.2" title="&quot;OGC KML&quot;">KMLv2.2</a>], providing
details about the locations of sensitive persons, animals, habitats,
and facilities can expose them to unauthorized tracking or injury.
Data providers should recognize the risk of inadvertently identifying
individuals if locations in anonymized datasets are not adequately
skewed or not sufficiently fuzzed [<a href="#ref-Sweeney" title="&quot;k-anonymity: a model for protecting privacy&quot;">Sweeney</a>] and recognize that the
effectiveness of location obscuration is limited by a number of
factors and is unlikely to be an effective defense against a
determined attack [<a href="./rfc6772" title="&quot;Geolocation Policy: A Document Format for Expressing Privacy Preferences for Location Information&quot;">RFC6772</a>].
<span class="h2"><a class="selflink" name="section-11" href="#section-11">11</a>. Interoperability Considerations</span>
<span class="h3"><a class="selflink" name="section-11.1" href="#section-11.1">11.1</a>. I-JSON</span>
GeoJSON texts should follow the constraints of Internet JSON (I-JSON)
[<a href="./rfc7493" title="&quot;The I-JSON Message Format&quot;">RFC7493</a>] for maximum interoperability.
<span class="h3"><a class="selflink" name="section-11.2" href="#section-11.2">11.2</a>. Coordinate Precision</span>
The size of a GeoJSON text in bytes is a major interoperability
consideration, and precision of coordinate values has a large impact
on the size of texts. A GeoJSON text containing many detailed
Polygons can be inflated almost by a factor of two by increasing
coordinate precision from 6 to 15 decimal places. For geographic
coordinates with units of degrees, 6 decimal places (a default common
in, e.g., sprintf) amounts to about 10 centimeters, a precision well
within that of current GPS systems. Implementations should consider
the cost of using a greater precision than necessary.
Furthermore, the WGS 84 [<a href="#ref-WGS84" title="&quot;Department of Defense World Geodetic System 1984: Its Definition and Relationships with Local Geodetic Systems&quot;">WGS84</a>] datum is a relatively coarse
approximation of the geoid, with the height varying by up to 5 m (but
generally between 2 and 3 meters) higher or lower relative to a
surface parallel to Earth's mean sea level.
<span class="grey">Butler, et al. Standards Track [Page 18]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-19" id="page-19" href="#page-19" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h2"><a class="selflink" name="section-12" href="#section-12">12</a>. IANA Considerations</span>
The media type for GeoJSON text is "application/geo+json" and is
registered in the "Media Types" registry described in [<a href="./rfc6838" title="&quot;Media Type Specifications and Registration Procedures&quot;">RFC6838</a>]. The
entry for "application/vnd.geo+json" in the same registry should have
its status changed to be "OBSOLETED" with a pointer to the media type
"application/geo+json" and a reference added to this RFC.
Type name: application
Subtype name: geo+json
Required parameters: n/a
Optional parameters: n/a
Encoding considerations: binary
Security considerations: See <a href="#section-10">Section 10</a> above
Interoperability considerations: See <a href="#section-11">Section 11</a> above
Published specification: [[<a href="./rfc7946">RFC7946</a>]]
Applications that use this media type: No known applications
currently use this media type. This media type is intended for
GeoJSON applications currently using the "application/
vnd.geo+json" or "application/json" media types, of which there
are several categories: web mapping, geospatial databases,
geographic data processing APIs, data analysis and storage
services, and data dissemination.
Additional information:
Magic number(s): n/a
File extension(s): .json, .geojson
Macintosh file type code: n/a
Object Identifiers: n/a
Windows clipboard name: GeoJSON
Macintosh uniform type identifier: public.geojson conforms to
public.json
<span class="grey">Butler, et al. Standards Track [Page 19]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-20" id="page-20" href="#page-20" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
Person to contact for further information: Sean Gillies
(sean.gillies@gmail.com)
Intended usage: COMMON
Restrictions on usage: none
Restrictions on usage: none
Author: see "Authors' Addresses" section of [[<a href="./rfc7946">RFC7946</a>]].
Change controller: Internet Engineering Task Force
<span class="h2"><a class="selflink" name="section-13" href="#section-13">13</a>. References</span>
<span class="h3"><a class="selflink" name="section-13.1" href="#section-13.1">13.1</a>. Normative References</span>
[<a name="ref-RFC2119" id="ref-RFC2119">RFC2119</a>] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", <a href="./bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>,
DOI 10.17487/RFC2119, March 1997,
&lt;<a href="http://www.rfc-editor.org/info/rfc2119">http://www.rfc-editor.org/info/rfc2119</a>&gt;.
[<a name="ref-RFC6838" id="ref-RFC6838">RFC6838</a>] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", <a href="./bcp13">BCP 13</a>,
<a href="./rfc6838">RFC 6838</a>, DOI 10.17487/RFC6838, January 2013,
&lt;<a href="http://www.rfc-editor.org/info/rfc6838">http://www.rfc-editor.org/info/rfc6838</a>&gt;.
[<a name="ref-RFC7159" id="ref-RFC7159">RFC7159</a>] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", <a href="./rfc7159">RFC 7159</a>, DOI 10.17487/RFC7159, March
2014, &lt;<a href="http://www.rfc-editor.org/info/rfc7159">http://www.rfc-editor.org/info/rfc7159</a>&gt;.
[<a name="ref-RFC7493" id="ref-RFC7493">RFC7493</a>] Bray, T., Ed., "The I-JSON Message Format", <a href="./rfc7493">RFC 7493</a>,
DOI 10.17487/RFC7493, March 2015,
&lt;<a href="http://www.rfc-editor.org/info/rfc7493">http://www.rfc-editor.org/info/rfc7493</a>&gt;.
[<a name="ref-WGS84" id="ref-WGS84">WGS84</a>] National Imagery and Mapping Agency, "Department of
Defense World Geodetic System 1984: Its Definition and
Relationships with Local Geodetic Systems", Third Edition,
1984.
<span class="grey">Butler, et al. Standards Track [Page 20]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-21" id="page-21" href="#page-21" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h3"><a class="selflink" name="section-13.2" href="#section-13.2">13.2</a>. Informative References</span>
[<a name="ref-GJ2008" id="ref-GJ2008">GJ2008</a>] Butler, H., Daly, M., Doyle, A., Gillies, S., Schaub, T.,
and C. Schmidt, "The GeoJSON Format Specification", June
2008.
[<a name="ref-KMLv2.2" id="ref-KMLv2.2">KMLv2.2</a>] Wilson, T., "OGC KML", OGC 07-147r2, Version 2.2.0, April
2008.
[<a name="ref-RFC5870" id="ref-RFC5870">RFC5870</a>] Mayrhofer, A. and C. Spanring, "A Uniform Resource
Identifier for Geographic Locations ('geo' URI)",
<a href="./rfc5870">RFC 5870</a>, DOI 10.17487/RFC5870, June 2010,
&lt;<a href="http://www.rfc-editor.org/info/rfc5870">http://www.rfc-editor.org/info/rfc5870</a>&gt;.
[<a name="ref-RFC6772" id="ref-RFC6772">RFC6772</a>] Schulzrinne, H., Ed., Tschofenig, H., Ed., Cuellar, J.,
Polk, J., Morris, J., and M. Thomson, "Geolocation Policy:
A Document Format for Expressing Privacy Preferences for
Location Information", <a href="./rfc6772">RFC 6772</a>, DOI 10.17487/RFC6772,
January 2013, &lt;<a href="http://www.rfc-editor.org/info/rfc6772">http://www.rfc-editor.org/info/rfc6772</a>&gt;.
[<a name="ref-RFC7464" id="ref-RFC7464">RFC7464</a>] Williams, N., "JavaScript Object Notation (JSON) Text
Sequences", <a href="./rfc7464">RFC 7464</a>, DOI 10.17487/RFC7464, February 2015,
&lt;<a href="http://www.rfc-editor.org/info/rfc7464">http://www.rfc-editor.org/info/rfc7464</a>&gt;.
[<a name="ref-SFSQL" id="ref-SFSQL">SFSQL</a>] OpenGIS Consortium, Inc., "OpenGIS Simple Features
Specification For SQL Revision 1.1", OGC 99-049, May 1999.
[<a name="ref-Sweeney" id="ref-Sweeney">Sweeney</a>] Sweeney, L., "k-anonymity: a model for protecting
privacy", International Journal on Uncertainty, Fuzziness
and Knowledge-based Systems 10 (5), 2002; 557-570,
DOI 10.1142/S0218488502001648, 2002.
[<a name="ref-WFSv1" id="ref-WFSv1">WFSv1</a>] Vretanos, P., "Web Feature Service Implementation
Specification", OGC 04-094, Version 1.1.0, May 2005.
<span class="grey">Butler, et al. Standards Track [Page 21]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-22" id="page-22" href="#page-22" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h2"><a class="selflink" name="appendix-A" href="#appendix-A">Appendix A</a>. Geometry Examples</span>
Each of the examples below represents a valid and complete GeoJSON
object.
<span class="h3"><a class="selflink" name="appendix-A.1" href="#appendix-A.1">A.1</a>. Points</span>
Point coordinates are in x, y order (easting, northing for projected
coordinates, longitude, and latitude for geographic coordinates):
{
"type": "Point",
"coordinates": [100.0, 0.0]
}
<span class="h3"><a class="selflink" name="appendix-A.2" href="#appendix-A.2">A.2</a>. LineStrings</span>
Coordinates of LineString are an array of positions (see
<a href="#section-3.1.1">Section 3.1.1</a>):
{
"type": "LineString",
"coordinates": [
[100.0, 0.0],
[101.0, 1.0]
]
}
<span class="grey">Butler, et al. Standards Track [Page 22]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-23" id="page-23" href="#page-23" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h3"><a class="selflink" name="appendix-A.3" href="#appendix-A.3">A.3</a>. Polygons</span>
Coordinates of a Polygon are an array of linear ring (see
<a href="#section-3.1.6">Section 3.1.6</a>) coordinate arrays. 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.8, 0.8],
[100.8, 0.2],
[100.2, 0.2],
[100.2, 0.8],
[100.8, 0.8]
]
]
}
<span class="grey">Butler, et al. Standards Track [Page 23]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-24" id="page-24" href="#page-24" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h3"><a class="selflink" name="appendix-A.4" href="#appendix-A.4">A.4</a>. MultiPoints</span>
Coordinates of a MultiPoint are an array of positions:
{
"type": "MultiPoint",
"coordinates": [
[100.0, 0.0],
[101.0, 1.0]
]
}
<span class="h3"><a class="selflink" name="appendix-A.5" href="#appendix-A.5">A.5</a>. MultiLineStrings</span>
Coordinates of a MultiLineString are an array of LineString
coordinate arrays:
{
"type": "MultiLineString",
"coordinates": [
[
[100.0, 0.0],
[101.0, 1.0]
],
[
[102.0, 2.0],
[103.0, 3.0]
]
]
}
<span class="grey">Butler, et al. Standards Track [Page 24]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-25" id="page-25" href="#page-25" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h3"><a class="selflink" name="appendix-A.6" href="#appendix-A.6">A.6</a>. MultiPolygons</span>
Coordinates of a MultiPolygon are an array of Polygon coordinate
arrays:
{
"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.2, 0.8],
[100.8, 0.8],
[100.8, 0.2],
[100.2, 0.2]
]
]
]
}
<span class="grey">Butler, et al. Standards Track [Page 25]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-26" id="page-26" href="#page-26" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
<span class="h3"><a class="selflink" name="appendix-A.7" href="#appendix-A.7">A.7</a>. GeometryCollections</span>
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]
]
}]
}
<span class="h2"><a class="selflink" name="appendix-B" href="#appendix-B">Appendix B</a>. Changes from the Pre-IETF GeoJSON Format Specification</span>
This appendix briefly summarizes non-editorial changes from the 2008
specification [<a href="#ref-GJ2008" title="&quot;The GeoJSON Format Specification&quot;">GJ2008</a>].
<span class="h3"><a class="selflink" name="appendix-B.1" href="#appendix-B.1">B.1</a>. Normative Changes</span>
o Specification of coordinate reference systems has been removed,
i.e., the "crs" member of [<a href="#ref-GJ2008" title="&quot;The GeoJSON Format Specification&quot;">GJ2008</a>] is no longer used.
o In the absence of elevation values, applications sensitive to
height or depth SHOULD interpret positions as being at local
ground or sea level (see <a href="#section-4">Section 4</a>).
o Implementations SHOULD NOT extend position arrays beyond 3
elements (see <a href="#section-3.1.1">Section 3.1.1</a>).
o A line between two positions is a straight Cartesian line (see
<a href="#section-3.1.1">Section 3.1.1</a>).
o Polygon rings MUST follow the right-hand rule for orientation
(counterclockwise external rings, clockwise internal rings).
o The values of a "bbox" array are "[west, south, east, north]", not
"[minx, miny, maxx, maxy]" (see <a href="#section-5">Section 5</a>).
o A Feature object's "id" member is a string or number (see
<a href="#section-3.2">Section 3.2</a>).
<span class="grey">Butler, et al. Standards Track [Page 26]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-27" id="page-27" href="#page-27" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
o Extensions MAY be used, but MUST NOT change the semantics of
GeoJSON members and types (see <a href="#section-6">Section 6</a>).
o GeoJSON objects MUST NOT contain the defining members of other
types (see <a href="#section-7.1">Section 7.1</a>).
o The media type for GeoJSON is "application/geo+json".
<span class="h3"><a class="selflink" name="appendix-B.2" href="#appendix-B.2">B.2</a>. Informative Changes</span>
o The definition of a GeoJSON text has been added.
o Rules for mapping 'geo' URIs have been added.
o A recommendation of the I-JSON [<a href="./rfc7493" title="&quot;The I-JSON Message Format&quot;">RFC7493</a>] constraints has been
added.
o Implementers are cautioned about the effect of excessive
coordinate precision on interoperability.
o Interoperability concerns of GeometryCollections are noted. These
objects should be used sparingly (see <a href="#section-3.1.8">Section 3.1.8</a>).
<span class="h2"><a class="selflink" name="appendix-C" href="#appendix-C">Appendix C</a>. GeoJSON Text Sequences</span>
All GeoJSON objects defined in this specification --
FeatureCollection, Feature, and Geometry -- consist of exactly one
JSON object. However, there may be circumstances in which
applications need to represent sets or sequences of these objects
(over and above the grouping of Feature objects in a
FeatureCollection), e.g., in order to efficiently "stream" large
numbers of Feature objects. The definition of such sets or sequences
is outside the scope of this specification.
If such a representation is needed, a new media type is required that
has the ability to represent these sets or sequences. When defining
such a media type, it may be useful to base it on "JavaScript Object
Notation (JSON) Text Sequences" [<a href="./rfc7464" title="&quot;JavaScript Object Notation (JSON) Text Sequences&quot;">RFC7464</a>], leaving the foundations of
how to represent multiple JSON objects to that specification, and
only defining how it applies to GeoJSON objects.
Acknowledgements
The GeoJSON format is the product of discussion on the GeoJSON
mailing list, &lt;<a href="http://lists.geojson.org/listinfo.cgi/geojson-geojson.org">http://lists.geojson.org/listinfo.cgi/</a>
<a href="http://lists.geojson.org/listinfo.cgi/geojson-geojson.org">geojson-geojson.org</a>&gt;, before October 2015 and in the IETF's GeoJSON
WG after October 2015.
<span class="grey">Butler, et al. Standards Track [Page 27]</span></pre>
<hr class='noprint' style='width: 96ex;' align='left'/><!--NewPage--><pre class='newpage'><a name="page-28" id="page-28" href="#page-28" class="invisible"> </a>
<span class="grey"><a href="./rfc7946">RFC 7946</a> GeoJSON August 2016</span>
Material in this document was adapted with changes from
&lt;<a href="http://geojson.org/geojson-spec.html">http://geojson.org/geojson-spec.html</a>&gt; [<a href="#ref-GJ2008" title="&quot;The GeoJSON Format Specification&quot;">GJ2008</a>], which is licensed
under &lt;<a href="http://creativecommons.org/licenses/by/3.0/us/">http://creativecommons.org/licenses/by/3.0/us/</a>&gt;.
Authors' Addresses
Howard Butler
Hobu Inc.
Email: howard@hobu.co
Martin Daly
Cadcorp
Email: martin.daly@cadcorp.com
Allan Doyle
Email: adoyle@intl-interfaces.com
Sean Gillies
Mapbox
Email: sean.gillies@gmail.com
URI: <a href="http://sgillies.net">http://sgillies.net</a>
Stefan Hagen
Rheinaustr. 62
Bonn 53225
Germany
Email: stefan@hagen.link
URI: <a href="http://stefan-hagen.website/">http://stefan-hagen.website/</a>
Tim Schaub
Planet Labs
Email: tim.schaub@gmail.com
Butler, et al. Standards Track [Page 28]
</pre><br />
<span class="noprint"><small><small>Html markup produced by rfcmarkup 1.127, available from
<a href="https://tools.ietf.org/tools/rfcmarkup/">https://tools.ietf.org/tools/rfcmarkup/</a>
</small></small></span>
</div>
</body>
</html>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment