GEOPRIV R. George
Internet-Draft Q. Sun
Intended status: Standards Track Huawei Technologies
Expires: January 14, 2010 July 13, 2009
Geodetic-Civic Address Translation Protocol
draft-george-geopriv-address-translation-01
Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 14, 2010.
Copyright Notice
Copyright (c) 2009 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 in effect on the date of
publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.
Abstract
This document explains how to map a geodetic datum to a civic address
and vice versa. Server accepts an HTTP POST with one form of user
specified location addresses and return whatever other form it has.
George & Sun Expires January 14, 2010 [Page 1]
Internet-Draft Location translation protocol July 2009
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology Used in This Document . . . . . . . . . . . . . . 3
3. Coordinate System Translation . . . . . . . . . . . . . . . . 3
3.1. Reverse Geocoding: Geodetic-Civic Translation . . . . . . 3
3.1.1. Reverse Geocoder Service Requirements . . . . . . . . 4
3.1.2. Example . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Geocoding: Civic-Geodetic Translation . . . . . . . . . . 7
3.2.1. Geocoder Service Requirements . . . . . . . . . . . . 7
3.2.2. Example . . . . . . . . . . . . . . . . . . . . . . . 8
4. The Accuracy . . . . . . . . . . . . . . . . . . . . . . . . . 10
5. The Error Codes . . . . . . . . . . . . . . . . . . . . . . . 12
6. Security Considerations . . . . . . . . . . . . . . . . . . . 13
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14
8.1. Normative References . . . . . . . . . . . . . . . . . . . 14
8.2. Informative References . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14
George & Sun Expires January 14, 2010 [Page 2]
Internet-Draft Location translation protocol July 2009
1. Introduction
The growth of location-based services and increased access to real
time sensor feeds, the ability to access and exchange real-
time,dynamic geolocation information becomes more important. This
draft describes how to convert civic addresses as defined in
[RFC5139] to geodetic coordinates and vice versa.
An example of a simple Civic Address is 'Washington, DC'. Using a
Gazetteer service to geocode the address, a geodetic coordinate of
(40.8N, 73.9W) might be returned. Conversely, entering (40.8N,
73.9W) into a reverse geocoding service might return 'Washington DC'.
It is sending PIDF-LO (civic) to the server and getting a geodetic
address back. To use it, look up your location's co-ordinates, and
then enter them in the request. The corresponding response will
return the civic address of the requested coordinates. In the same
way the geodetic address obtained, if civic address information has
provided in the request.
The Geodetic-civic address translation SHOULD return standard errors
and status codes. The possible errors conditions are listed in the
Section 5.
2. Terminology Used in This Document
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 [RFC2119].
3. Coordinate System Translation
3.1. Reverse Geocoding: Geodetic-Civic Translation
This method performs the conversion of a latitude/longitude pair into
human-readable addresses. A reverse geocoder service is a network-
accessible service that transforms a given position (geodetic
coordinate) into a normalized description of a feature location
(Address with Point), where the address may be defined as a street
address, intersection address, place name or postal code. A reverse
geocoding service could be a service supported in a location server.
The client or server sends a request to the location server/reverse
geocoding service containing the position expressed as geodetic
coordinates. If the address was successfully located, it sent back
to the requester. The response is a civic address for the given
George & Sun Expires January 14, 2010 [Page 3]
Internet-Draft Location translation protocol July 2009
geodetic address, and the response encoding (format) is described in
RFC [RFC5139]. In case of ambiguous addresses, only the point for
the best match is passed in the response.
3.1.1. Reverse Geocoder Service Requirements
The following requirements must be supported by the Reverse Geocoder
Service.
Given a Position ADT, must be able to return one or more locations
(i.e., Address ADTs with associated Point geometries), and
optionally, the ranges of these locations from the given position, as
it is defined in the Position ADT.
The form of the returned address(es) must be based upon the user's
preference, as stated in the request. The user should be able to
specify a preference of StreetAddress, StreetIntersection, or
PositionOfInterest (Place and/or PostalCode). If not specified, the
service should default to StreetAddress.
Must be capable of returning all location information of a preferred
type within an area of interest (AOI ADT - a Circle, Polygon or Box).
Must be able to indicate the number of matches in the response
(possibly zero) for a given request.
3.1.2. Example
George & Sun Expires January 14, 2010 [Page 4]
Internet-Draft Location translation protocol July 2009
POST /location HTTP/1.1
Host: lis.example.com:49152
Content-Type: application/held+xml
Content-Length: 1043
<?xml version="1.0"?>
<xs:schema targetNamespace="urn:ietf:params:
xml:ns:pidf:geopriv10:civicAddr"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:geoAddr"
xmlns:xml="http://www.w3.org/XML/1998/namespace" >
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd"/>
<locationRequest xmlns="urn:ietf:params:xml:ns:geopriv:held">
<locationType exact="true">civic</locationType>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
entity="pres:3650n87934c@ls.example.com">
<tuple id="b650sf789nd">
<status>
<geopriv xmlns="urn:ietf:params:xml:ns:pidf:geopriv10">
<location-info>
<Point xmlns="http://www.opengis.net/gml"
srsName="urn:ogc:def:crs:EPSG::4326">
<pos>-34.407 150.88001</pos>
</Point>
</location-info>
<usage-rules/>
</geopriv>
</status>
<timestamp>2006-01-10T03:42:28+00:00</timestamp>
</tuple>
</presence>
</locationRequest>
Requesting server to send the civic address of the latitude/longitude
pair given in the request.
George & Sun Expires January 14, 2010 [Page 5]
Internet-Draft Location translation protocol July 2009
HTTP/1.1 200 OK
Server: Example LIS
Date: Tue, 10 Jan 2006 03:42:29 GMT
Expires: Tue, 10 Jan 2006 03:42:29 GMT
Cache-control: private
Content-Type: application/held+xml
Content-Length: 1062
<locationResponse xmlns="urn:ietf:params:xml:ns:geopriv:held">
<presence xmlns="urn:ietf:params:xml:ns:pidf"
entity="pres:3650n87934c@ls.example.com">
<tuple id="b650sf789nd">
<status>
<geopriv xmlns="urn:ietf:params:xml:ns:pidf:geopriv10">
<location-info>
<ca:civicAddress
xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
xml:lang="en-au">
<ca:country>AU</ca:country>
<ca:A1>NSW</ca:A1>
<ca:A3>Wollongong</ca:A3>
<ca:A4>Gwynneville</ca:A4>
<ca:STS>Northfield Avenue</ca:STS>
<ca:LMK>University of Wollongong</ca:LMK>
<ca:FLR>2</ca:FLR>
<ca:NAM>Andrew Corporation</ca:NAM>
<ca:PC>2500</ca:PC>
<ca:BLD>39</ca:BLD>
<ca:SEAT>WS-183</ca:SEAT>
<ca:POBOX>U40</ca:POBOX>
</ca:civicAddress>
</location-info>
<usage-rules/>
</geopriv>
</status>
<timestamp>2006-01-10T03:42:28+00:00</timestamp>
</tuple>
</presence>
</locationResponse>
The given response is the result for a civic address request, where
the geodetic address is -34.407 150.88001.
The civic address includes the header fields that are defined in
[RFC5139]. We recommend that if a national or regional standard (and
George & Sun Expires January 14, 2010 [Page 6]
Internet-Draft Location translation protocol July 2009
schema) exists for encoding addresses, such as the US national
address coding standard, that this schema be supported in the
response. See also
draft-ietf-geopriv-civic-address-recommendations-03.
One thing that needs explanation is accuracy, which is a measure of
how accurately the system is returning location information. It
allows to specify whether it is 'exact', 'neighborhood' etc.
However, it is worth specifying how much deviation from the requested
location in terms of meters. If client sends a request with geodetic
address and there is no mapping found in the server, server could
return civic address which is close by. Also specify how much
deviation from the requested location in terms of meters.
3.2. Geocoding: Civic-Geodetic Translation
A geocoding service is a network-accessible service that transforms a
description of a location, such as a place name, street address or
postal code, into a normalized description of the location with a
Point geometry (geodetic coordinate). A geocoding service could be a
service supported in a location server to parse the given civic
address and get response back.
The server will attempt to find the closest addressable location
within a certain tolerance; if no match is found, the server will
usually return a status code, unknown addresses.
3.2.1. Geocoder Service Requirements
The following requirements must be supported by the Geocoder Service.
Given a Civic Address, must be capable of using an address matching
Geocoding algorithm to determine a position (geodetic coordinate) for
the specified address.
Must be capable of performing geocoding using an incomplete address
and return the complete set of address information (i.e., a
normalized address).
Must be able to indicate the number of matches in the response
(possibly zero) for a particular address supplied in the geocoding
request.
Must be capable of processing one or more addresses in a single
geocoding request.
George & Sun Expires January 14, 2010 [Page 7]
Internet-Draft Location translation protocol July 2009
May provide information on the quality of the result using a match
code.
May return the centroid of a zip code if an address is not complete.
May return an altitude if the service supports this capability.
3.2.2. Example
George & Sun Expires January 14, 2010 [Page 8]
Internet-Draft Location translation protocol July 2009
POST /location HTTP/1.1
Host: lis.example.com:49152
Content-Type: application/held+xml
Content-Length: 1484
<?xml version="1.0"?>
<xs:schema targetNamespace="urn:ietf:params:
xml:ns:pidf:geopriv10:geodeticAddr"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
xmlns:xml="http://www.w3.org/XML/1998/namespace" >
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd"/>
<locationRequest xmlns="urn:ietf:params:xml:ns:geopriv:held">
<locationType >geodetic</locationType>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
entity="pres:3650n87934c@ls.example.com">
<tuple id="b650sf789nd">
<status>
<geopriv xmlns="urn:ietf:params:xml:ns:pidf:geopriv10">
<location-info>
<ca:civicAddress
xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
xml:lang="en-au">
<ca:country>AU</ca:country>
<ca:A1>NSW</ca:A1>
<ca:A3>Wollongong</ca:A3>
<ca:A4>Gwynneville</ca:A4>
<ca:STS>Northfield Avenue</ca:STS>
<ca:LMK>University of Wollongong</ca:LMK>
<ca:FLR>2</ca:FLR>
<ca:NAM>Andrew Corporation</ca:NAM>
<ca:PC>2500</ca:PC>
<ca:BLD>39</ca:BLD>
<ca:SEAT>WS-183</ca:SEAT>
<ca:POBOX>U40</ca:POBOX>
</ca:civicAddress>
</location-info>
<usage-rules/>
</geopriv>
</status>
<timestamp>2006-01-10T03:42:28+00:00</timestamp>
</tuple>
</presence>
</locationRequest>
Sends a civic address to the server.
George & Sun Expires January 14, 2010 [Page 9]
Internet-Draft Location translation protocol July 2009
HTTP/1.1 200 OK
Server: Example LIS
Date: Tue, 10 Jan 2006 03:42:29 GMT
Expires: Tue, 10 Jan 2006 03:42:29 GMT
Cache-control: private
Content-Type: application/held+xml
Content-Length: 619
<locationResponse xmlns="urn:ietf:params:xml:ns:geopriv:held">
<presence xmlns="urn:ietf:params:xml:ns:pidf"
entity="pres:3650n87934c@ls.example.com">
<tuple id="b650sf789nd">
<status>
<geopriv xmlns="urn:ietf:params:xml:ns:pidf:geopriv10">
<location-info>
<Point xmlns="http://www.opengis.net/gml"
srsName="urn:ogc:def:crs:EPSG::4326">
<pos>-34.407 150.88001</pos>
</Point>
</location-info>
<usage-rules/>
</geopriv>
</status>
<timestamp>2006-01-10T03:42:28+00:00</timestamp>
</tuple>
</presence>
</locationResponse>
Hence, the corresponding response from the server.
Result for a civic address request contains each individual response.
More than one result may be returned if the given address is
ambiguous. Possible values, from most specific to most general are:
address, street, zip, city, state, country etc. <warning>: If the
exact address was not found, the closest available match will be
noted here.
4. The Accuracy
Location translation service returns an Accuracy value within each
returned address. This value indicates the resolution of the given
result, but not necessarily the correctness of the result. For
example, a civic address of "111 8th Avenue, New York, NY" may return
8 (Address) level accuracy, indicating that the given address is on
the order of resolution of a street address. A civic address for
George & Sun Expires January 14, 2010 [Page 10]
Internet-Draft Location translation protocol July 2009
"France" would only return 1 (Country) level accuracy.
The following table lists the accuracy values returned by the Geo-
Civic address translation service. Note that these accuracy values
only indicate the expected resolution.
Value Description
0 Unknown accuracy.
1 Country level accuracy.
2 Region (state, province, prefecture, etc.) level accuracy.
3 Sub-region (county, municipality, etc.) level accuracy.
4 Town (city, village) level accuracy.
5 Post code (zip code) level accuracy.
6 Street level accuracy.
7 Intersection level accuracy.
8 Address level accuracy.
9 Premise (building name, property name, shopping center, etc.) level
accuracy.
Consider an example for <locationResponse> with accuracy information.
George & Sun Expires January 14, 2010 [Page 11]
Internet-Draft Location translation protocol July 2009
HTTP/1.1 200 OK
Server: Example LIS
Date: Tue, 10 Jan 2006 03:42:29 GMT
Expires: Tue, 10 Jan 2006 03:42:29 GMT
Cache-control: private
Content-Type: application/held+xml
Content-Length: 957
<locationResponse xmlns="urn:ietf:params:xml:ns:geopriv:held">
<presence xmlns="urn:ietf:params:xml:ns:pidf"
entity="pres:3650n87934c@ls.example.com">
<tuple id="b650sf789nd">
<status>
<geopriv xmlns="urn:ietf:params:xml:ns:pidf:geopriv10">
<location-info accuracy = "9">
<ca:civicAddress
xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
xml:lang="en-au">
<ca:country>AU</ca:country>
<ca:A1>NSW</ca:A1>
<ca:A3>Wollongong</ca:A3>
<ca:A4>Gwynneville</ca:A4>
<ca:STS>Northfield Avenue</ca:STS>
<ca:LMK>University of Wollongong</ca:LMK>
<ca:FLR>2</ca:FLR>
<ca:NAM>Andrew Corporation</ca:NAM>
<ca:PC>2500</ca:PC>
<ca:BLD>39</ca:BLD>
<ca:SEAT>WS-183</ca:SEAT>
<ca:POBOX>U40</ca:POBOX>
</ca:civicAddress>
</location-info>
<usage-rules/>
</geopriv>
</status>
<timestamp>2006-01-10T03:42:28+00:00</timestamp>
</tuple>
</presence>
</locationResponse>
5. The Error Codes
There may occur few errors during the request processing. For
example the parameters passed to the server did not match as
George & Sun Expires January 14, 2010 [Page 12]
Internet-Draft Location translation protocol July 2009
expected. This document should re-use the HELD error codes. In
particular, the server should always return a 200/OK, possibly with a
HELD <error> element. In addition to HELD errors codes, following is
a list of error codes that you may encounter.
accessDenied: You do not have permission to access this resource.
internaleError: An internal problem prevents from returning data.
notDefined: The address translation process failed due to an error
not covered by the definition of any other error code in this
interface.
For each error, you'll receive an XML response of the following form.
HTTP/1.1 200 OK
Server: Example LIS
Expires: Tue, 10 Jan 2006 03:49:20 GMT
Cache-control: private
Content-Type: application/held+xml
Content-Length: 182
<?xml version="1.0"?>
<error xmlns="urn:ietf:params:xml:ns:geopriv:held"
code="locationUnknown">
<message xml:lang="en">Unable to determine location
</message>
</error>
6. Security Considerations
TBD
7. IANA Considerations
TBD
George & Sun Expires January 14, 2010 [Page 13]
Internet-Draft Location translation protocol July 2009
8. References
8.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
8.2. Informative References
[I-D.ietf-geopriv-civic-address-recommendations]
Wolf, K. and A. Mayrhofer, "Considerations for Civic
Addresses in PIDF-LO - Guidelines and IANA Registry
Definition",
draft-ietf-geopriv-civic-address-recommendations-03 (work
in progress), July 2009.
[I-D.ietf-geopriv-http-location-delivery]
Barnes, M., Winterbottom, J., Thomson, M., and B. Stark,
"HTTP Enabled Location Delivery (HELD)",
draft-ietf-geopriv-http-location-delivery-15 (work in
progress), June 2009.
[RFC3693] Cuellar, J., Morris, J., Mulligan, D., Peterson, J., and
J. Polk, "Geopriv Requirements", RFC 3693, February 2004.
[RFC4119] Peterson, J., "A Presence-based GEOPRIV Location Object
Format", RFC 4119, December 2005.
[RFC4776] Schulzrinne, H., "Dynamic Host Configuration Protocol
(DHCPv4 and DHCPv6) Option for Civic Addresses
Configuration Information", RFC 4776, November 2006.
[RFC5139] Thomson, M. and J. Winterbottom, "Revised Civic Location
Format for Presence Information Data Format Location
Object (PIDF-LO)", RFC 5139, February 2008.
Authors' Addresses
Robins George
Huawei Technologies
Huawei Base, Bantian, Longgang District
Shenzhen, Guangdong 518129
P. R. China
Phone: +86-755-28788314
Email: robinsg@huawei.com
George & Sun Expires January 14, 2010 [Page 14]
Internet-Draft Location translation protocol July 2009
Qian Sun
Huawei Technologies
Huawei Base, Bantian, Longgang District
Shenzhen, Guangdong 518129
P. R. China
Phone: +86-755-28787351
Email: sunqian@huawei.com
George & Sun Expires January 14, 2010 [Page 15]