SIGN IN

New users get a free 3 month trial of all services.

General: Location ID

Location Ids may be specified in several different formats:

  • Numeric id. This is a unique and stable identifier assigned to a location. Numeric identifiers do not change.

  • Textual id in the form country/city. Please note that although those ids can be guessed easily, it should be confirmed that they actually specify the city you want to query – e.g. usa/augusta does not refer to the city Augusta, GA, but to Augusta, ME (the id for Augusta, GA is usa/augusta-ga).

  • Geographic coordinates.

  • IATA/ICAO codes for airports.

The places service can be used to retrieve the currently existing places (numeric and textual ids). A list of known places also be viewed here. IATA/ICAO codes are not included in these listings.

Geographic coordinates

It is possible to specify coordinates instead of an id. The service will then try to determine the nearest known location within the same time zone and country. By using the radius parameter, the search radius can be limited. Coordinates within the territorial waters of a country will be treated as belonging to this country. Coordinates that cannot be resolved to a country will be resolved to their corresponding nautical time zone. Coordinates that have not been resolved to a location (because they have been resolved to a nautical time zone, or no location was found within the search radius) are not valid for all services.

Please note that specifying coordinates is not supported in all license packages – this feature is only possible with license packages which allow querying of all available locations.

Two different ways can be used to specify coordinates:

  • Coordinates in decimal format. Directly concatenate the coordinates including the leading sign, first the latitude, then the longitude. Negative latitudes indicate southern hemisphere, whereas positive values for the latitude indicate northern hemisphere. For longitude, negative values indicate the western hemisphere and positive values the eastern hemisphere.

    Example: +58.96+5.67

  • Coordinates in degree/minutes/seconds format. Specify latitude followed by an uppercase N or S character. Directly after this value specify the longitude followed by an uppercase E or W character to indicate which hemisphere it belongs to. Degree, minute, second and fraction values shall be separated with a . (dot) character. Only degrees are mandatory, the other values can be omitted.

    Example: 58.58.12N5.45E

All coordinates shall be expressed in the WGS 84 coordinate system (typically used by e.g. GPS devices).

IATA/ICAO codes for airports

This way of specifying a location is only supported for the astronomy, the converttime and the timeservice services. The respective code shall be prefixed with the string a-. The service will then respond with information corresponding to the indicated airport or with an error if no matching airport could be located.

EBNF specification of accepted location ids

[1]LocationId= LocationIdNumeric | LocationIdTextual | LocationIdGeographicDecimal | LocationIdGeographicDMS | LocationIdAirport;
[2]LocationIdNumeric=Number;
[3]LocationIdTextual= AlphanumericId, { "/", AlphanumericId };
[4]LocationIdGeographicDecimal= sign, Float, sign, Float;
[5]LocationIdGeographicDMS= Degree, NorthSouth, Degree, EastWest;
[6]LocationIdAirport= "a-", letter, letter, letter, [ letter ];
[7]AlphanumericId= letter, { idchar };
[8]Degree= number, [ ".", number, [ ".", Float ] ];
[9]Float= number, [ ".", number ];
[10]Number= digit, { digit };
[11]EastWest="E" | "W";
[12]NorthSouth ="N" | "S";
[13]idchar= letter | digit | "-";
[14]digit= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
[15]letter="a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
[16]sign="+" | "-";