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 3.1.1. Example POST /location HTTP/1.1 Host: lis.example.com:49152 Content-Type: application/held+xml Content-Length: 1043 civic -34.407 150.88001 2006-01-10T03:42:28+00:00 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 AU NSW Wollongong Gwynneville Northfield Avenue University of Wollongong 2 Andrew Corporation 2500 39 WS-183 U40 2006-01-10T03:42:28+00:00 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. 3.2.1. Example 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 geodetic AU NSW Wollongong Gwynneville Northfield Avenue University of Wollongong 2 Andrew Corporation 2500 39 WS-183 U40 2006-01-10T03:42:28+00:00 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 -34.407 150.88001 2006-01-10T03:42:28+00:00 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. : 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 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 AU NSW Wollongong Gwynneville Northfield Avenue University of Wollongong 2 Andrew Corporation 2500 39 WS-183 U40 2006-01-10T03:42:28+00:00 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 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 Unable to determine location 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]