Location Module 1.0

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.

Location Module 1.0

EXPath Candidate Module 12 March 2013

Abstract

Table of Contents

Appendices

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

A References

B Summary of Error Conditions

Location Module 1.0

EXPath Candidate Module 12 March 2013

Abstract

Table of Contents

Appendices

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

A References

B Summary of Error Conditions

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