RFC 5870
A Uniform Resource Identifier for Geographic Locations ('geo' URI)
RFC 5870: A Uniform Resource Identifier for Geographic Locations ('geo' URI) 🌍
okay bestie, let's start with the receipts 📜 This one is RFC 5870, published in June 2010 by the IETF. The authors are A. Mayrhofer (from IPCom) and C. Spanring. It's on the Standards Track and carries ISSN 2070-1721. The title block doesn't list anything it obsoletes or updates ✨
Abstract 🦋
okay so this doc defines a Uniform Resource Identifier (URI) for geographic locations using the geo scheme name 🗺️ A geo URI points to a physical spot in a two- or three-dimensional coordinate reference system. It's compact, simple, human-readable, and works with any protocol 💖 The default coordinate reference system is the World Geodetic System 1984 (WGS-84) 🌏
Status of This Memo ✨
this is an Internet Standards Track document 🎀
it's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community 🫶 It got public review and was approved for publication by the Internet Engineering Steering Group (IESG) 👑 If you want more on Internet Standards, check Section 2 of RFC 5741 📚
for the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc5870 💅
Copyright Notice ©️
Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. 🌸
this document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the date this document was published 📜 Please read these carefully, bestie, because they explain your rights and restrictions for 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 they come without warranty as described in the Simplified BSD License 💜
this document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008 🕰️ The person or people who control the copyright in some of that material may not have given the IETF Trust permission to allow modifications outside the IETF Standards Process 😭 So unless you get an adequate license from whoever controls that copyright, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process 🚫 The exceptions are formatting it for publication as an RFC or translating it into languages other than English 🌈
Table of Contents 📚
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. IANA Registration of the 'geo' URI Scheme . . . . . . . . . . 6
3.1. URI Scheme Name . . . . . . . . . . . . . . . . . . . . . 6
3.2. Status . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.3. URI Scheme Syntax . . . . . . . . . . . . . . . . . . . . 6
3.4. URI Scheme Semantics . . . . . . . . . . . . . . . . . . . 7
3.4.1. Coordinate Reference System Identification . . . . . . 7
3.4.2. Component Description for WGS-84 . . . . . . . . . . . 8
3.4.3. Location Uncertainty . . . . . . . . . . . . . . . . . 8
3.4.4. URI Comparison . . . . . . . . . . . . . . . . . . . . 9
3.4.5. Interpretation of Undefined Altitude . . . . . . . . . 10
3.5. Encoding Considerations . . . . . . . . . . . . . . . . . 10
3.6. Applications/Protocols That Use This URI Scheme . . . . . 11
3.7. Interoperability Considerations . . . . . . . . . . . . . 11
3.8. Security Considerations . . . . . . . . . . . . . . . . . 11
3.9. Contact . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.10. Author/Change Controller . . . . . . . . . . . . . . . . . 12
3.11. References . . . . . . . . . . . . . . . . . . . . . . . . 12
4. 'geo' URI Parameters Registry . . . . . . . . . . . . . . . . 12
5. URI Operations . . . . . . . . . . . . . . . . . . . . . . . . 13
6. Use Cases and Examples . . . . . . . . . . . . . . . . . . . . 13
6.1. Plain 'geo' URI Example . . . . . . . . . . . . . . . . . 13
6.2. Hyperlink . . . . . . . . . . . . . . . . . . . . . . . . 14
6.3. 'geo' URI in 2-Dimensional Barcode . . . . . . . . . . . . 15
6.4. Comparison Examples . . . . . . . . . . . . . . . . . . . 15
7. GML Mappings . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.1. 2D GML 'Point' . . . . . . . . . . . . . . . . . . . . . . 17
7.2. 3D GML 'Point' . . . . . . . . . . . . . . . . . . . . . . 17
7.3. GML 'Circle' . . . . . . . . . . . . . . . . . . . . . . . 17
7.4. GML 'Sphere' . . . . . . . . . . . . . . . . . . . . . . . 18
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
8.1. 'geo' URI Scheme . . . . . . . . . . . . . . . . . . . . . 18
8.2. URI Parameter Registry . . . . . . . . . . . . . . . . . . 19
8.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 19
8.2.2. Registration Policy . . . . . . . . . . . . . . . . . 19
8.3. Sub-Registry for 'crs' Parameter . . . . . . . . . . . . . 20
8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 20
8.3.2. Registration Policy . . . . . . . . . . . . . . . . . 20
9. Security Considerations . . . . . . . . . . . . . . . . . . . 20
9.1. Invalid Locations . . . . . . . . . . . . . . . . . . . . 21
9.2. Location Privacy . . . . . . . . . . . . . . . . . . . . . 21
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 21
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22
11.1. Normative References . . . . . . . . . . . . . . . . . . . 22
11.2. Informative References . . . . . . . . . . . . . . . . . . 221. Introduction ✨
more and more Internet protocols and data formats get extended with specs for adding spatial (geographic) location 🌍 Usually latitude and longitude of simple points get slapped on as new attributes on existing data structures 🙃 The problem is all of those methods are super specific to one data format or protocol, so none of them give you a protocol-independent, compact, generic way to refer to a physical geographic location 😩
location-aware apps and location-based services are blowing up on the Internet 🚀 Most web search engines use geographic info, and the open source mapping community has brought so much momentum into location-aware tech 🔥 Tools and data sets that used to be only for professionals are now available to a much wider audience 🫶
the geo URI scheme is the next step in that direction 🦋 It aims to make location identification in geospatial services and applications easier to support and standardize 🎀 Getting info about a location or triggering another service should be just as easy as clicking a 'mailto:' link and writing an email right away 💌
according to [RFC3986], a Uniform Resource Identifier (URI) is "a compact sequence of characters that identifies an abstract or physical resource" 📖 The geo URI scheme in this document identifies geographic locations (physical resources) in a coordinate reference system (CRS), which is WGS-84 [WGS84] by default 🌏 It gives a text version of the location's coordinates in either two or three dimensions: latitude, longitude, and optionally altitude for the default CRS of WGS-84 ✨ Here's an example:
geo:13.4125,103.8667these URIs don't depend on any specific protocol, app, or data format, so they can go in any protocol or data format that lets you include arbitrary URIs 💜
for usability's sake, the scheme is strictly focused on the simplest and most common way to represent a location: a single point in a well-known CRS 💅 Anything more complex, or locations described by civic addresses, is out of scope for this document 🙈
the optional crs URI parameter described below may be used by future specifications to define the use of CRSes other than WGS-84 🌸 This mainly exists for the case where another CRS replaces WGS-84 as the predominant one 👑 It's not about letting anyone use thousands of CRSes in the URI, since that would clearly hurt interoperability 😬 So defining crs values beyond the default of "wgs84" is out of scope for this document 🚫
this spec discourages the use of alternate CRSes in use cases where comparison is an important function ⚠️
Note: The choice of WGS-84 as the default CRS is based on how widely available Global Positioning System (GPS) devices are, since they use the WGS-84 reference system 🛰️ Devices like that are expected to be one of the main data sources for authoringgeoURIs, which is why the native GPS reference system got adopted for the URI scheme 🧚 Plus, lots of other data formats for geographic locations also use WGS-84, which makes converting to and from them less error prone, because no re-projection is involved 🙌 It's also believed that the burden of any spatial transformations that might be needed should land on the author rather than the consumer ofgeoURI instances 💖
because of their similar structure, geo URI instances can also be mapped from and to certain ISO 6709 [ISO.6709.2008] string representations of geographic point locations 🍓
2. Terminology 📐
geographic locations in this document are defined using WGS-84 (World Geodetic System 1984), which is equivalent to the International Association of Oil & Gas Producers (OGP) Surveying and Positioning Committee EPSG (European Petroleum Survey Group) codes 4326 (2 dimensions) and 4979 (3 dimensions) 🗂️ This document doesn't assign responsibility for coordinate transformations from and to other Spatial Reference Systems 🙅♀️
a 2-dimensional WGS-84 coordinate value is written as a comma-delimited latitude/longitude pair, measured in decimal degrees (un-projected) 🎀 A 3-dimensional WGS-84 coordinate value adds a comma-delimited altitude value in meters onto those pairs 🦋
latitudes range from -90 to 90, and longitudes range from -180 to 180 🌍 Coordinates in the Southern and Western hemispheres, plus altitudes below the WGS-84 reference geoid (depths), are signed negative with a leading dash ➖
the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119] 🧠 these are the official BCP 14 keywords, so they carry the exact meaning from RFC 2119 💅
3. IANA Registration of the 'geo' URI Scheme 📝
this section has the fields required for the URI scheme registration, following the guidelines in Section 5.4 of [RFC4395] 🗒️
3.1. URI Scheme Name 🏷️
the scheme name is:
geo3.2. Status 🌟
the status is:
permanent3.3. URI Scheme Syntax
okay bestie, the whole syntax is written in ABNF [RFC5234] (the grammar language standards nerds use 💅). here's the full vibe 🎀
geo-URI = geo-scheme ":" geo-path
geo-scheme = "geo"
geo-path = coordinates p
coordinates = coord-a "," coord-b [ "," coord-c ]
coord-a = num
coord-b = num
coord-c = num
p = [ crsp ] [ uncp ] *parameter
crsp = ";crs=" crslabel
crslabel = "wgs84" / labeltext
uncp = ";u=" uval
uval = pnum
parameter = ";" pname [ "=" pvalue ]
pname = labeltext
pvalue = 1*paramchar
paramchar = p-unreserved / unreserved / pct-encoded
labeltext = 1*( alphanum / "-" )
pnum = 1*DIGIT [ "." 1*DIGIT ]
num = [ "-" ] pnum
unreserved = alphanum / mark
mark = "-" / "_" / "." / "!" / "~" / "*" /
"'" / "(" / ")"
pct-encoded = "%" HEXDIG HEXDIG
p-unreserved = "[" / "]" / ":" / "&" / "+" / "$"
alphanum = ALPHA / DIGITparameter names are case insensitive ✨ but lowercase is the preferred look 🍓 for non-numeric parameter values, case sensitivity MUST be described in the spec of that specific parameter. for the 'crs' parameter, values are case insensitive and lowercase is preferred.
now the big rules 👑 both 'crs' and 'u' MUST NOT appear more than once each. the 'crs' and 'u' parameters MUST be given before any other parameters that might be defined in future extensions. and if you use both, 'crs' MUST be given first. defining other parameters, and any <crslabel> values beyond the default "wgs84", is out of scope for this doc. section 8.2 talks about how those extra parameters and values get registered with IANA 🧚
the value "-0" for <num> is allowed and is identical to "0" (lol, math is so funny sometimes 🙈)
if the URI identifies a location in the default CRS of WGS-84, the <coordinates> sub-components get extra restrictions:
coord-a = latitude
coord-b = longitude
coord-c = altitude
latitude = [ "-" ] 1*2DIGIT [ "." 1*DIGIT ]
longitude = [ "-" ] 1*3DIGIT [ "." 1*DIGIT ]
altitude = [ "-" ] 1*DIGIT [ "." 1*DIGIT ]3.4. URI Scheme Semantics
okay so the data in a 'geo' URI points at a physical resource 🌍 basically a spatial location, identified by its geographic coordinates plus the CRS that's encoded in the URI. main character energy fr 💅
3.4.1. Coordinate Reference System Identification
the meaning of <coordinates> depends entirely on the CRS of the URI 🦋 the CRS is identified by the optional 'crs' parameter. a URI uses the default WGS-84 CRS if the 'crs' parameter is either missing or has the value 'wgs84'. other <crslabel> values aren't defined yet, but future documents might define them ✨
ngl this part is so important 😭 interpreting coordinates in the wrong CRS gives you invalid location info. so consumers of 'geo' URIs MUST NOT ignore the 'crs' parameter if it's given, and they MUST NOT interpret the <coordinates> sub-components without considering and understanding the 'crs' parameter value.
this section only talks about the default CRS (WGS-84). future docs that specify other 'crs' values MUST provide similar descriptions for the <coordinates> sub-components in the CRS they describe 🎀
3.4.2. Component Description for WGS-84
here's how the <latitude>, <longitude>, and <altitude> components from the syntax (Section 3.3) get used 🫶
- <latitude> MUST contain the latitude of the identified location, in decimal degrees, in the reference system WGS-84.
- <longitude> MUST contain the longitude of the identified location, in decimal degrees, in the reference system WGS-84.
- If present, the OPTIONAL <altitude> MUST contain the altitude of the identified location, in meters, in the reference system WGS-84.
if the altitude of the location is unknown, then <altitude> (and the comma before it) MUST NOT be present in the URI. and bestie, unknown altitude MUST NOT be represented by setting <altitude> to "0" (or any other arbitrary value) 💀 don't do the fake zero thing!!
the <longitude> of coordinate values reflecting the poles (<latitude> set to -90 or 90 degrees) SHOULD be set to "0". but consumers of 'geo' URIs MUST accept such URIs with any longitude value from -180 to 180 🌸
'geo' URIs with longitude values outside the range -180 to 180 decimal degrees, or with latitude values outside the range -90 to 90 degrees, MUST be considered invalid. rip to those 🙅♀️
3.4.3. Location Uncertainty
the 'u' ("uncertainty") parameter says how much uncertainty there is in the location, as a value in meters 🧁 when a 'geo' URI is used to identify the location of a particular object, <uval> shows how uncertain we are about where the subject actually is.
the 'u' parameter is optional, and it can appear only once. if it isn't specified, that means the uncertainty is unknown or unspecified. if the goal is to point at one specific spot in space, <uval> MAY be set to zero. but zero uncertainty and absent uncertainty are never the same thing!! 🙅♀️✨
the single uncertainty value applies to all the dimensions given in the URI.
Note: the number of digits in the values in <coordinates> MUST NOT be read as an indication of how uncertain the location is. no sneaky decimal math 🙈
3.4.4. URI Comparison
comparing URIs is about figuring out whether two URI strings are equivalent and point at the same resource 🔍 (it's not comparing the actual resources themselves). so comparing two 'geo' URIs doesn't compare the spatial objects, just the strings (URIs) that identify them 💜
the term "mathematically identical" used below means some components of the URI MUST be compared as normalized numbers rather than as strings. that's because different string representations can be the same number (like "43.10" and "43.1" are different strings, but they represent the same number 🍓).
two 'geo' URIs are equal only if they pass all of these general comparison rules:
- both URIs use the same CRS. that means either both have the 'crs' parameter omitted, or both have the same <crslabel> value, or one omits the 'crs' parameter while the other explicitly specifies the default CRS with a <crslabel> value of "wgs84".
- their <coord-a>, <coord-b>, <coord-c> and 'u' values are mathematically identical (including an absent <uval>, which means an undefined 'u' value).
- their sets of other parameters are equal, with comparison operations applied to each parameter as described in its own specification.
parameter order doesn't matter for URI comparison 🫶
new parameters can get registered over time, so legacy implementations of 'geo' URIs might run into unknown parameters. in that case, these rules apply:
- two 'geo' URIs with unknown parameters are equivalent only if the same set of unknown parameter names shows up in each URI, and their values are bitwise identical after percent-decoding.
- otherwise, the comparison for those URIs is undefined (because the legacy implementation can't know the comparison rules for those parameters 😵💫).
if you're designing future extension parameters, keep this in mind when you choose their comparison rules 🧚
a URI with an undefined (missing) <coord-c> (altitude) value MUST NOT be considered equal to a URI that contains a <coord-c>, even if the remaining <coord-a>, <coord-b>, and 'u' values are equivalent.
for the default CRS of WGS-84, these extra comparison rules also apply:
- if the <latitude> of a 'geo' URI is set to either 90 or -90 degrees, then <longitude> MUST be ignored in comparison operations (the "poles case" 🧊).
- a <longitude> of 180 degrees MUST be considered equal to a <longitude> of -180 degrees for the purpose of URI comparison (the "date line" case 🌏).
3.4.5. Interpretation of Undefined Altitude
a consumer of a 'geo' URI in the WGS-84 CRS with an undefined <altitude> MAY assume that the URI refers to the matching location on Earth's physical surface at that latitude and longitude 🌱
BUT (and this is a big but 🚨) altitudes are relative to the WGS-84 reference geoid, not Earth's surface. so an <altitude> value of 0 MUST NOT be mistaken for "ground elevation". don't mix those up, bestie!
3.5. Encoding Considerations
the <coordinates> path component of the 'geo' URI (see Section 3.3) uses a comma (",") as the delimiter between subcomponents. this delimiter MUST NOT be percent-encoded 🚫
it is RECOMMENDED that, for readability, the contents of <coord-a>, <coord-b>, and <coord-c>, as well as <crslabel> and <uval>, are never percent-encoded 🎀
for internationalization: the components defined right now only allow ASCII characters, so they don't need any internationalization work 🌈 future specs that add extra parameters might allow non-ASCII values. those specs MUST describe the internationalization considerations for their parameters and values, and MUST require percent-encoding of non-ASCII values.
3.6. Applications/Protocols That Use This URI Scheme
like lots of other URI scheme definitions, the 'geo' URI gives you resource identification that doesn't depend on any specific application or protocol 💅 examples of possible protocol mappings and use cases are in Section 6 ✨
3.7. Interoperability Considerations
like other new URI schemes, the 'geo' URI needs support in client applications 🫶 users of apps that don't know about the 'geo' scheme probably can't directly use the info in the URI. but a client can still make indirect use of it by passing 'geo' URIs around, even without understanding the format and semantics of the scheme 🦋 and the simple structure means a human could even dereference one manually 🙈
clients MUST NOT attempt to dereference 'geo' URIs given in a CRS that's unknown to the client, because that would produce entirely bogus results 💀
authors of 'geo' URIs should carefully check that the coordinate components are set in the right CRS and in the specified order. the wrong order of components (or using coordinates from a different CRS without transforming them) are commonly seen mistakes that produce completely bogus locations 🙃
the number of digits in the <coordinates> values MUST NOT be interpreted as an indication of a certain level of accuracy or uncertainty.
3.8. Security Considerations
see Section 9 of RFC 5870 🔐
3.9. Contact
Alexander Mayrhofer <axelm@ipcom.at>, <http://geouri.org/>
Christian Spanring <christian@spanring.eu>3.10. Author/Change Controller
the 'geo' URI scheme is registered under the IETF part of the URI tree 🌳 which means change control is up to the IETF 👑
3.11. References
RFC 5870 📚
4. 'geo' URI Parameters Registry ✨
Okay bestie, so this spec creates a brand new IANA registry called "'geo' URI Parameters" 📋 for the <parameter> component of the URI. Parameters for the 'geo' URI and their values MUST be registered with IANA, because that's how we avoid namespace collisions and keep everyone interoperable 🫶
Some parameters only accept values that match a syntax definition, some only take values from a predefined set, and some don't take any values at all (those are the "flag" type ones) 💅
Registering values is REQUIRED for any parameter that takes values from a predefined set. 🔥
The spec for a parameter MUST fully explain its syntax, intended usage, and semantics so that independent implementations can actually agree with each other 🧚
For parameters that aren't limited to a predefined set and aren't the "flag" type, the syntax of allowed values MUST be described in the specification, for example by using ABNF.
Documents that define new parameters (or new values for existing parameters) MUST register them with IANA, as explained in Section 8.2. 💖
The 'geo' URI Parameter Registry has a column called "Value Restriction" that tells you whether a parameter accepts a value, and whether those values are restricted to a predefined set. That column accepts the following values:
"No value": The parameter doesn't accept any values and is only used as a "flag". 🚩"Predefined": The parameter accepts values from a predefined set only, as specified in an RFC or other permanent and readily available public specification. 📜"Constrained": The parameter accepts arbitrary values that are only constrained by a syntax, as specified in an RFC or other permanent and readily available public specification. 🎀
Section 8.2.1 contains the initial contents of the Registry. ✨
5. URI Operations 🌸
Right now there's only one operation on a 'geo' URI: location dereference. The client dereferences the URI by pulling the geographical coordinates out of the URI path component <geo-path>. What happens with those coordinates (and the uncertainty value from <uval>) after that is totally up to the application processing the URI, and it might depend on the context of the URI 🧚
An application can then use that location info for all sorts of things, like:
- A web browser could use it to open a mapping service of the user's choice and show a map of the location. 🗺️
- A navigational device, like a Global Positioning System (GPS) receiver, could offer the user the ability to start navigation to the location. 🧭
Note that the examples and use cases above, as well as the ones in the next section, are non-normative and only here for information 🫶
6. Use Cases and Examples 💅
6.1. Plain 'geo' URI Example
The following 3-dimensional 'geo' URI points to the office of one of the authors in Vienna, Austria 🏢
geo:48.2010,16.3695,183When you resolve it, you get this info:
- The
crsparameter isn't in the URI, which means the URI uses the default CRS of WGS-84. 🌍 - The URI includes
<coord-c>, so it's 3-dimensional, and it usesurn:ogc:def:crs:EPSG::4979as the WGS-84 CRS identifier. - The
<coord-a>value (latitude in WGS-84) is48.2010decimal degrees. - The
<coord-b>value (longitude in WGS-84) is16.3695decimal degrees. - The
<coord-c>value (altitude in WGS-84) is 183 meters. - Uncertainty is undefined. 🤷♀️
You could type the data from this URI into an electronic navigation device, or even use it to find the location on a paper map 🗺️✨
6.2. Hyperlink
'geo' URIs (like any other URI scheme) can also be embedded as hyperlinks in web pages 🌈 A Hyper Text Markup Language (HTML) snippet with one of these links could look like this:
<p>one of Vienna's popular sights is the
<a href='geo:48.198634,16.371648;crs=wgs84;u=40'>Karlskirche</a>.When you resolve it, here's the tea:
- The
crsis given in the URI, which sets the CRS used in the URI to WGS-84 explicitly. 💅 - The URI omits
<coord-c>, so it's 2-dimensional, and it usesurn:ogc:def:crs:EPSG::4326as the WGS-84 CRS identifier. - The
<coord-a>value (latitude in WGS-84) is48.198634decimal degrees. - The
<coord-b>value (longitude in WGS-84) is16.371648decimal degrees. - The
<coord-c>(altitude) value is undefined, so the client MAY assume the identified location is on Earth's physical surface. 🌏 - The
uparameter is included, setting uncertainty to 40 meters. 🎯
A web browser could use this info from the HTML snippet and offer the user different options (based on configuration and context), like:
- Showing a small map thumbnail when the mouse pointer hovers over the link. 🖱️
- Switching to a mapping service of the user's choice once the link is selected. 🗺️
- Finding nearby resources, for example by comparing the 'geo' URI with locations pulled from GeoRSS feeds the user has subscribed to. 📡
- Converting the coordinates into a format that can be uploaded to a navigation device. 📲
Note that the URI in this example also makes use of the explicit specification of the CRS with the crs parameter. 🫶
6.3. 'geo' URI in 2-Dimensional Barcode
Because it's so short, a 'geo' URI can easily be encoded in a 2-dimensional barcode 🦋 These barcodes can be printed on business cards, flyers, and paper maps, and then used by mobile devices, like this:
- The user spots a barcode on a flyer and uses the camera on their phone to photograph and decode it. 📸
- The phone dereferences the 'geo' URI and offers the user the ability to calculate a navigation route to the identified location. 🛣️
- Using the builtin GPS receiver, the user follows the navigation instructions to reach the location. 🎉
6.4. Comparison Examples
Okay, this part is giving math class but make it cute 🧮 This section shows examples of URI comparison. The unknown parameters 'foo' and 'bar', and the unregistered 'crs' values, are only used for illustration here. Including them below doesn't count as any formal parameter definition or registration request 💜
- The two URIs
<geo:90,-22.43;crs=WGS84>and<geo:90,46>are equal. They use the same CRS, and even though the longitude values are different, both reflect a location on the north pole (the special "poles" rule for WGS-84 applies, so longitude is ignored) ❄️ Note that 'crs' parameter values are case insensitive. - The URIs
<geo:22.300;-118.44>and<geo:22.3;-118.4400>are equal, because their coordinate components are mathematically identical. 🔢 - The set of
<geo:66,30;u=6.500;FOo=this%2dthat>and<geo:66.0,30;u=6.5;foo=this-that>is identical. The value of the unknown parameter 'foo' is bitwise identical after percent-decoding, parameter names are case insensitive, and coordinates and uncertainty are mathematically identical. 🫶 - The comparison operation on
<geo:70,20;foo=1.00;bar=white>and<geo:70,20;foo=1;bar=white>in a legacy implementation is undefined 😬 The normalization rules for 'foo' aren't known, so the implementation can't tell whether '1.00' is identical to '1' for the 'foo' parameter. - Comparing
<geo:47,11;foo=blue;bar=white>and<geo:47,11;bar=white;foo=blue>returns true, because parameter order doesn't matter in comparison operations. ✨ - The comparison operation on
<geo:22,0;bar=Blue>and<geo:22,0;BAR=blue>is undefined. Even though parameter names are case insensitive, that isn't necessarily true for the values of the unknown 'bar' parameter 🙈
7. GML Mappings 🧚
The Geographic Markup Language (GML) by the Open Geospatial Consortium (OGC) is a set of XML schemas that represent geographical features 🗺️ GML is widely accepted, so this document includes instructions for transforming 'geo' URIs to and from GML fragments. The instructions in this section are not normative 💅
For the sections that follow, %lat%, %lon%, %alt%, and %unc% are placeholders for the latitude, longitude, altitude, and uncertainty values. The mappings use WGS-84 and are defined in the sections below.
Note: GML fragments in other reference systems could be used too, as long as a transformation into urn:ogc:def:crs:EPSG::4979 or urn:ogc:def:crs:EPSG::4326 is defined and applied before the mapping step. Those transformations are typically not lossless ⚠️
GML uses the 'double' type from XML Schema, and the mapping examples assume that numbers in the form of 3.32435e2 in GML are properly converted to fixed point when they're placed into the 'geo' URI.
7.1. 2D GML 'Point'
A 2D GML 'Point' [RFC5491] is built from a 'geo' URI that has two coordinates and an uncertainty ('u') parameter that's either absent or zero 📍 A GML point always converts to a 'geo' URI with no uncertainty parameter.
'geo' URI:
geo:%lat%,%lon%GML fragment:
<Point srsName="urn:ogc:def:crs:EPSG::4326"
xmlns="http://www.opengis.net/gml">
<pos>%lat% %lon%</pos>
</Point>Note that a 'geo' URI with an uncertainty value of zero converts to a GML 'Point', but a GML 'Point' can't be translated into a 'geo' URI with zero uncertainty 🙃
7.2. 3D GML 'Point'
A 3D GML 'Point' [RFC5491] is built from a 'geo' URI that has three coordinates and an uncertainty parameter that's either absent or zero 🏔️ A GML point always converts to a 'geo' URI with no uncertainty parameter.
'geo' URI:
geo:%lat%,%lon%,%alt%GML fragment:
<Point srsName="urn:ogc:def:crs:EPSG::4979"
xmlns="http://www.opengis.net/gml">
<pos>%lat% %lon% %alt%</pos>
</Point>7.3. GML 'Circle'
A GML 'Circle' [RFC5491] is built from a 'geo' URI that has two coordinates and an uncertainty parameter that's present and non-zero ⭕
'geo' URI:
geo:%lat%,%lon%;u=%unc%GML fragment:
<gs:Circle srsName="urn:ogc:def:crs:EPSG::4326"
xmlns:gml="http://www.opengis.net/gml"
xmlns:gs="http://www.opengis.net/pidflo/1.0">
<gml:pos>%lat% %lon%</gml:pos>
<gs:radius uom="urn:ogc:def:uom:EPSG::9001">
%unc%
</gs:radius>
</gs:Circle>7.4. GML 'Sphere'
A GML 'sphere' [RFC5491] is built from a 'geo' URI that has three coordinates and an uncertainty parameter that's present and non-zero 🔮
'geo' URI:
geo:%lat%,%lon%,%alt%;u=%unc%GML fragment:
<gs:Sphere srsName="urn:ogc:def:crs:EPSG::4979"
xmlns:gml="http://www.opengis.net/gml"
xmlns:gs="http://www.opengis.net/pidflo/1.0">
<gml:pos>%lat% %lon% %alt%</gml:pos>
<gs:radius uom="urn:ogc:def:uom:EPSG::9001">
%unc%
</gs:radius>
</gs:Sphere>8. IANA Considerations 📋
8.1. 'geo' URI Scheme
This document creates the 'geo' URI scheme in the IETF part of the URI scheme tree, following the guidelines in BCP 115 (RFC 4395) [RFC4395]. The definitions required for the assignment are contained in Section 3. 🎀
8.2. URI Parameter Registry 🎀
okay bestie, so this doc creates a brand new IANA registry called "'geo' URI Parameters" 📋 The rules live in Section 4, and the actual definition is right here 💅
8.2.1. Registry Contents 📝
When registering a new 'geo' URI Parameter, the following information MUST be provided:
- Name of the Parameter.
- Whether the Parameter accepts no value ("No value"), values from a predefined set ("Predefined"), or values constrained by a syntax only ("Constrained").
- Reference to the RFC or other permanent and readily available public specification defining the parameters and the new values.
Unless specific instructions exist for a Parameter (like the definition of a Sub-registry), the following information MUST be provided when registering new values for existing "Predefined" 'geo' URI Parameters:
- Name of the Parameter.
- Reference to the RFC or other permanent and readily available public specification defining the new values.
The following table provides the initial values for this registry:
Parameter Name Value Restriction Reference(s)
----------------------------------------------------------
crs Predefined [RFC5870]
u Constrained [RFC5870]8.2.2. Registration Policy 🔐
The Registration Policy for 'geo' URI Parameters and their value definitions is "Specification Required" (which implies "Designated Expert"), as defined in [RFC5226]. ✨
8.3. Sub-Registry for 'crs' Parameter 🌍
This document creates a new IANA Sub-registry named "'geo' URI 'crs' Parameter Values", based on the Registry specified in Section 8.2 and the information in this section and Section 4. The syntax of the 'crs' parameter is constrained by the ABNF given in Section 3.3. 🧚
8.3.1. Registry Contents 📝
When registering a new value for the 'crs' parameter, the following information MUST be provided:
- Value of the parameter.
- Reference to the RFC or other permanent and readily available public specification defining the use of the CRS in the scope of the 'geo' URI. The specification should contain information that is similar to the WGS-84-specific text given in this document.
- Reference to the definition document of the CRS. If a URN is assigned to the CRS, the use of such URN as reference is preferred. Note that different URNs may exist for the 2-dimensional and 3-dimensional case.
The following table provides the initial values for this registry:
crs Value CRS definition(s) Reference(s)
-----------------------------------------------------------
wgs84 urn:ogc:def:crs:EPSG::4326 [RFC5870]
urn:ogc:def:crs:EPSG::4979 [RFC5870]8.3.2. Registration Policy 🔐
The registration policy for the "'geo' URI 'crs' Parameter Values" Registry shall require both "Specification Required" and "IESG Approval", as defined in [RFC5226]. Section 1 contains some text about the motivation for when to introduce new 'crs' values. 🌸
9. Security Considerations 💀
Okay, this part is serious, so listen up 🫶 Because the 'geo' URI is not tied to any specific protocol and identifies a physical location rather than a network resource, most of the general security considerations on URIs (Section 7 of RFC 3986) do not apply. However, the following (additional) issues apply:
9.1. Invalid Locations 🙈
The URI syntax (Section 3.3) makes it possible to construct 'geo' URIs that don't identify a valid location. Applications MUST NOT use URIs with such values and SHOULD warn the user when such URIs are encountered.
An example of such a URI referring to an invalid location would be <geo:94,0> (latitude "beyond" north pole). 😭
9.2. Location Privacy 🔒
A 'geo' URI by itself is just an opaque reference to a physical location, expressed by a set of spatial coordinates. This does not fit the "Location Information" definition according to Section 5.2 of GEOPRIV Requirements [RFC3693], because there is not necessarily a "Device" involved.
Because there is also no way to specify the identity of a "Target" within the confines of a 'geo' URI, it also does not fit the specification of a "Location Object" (Section 5.2 of RFC 3693).
However, if a 'geo' URI is used in a context where it identifies the location of a Target, it becomes part of a Location Object and is therefore subject to GEOPRIV rules. 👀
Therefore, when 'geo' URIs are put into such contexts, the privacy requirements of RFC 3693 MUST be met. Don't skip this one, bestie! 🚨
10. Acknowledgements 🫶
Martin Thomson has provided significant text around the definition of the "uncertainty" parameter and the GML mappings. 💜
The authors further wish to acknowledge the helpful contributions from Carl Reed, Bill McQuillan, Martin Kofal, Andrew Turner, Kim Sanders, Ted Hardie, Cullen Jennings, Klaus Darilion, Bjoern Hoehrmann, Alissa Cooper, and Ivan Shmakov. 🌈
Alfred Hoenes has provided an extremely helpful in-depth review of the document. 👑
11. References 📚
11.1. Normative References
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5491] Winterbottom, J., Thomson, M., and H. Tschofenig, "GEOPRIV Presence Information Data Format Location Object (PIDF-LO) Usage Clarification, Considerations, and Recommendations", RFC 5491, March 2009.
11.2. Informative References
[RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and Registration Procedures for New URI Schemes", BCP 35, RFC 4395, February 2006.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008.
[RFC3693] Cuellar, J., Morris, J., Mulligan, D., Peterson, J., and J. Polk, "Geopriv Requirements", RFC 3693, February 2004.
[WGS84] National Imagery and Mapping Agency, "Department of Defense World Geodetic System 1984, Third Edition", NIMA TR8350.2, January 2000.
[ISO.6709.2008] International Organization for Standardization, "Standard representation of geographic point location by coordinates", ISO Standard 6709, 2008.
Authors' Addresses 📮
Alexander Mayrhofer
IPCom GmbH
Karlsplatz 1/2/9
Wien A-1010
Austria
Phone: +43 1 5056416 34
Email: alexander.mayrhofer@ipcom.at
URI: http://www.ipcom.at/
Christian Spanring
73 Josephine Ave
Somerville 02144
Email: christian@spanring.eu
URI: http://www.spanring.eu/And that's the whole spec, bestie! 🌈✨ You made it through all of RFC 5870 💖
📦 where this page comes from
- ietf: rfc5870 2010-06
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms