GEOPRIV R. George
Internet-Draft Q. Sun
Intended status: Standards Track Huawei Technologies
Expires: January 7, 2010 July 6, 2009
Geodetic-Civic Address Translation Protocol
draft-george-geopriv-address-translation-00
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 7, 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 7, 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. Geodetic-Civic . . . . . . . . . . . . . . . . . . . . . . 3
3.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Civic to Geodetic . . . . . . . . . . . . . . . . . . . . 6
3.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 6
4. The Accuracy . . . . . . . . . . . . . . . . . . . . . . . . . 8
5. The Error Codes . . . . . . . . . . . . . . . . . . . . . . . 10
6. Security Considerations . . . . . . . . . . . . . . . . . . . 11
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
8.1. Normative References . . . . . . . . . . . . . . . . . . . 12
8.2. Informative References . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12
George & Sun Expires January 7, 2010 [Page 2]
Internet-Draft Location translation protocol July 2009
1. Introduction
As the growth of location-based services, access to real-time
geolocation information becomes more important. This draft describes
how to convert civic addresses to geospatial addresses and vice
versa. For example, I'm in Washington, DC, instead of (40.8N,
73.9W). This form of location is a lot more realistic in a lot of
situations, since it can be often hard to get a precise position.
However, it's good enough for some location-based services.
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 may return the 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. Geodetic-Civic
This method performs the conversion of a latitude/longitude pair into
human-readable addresses. User sends a request to the location
translation service, asking to return the civic address for the given
geodetic address. If the address was successfully located, it sent
back to the user. In case of ambiguous addresses, only the point for
the best match is passed in the response.
George & Sun Expires January 7, 2010 [Page 3]
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 7, 2010 [Page 4]
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 which are defined in
[RFC5139]. It is recommended to follow a particular civic address
George & Sun Expires January 7, 2010 [Page 5]
Internet-Draft Location translation protocol July 2009
schema, if there is any civic address recommendation for a particular
country or region. For example,
draft-ietf-geopriv-civic-address-recommendations-02.
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. Civic to Geodetic
Civic to Geodetic is the process of converting civic addresses (like
"1600 Amphitheatre Parkway, Mountain View, CA") into geographic
coordinates (like latitude 37.423021 and longitude -122.083739).
This method performs a conversion of a human-readable address into a
latitude/longitude pair. The user sends a request to the server,
asking it to parse the given 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.
If the geodetic address of a location is requested, the response will
contain altitude, latitude and longitude of the location, in which
altitude is an optional. The following parameters may be included
while requesting for a geodetic address.
Street name, city name, zip code. If this location contradicts the
city and state specified, the zip code will be used for determining
the location and the city, state and other parameters will be
ignored. If a location like Washington DC is specified, it will take
priority over the individual fields in determining the location for
the query. City, state and zip will be ignored.
George & Sun Expires January 7, 2010 [Page 6]
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 7, 2010 [Page 7]
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 7, 2010 [Page 8]
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 7, 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: 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 7, 2010 [Page 10]
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 7, 2010 [Page 11]
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-02 (work
in progress), February 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-14 (work in
progress), May 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 7, 2010 [Page 12]
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 7, 2010 [Page 13]