Copyright © 2013 Claudius Teodorescu, published by the EXPath Community Group under the W3C Community Contributor License Agreement (CLA) . A human-readable summary is available.
This specification was published by the EXPath Community Group . It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups .
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.
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
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.
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.
These functions provide location data based upon user agent's IP address (whether is version 4 or version 6 type IP).
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.
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 asxs:string
) asxs:string
$ip-address
is the user agent's IP address. If the IP address is not valid, this is an error
[err:LOC01].
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 asxs:string
) asxs: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].
loc:get-country-name()
function
This function returns the country name.
time:get-country-name
($country-2-code asxs:string
) asxs:string
time:get-country-name
($country-2-code asxs:string
, $language-tag asxs:string
) asxs: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].
loc:get-country-flag()
function
This function returns the country flag, in various formats.
time:get-country-flag
($country-2-code asxs:string
, $format asxs:string
, $provider asxs:anyURI?
) asxs: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].
loc:get-city-name()
function
This function returns the city name.
time:get-city-name
($ip-address asxs:string
) asxs:string
time:get-city-name
($ip-address asxs:string
, $provider asxs:anyURI
) asxs: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].
loc:get-latitude()
function
This function returns the latitude of the geographic point corresponding to the IP address.
time:get-latitude
($ip-address asxs:string
, $format asxs:string?
) asxs:string
time:get-latitude
($ip-address asxs:string
, $format asxs:string?
, $provider asxs:anyURI
) asxs: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].
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 asxs:string
, $format asxs:string?
) asxs:string
time:get-longitude
($ip-address asxs:string
, $format asxs:string?
, $provider asxs:anyURI
) asxs: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].
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 asxs:string
) asxs:boolean
$latitude
is the latitude to be validated.
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 asxs:string
) asxs:boolean
$longitude
is the longitude to be validated.
loc:get-time-zone()
function
This function returns the time zone.
time:get-time-zone
($ip-address asxs:string
) asxs:string
time:get-time-zone
($ip-address asxs:string
, $provider asxs:anyURI
) asxs: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].
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 asxs:string
, $second-ip-address asxs:string
) asxs:string
time:get-distance
($first-ip-address asxs:string
, $second-ip-address asxs:string
, $provider asxs:anyURI
) asxs: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].
The formats are according to ISO 6709.
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.
The formats are according to ISO 6709.
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.