EXPath

Location Module 1.0

EXPath Candidate Module 12 March 2013

Latest version:
http://expath.org/spec/location
Editor:
Claudius Teodorescu, XML Consultant

Abstract

This proposal defines a module for providing functions dealing with location. It has been designed to be compatible with XQuery 3.0 and XSLT 3.0, as well as any other standard based on XPath 3.0.

Table of Contents

1 Introduction
1.1 Namespace conventions
1.2 Error management
2 IP localization
2.1 Location data providers
2.2 The loc:get-country-alpha-2-code() function
2.3 The loc:get-country-alpha-3-code() function
2.4 The loc:get-country-name() function
2.5 The loc:get-country-flag() function
2.6 The loc:get-city-name() function
2.7 The loc:get-latitude() function
2.8 The loc:get-longitude() function
2.9 The loc:validate-latitude() function
2.10 The loc:validate-longitude() function
2.11 The loc:get-time-zone() function
2.12 The loc:get-distance() function
2.13 The latitude, longitude, and altitude formats
2.13.1 The latitude and longitude formats
2.13.2 The altitude formats

Appendices

A References
B Summary of Error Conditions


1 Introduction

This module contains functions for dealing with location. It has been designed to be compatible with XQuery 3.0 and XSLT 3.0, as well as any other standard based on XPath 3.0.

1.1 Namespace conventions

The module defined by this document defines functions and elements in the namespace http://expath.org/ns/location. In this document, the loc prefix, when used, is bound to this namespace URI.

Error codes are defined in the namespace http://expath.org/ns/error. In this document, the err prefix, when used, is bound to this namespace URI.

1.2 Error management

Error conditions are identified by a code (a QName). When such an error condition is reached during the execution of the function, a dynamic error is thrown, with the corresponding error code (as if the standard XPath function error had been called).

2 IP localization

These functions provide location data based upon user agent's IP address (whether is version 4 or version 6 type IP).

2.1 Location data providers

The location data is made available by various providers, either as databases, or as webservices. The user should be able to choose the preferred provider among the ones accessible within the implementation.

Each implementation has to have a default provider, for the easy use of functions.

2.2 The loc:get-country-alpha-2-code() function

This function returns the country code composed of 2 digits, according to ISO 3166-1 Alpha-2.

time:get-country-alpha-2-code($ip-address as xs:string) as xs:string
  • $ip-address is the user agent's IP address. If the IP address is not valid, this is an error [err:LOC01].

2.3 The loc:get-country-alpha-3-code() function

This function returns the country code composed of 3 digits, according to ISO 3166-1 Alpha-3.

time:get-country-alpha-3-code($country-2-code as xs:string) as xs:string
  • $country-alpha-2-code is the country code composed of 2 digits, according to ISO 3166-1 Alpha-2. If the country code is not valid, this is an error [err:LOC04].

2.4 The loc:get-country-name() function

This function returns the country name.

time:get-country-name($country-2-code as xs:string) as xs:string
time:get-country-name($country-2-code as xs:string, $language-tag as xs:string) as xs:string
  • $country-alpha-2-code is the country code composed of 2 digits, according to ISO 3166-1 Alpha-2. If the country code is not valid, this is an error [err:LOC04].

  • $language-tag is the language tag used to designate the language of the country name, according to [RFC 5646]. The format for the language tags is . If the language tag is not valid, this is an error [err:LOC07].

2.5 The loc:get-country-flag() function

This function returns the country flag, in various formats.

time:get-country-flag($country-2-code as xs:string, $format as xs:string,
	$provider as xs:anyURI?) as xs:string
  • $country-alpha-2-code is the country code composed of 2 digits, according to ISO 3166-1 Alpha-2. If the country code is not valid, this is an error [err:LOC04].

  • $format is the flag's format. If the format is not valid, this is an error [err:LOC03].

  • $provider is the provider for the current operation. If the provider is not specified, the implementation will use the default provider. If the provider does not exist, this is an error [err:LOC02].

2.6 The loc:get-city-name() function

This function returns the city name.

time:get-city-name($ip-address as xs:string) as xs:string
time:get-city-name($ip-address as xs:string, $provider as xs:anyURI) as xs:string
  • $ip-address is the user agent's IP address. If the IP address is not valid, this is an error [err:LOC01].

  • $provider is the provider for the current operation. If the provider is not specified, the implementation will use the default provider. If the provider does not exist, this is an error [err:LOC02].

2.7 The loc:get-latitude() function

This function returns the latitude of the geographic point corresponding to the IP address.

time:get-latitude($ip-address as xs:string, $format as xs:string?) as xs:string
time:get-latitude($ip-address as xs:string, $format as xs:string?,
	$provider as xs:anyURI) as xs:string
  • $ip-address is the user agent's IP address. If the IP address is not valid, this is an error [err:LOC01].

  • $format is the format of the latitude. For latitude formats, see 2.13 The latitude, longitude, and altitude formats. If the format is not valid, this is an error [err:LOC05].

  • $provider is the provider for the current operation. If the provider is not specified, the implementation will use the default provider. If the provider does not exist, this is an error [err:LOC02].

2.8 The loc:get-longitude() function

This function returns the longitude of the geographic point corresponding to the IP address. For longitude formats, see 2.13 The latitude, longitude, and altitude formats.

time:get-longitude($ip-address as xs:string, $format as xs:string?) as xs:string
time:get-longitude($ip-address as xs:string, $format as xs:string?,
	$provider as xs:anyURI) as xs:string
  • $ip-address is the user agent's IP address. If the IP address is not valid, this is an error [err:LOC01].

  • $format is the format of the longitude. For longitude formats, see 2.13 The latitude, longitude, and altitude formats. If the format is not valid, this is an error [err:LOC06].

  • $provider is the provider for the current operation. If the provider is not specified, the implementation will use the default provider. If the provider does not exist, this is an error [err:LOC02].

2.9 The loc:validate-latitude() function

This function validates a latitude. It returns true if the latitude is valid, false if not. For latitude formats, see 2.13 The latitude, longitude, and altitude formats.

time:validate-latitude($latitude as xs:string) as xs:boolean
  • $latitude is the latitude to be validated.

2.10 The loc:validate-longitude() function

This function validates a longitude. It returns true if the longitude is valid, false if not. For longitude formats, see 2.13 The latitude, longitude, and altitude formats.

time:validate-longitude($longitude as xs:string) as xs:boolean
  • $longitude is the longitude to be validated.

2.11 The loc:get-time-zone() function

This function returns the time zone.

time:get-time-zone($ip-address as xs:string) as xs:string
time:get-time-zone($ip-address as xs:string, $provider as xs:anyURI) as xs:string
  • $ip-address is the user agent's IP address. If the IP address is not valid, this is an error [err:LOC01].

  • $provider is the provider for the current operation. If the provider is not specified, the implementation will use the default provider. If the provider does not exist, this is an error [err:LOC02].

2.12 The loc:get-distance() function

This function returns the distance (in kilometers) between two points, based on their IP addresses.

time:get-distance($first-ip-address as xs:string, $second-ip-address as xs:string) as xs:string
time:get-distance($first-ip-address as xs:string, $second-ip-address as xs:string,
				$provider as xs:anyURI) as xs:string
  • $first-ip-address is the first user agent's IP address. If the IP address is not valid, this is an error [err:LOC01].

  • $second-ip-address is the second user agent's IP address. If the IP address is not valid, this is an error [err:LOC01].

  • $provider is the provider for the current operation. If the provider is not specified, the implementation will use the default provider. If the provider does not exist, this is an error [err:LOC02].

2.13 The latitude, longitude, and altitude formats

2.13.1 The latitude and longitude formats

The formats are according to ISO 6709.

Formats for latitude and longitude
Format description Format for latitude Format for longitude
Latitude and longitude in degrees ±DD.DDDD ±DDD.DDDD
Latitude and longitude in degrees and minutes ±DDMM.MMMM ±DDDMM.MMMM
Latitude and longitude in degrees, minutes and seconds ±DDMMSS.SSSS ±DDDMMSS.SSSS

Explanations:

  • ±DD = three-digit integer degrees part of latitude (through -90 ~ -00 ~ +90);

  • ±DDD = four-digit integer degrees part of longitude (through -180 ~ -000 ~ +180);

  • MM = two-digit integer minutes part (00 through 59);

  • SS = two-digit integer seconds part (00 through 59);

  • .DDDD = variable-length fraction part in degrees;

  • .MMMM = variable-length fraction part in minutes;

  • .SSSS = variable-length fraction part in seconds;

  • The sign is always necessary for each value: latitude: North = "+", South = "-"; longitude: East = "+", West = "-";

  • The integer part is a fixed length, respectively, and padding character is "0";

  • It is variable-length below the decimal point.

2.13.2 The altitude formats

The formats are according to ISO 6709.

Formats for altitude
Format description Format for altitude
Altitude in meters and fractions of meter ±AAA.AAA

Explanations:

  • The measuring unit for altitude is meter [m];

  • The integer part and the fraction part of altitude are both variable-length.

A References

XPath 3.0
XML Path Language (XPath) 3.0. Jonathan Robie, Don Chamberlin, Michael Dyck, John Snelson, editors. W3C Working Draft, 13 December 2011.
XSLT 3.0
XSL Transformations (XSLT) Version 3.0. Michael Kay, editor. W3C Working Draft, 10 July 2012.
XQuery 3.0
XQuery 3.0: An XML Query Language. Jonathan Robie, Don Chamberlin, Michael Dyck, John Snelson, editors. W3C Working Draft, 13 December 2011.
XPath and XQuery Functions and Operators 3.0
XPath and XQuery Functions and Operators 3.0. Michael Kay, editor. W3C Working Draft, 13 December 2011.
XQuery and XPath Data Model 3.0
XQuery and XPath Data Model 3.0. Norman Walsh, Anders Berglund, John Snelson, editors. W3C Working Draft, 13 December 2011.
Latitude, Longitude, and Altitude
Latitude, Longitude and Altitude format for geospatial information.
RFC 5646
Tags for Identifying Languages. A. Phillips, M. Davis, editors. Network Working Group. September 2009.

B Summary of Error Conditions

err:LOC01
The IP address is not valid.
err:LOC02
The provider is not set.
err:LOC03
The flag format is not valid.
err:LOC04
The country ISO alpha 2 code is not valid.
err:LOC05
The latitude format is not valid.
err:LOC06
The longitude format is not valid.
err:LOC07
The language tag is not valid.