API Version 1
2016-11-11
This is the latest stable version.
General description
This is a REST API, served over HTTPS.
Unless stated otherwise, the only supported method for all requests is HTTP GET.
The API is served exclusively over HTTPS.
API versioning
The API URLs include the version number. Multiple versions of the API may be supported concurrently. Read our API contract for more information.
Base URL
Host
The hostname depends on the installation and DNS configuration (e.g., the service could be accessed via CNAME
records). In the general case, you may expect the service to be available under wxt.navlost.eu
as the canonical hostname, and this is what we will use throughout the documentation.
URL prefix
All requests will be served from /api/v1/
.
Note:
v1
is the prefix for version 1 of the API.
Authentication
Two types of authentication are supported:
- Basic authentication over HTTPS.
- Token-based authentication over HTTPS.
Basic authentication
This is the default authentication method, and is required for certain administrative operations such as generating tokens or changing a user’s password.
Password change
Your account’s password may be changed via the following endpoint:
POST https://user:passwd@wxt.navlost.eu/api/v1/auth/user/{user}/password
Content-Type: application/json
{ |
Parameters:
{user}
(in the URL): The username.hash
: An hex-encoded, unsalted, hash of the new password, using the specified algorithm.algorithm
: A text string, one of"sha512"
(recommended),"sha384"
, or"sha256"
.
Alternatively, instead of a JSON object, you can also supply the new password in plain text as a string literal in the POST body:
Content-Type: application/json
"newpassword" |
Note that the content type still has to be application/json
, and note the double quotes surrounding the password, needed to make it a valid JSON string literal.
Token-based authentication
This type of authentication allows a user to delegate his authority to access the service to another party, for a limited time, without having to reveal his credentials.
Usage
The user generates a token by using the appropriate API call, then somehow transmits that token to the third party. The third party presents the token to the service in an HTTP header named AUTH-TOKEN, the value of which is the verbatim token.
If the token is valid, not expired, and sufficient for the endpoint being accessed, the client will be granted access under the generating user’s credentials.
If the token does not comply with all of the above conditions, access will be denied with an HTTP 401 error code.
Create
POST https://user:passwd@wxt.navlost.eu/api/v1/auth/token/new
Content-Type: application/json
{ |
Parameters:
expires
: An ISO-8601 timestamp or a time to live in seconds. The token will cease to be valid after that time. Defaults to one hour after creation.ip_address
: Restrict the token to the given client IP address—both IPv4 and IPv6 are accepted. Defaults to accepting the token from any address.
Both request parameters are optional. The request body may be omitted althogether if defaults are used.
On success, it returns HTTP 201 (Created)
Example requests:
{ |
{ |
Example response:
{ |
Delete
DELETE https://user:passwd@wxt.navlost.eu/api/v1/auth/token/{token}
This command immediately expires a token.
It responds always with HTTP 202 (Accepted), regardless of whether or not {token}
exists or has ever existed. Tokens may only be deleted by the user who has created them.
Retrieve
GET https://user:passwd@wxt.navlost.eu/api/v1/auth/token/
Returns the list of currently active tokens for the user.
Example response:
{ |
Use
Tokens may be used with any non-administrative request. That is to say, those which retrieve non-user-specific data, such as forecast weather.
To use a token, include it in the request as a header named AUTH-TOKEN
, as in the following example—we use curl
for illustration purposes:
curl -H "AUTH-TOKEN: 713399736b4ebf886680bc4dfe1cff32f536475e4fa1567480b3b19d030be8776e5244c98d7e092f67773cda8574344c11ebe1373c9fa096904c506b208a3557" \ |
If a token ceases to be valid, e.g., because it has expired or been removed, the server will respond with HTTP 401 (Unauthorized), in which case the user should obtain another token and retry the request.
Data requests: Summary
GET https://user:passwd@wxt.navlost.eu/api/v1/f/
GET https://user:passwd@wxt.navlost.eu/api/v1/f/{elements}
Forecast values: at current time:
GET https://user:passwd@wxt.navlost.eu/api/v1/f/{elements}/{locations}
Forecast values: at a specific time:
GET https://user:passwd@wxt.navlost.eu/api/v1/f/{elements}/{locations}/{epochs}
Forecast values: other than ground level:
GET https://user:passwd@wxt.navlost.eu/api/v1/f/{elements}/{locations}/{epochs}/{levels}
GET https://user:passwd@wxt.navlost.eu/api/v1/r/{reports}/{icaoOrLoc}?count={count}&output={output}
Data requests: Generalities
Request method
In general, data requests are GET-based endpoints where all the request parameters are specified in the URL. In many cases multiple values may be specified for a given parameter (such as element types, locations, times, etc.) by separating the different values with a semicolon, as will be shown latter in the examples.
Response type
The default response type is application/json
, although other formats may be supported. At the present time, there is partial support for comma-separated value (CSV) responses.
The response JSON object for this version of the API aims for brevity and usually follows a hierarchical pattern to group multiple values according to location, date, etc.
Value lists
Please note that, as a general rule, lists of values are not sorted on the server. It is expected that any sorting that may be needed will be done client-side.
Vertical levels specification
To specify the vertical level that a data request refers to, when applicable, the following conventions are used:
Aeronautical format
Level | Examples |
---|---|
Feet above mean sea level | A5000 |
Metres above mean sea level | M1500 |
Flight level (feet) | F100 |
Flight level (metric) | S30 |
Distance above mean sea level
Level | Examples |
---|---|
Metres above MSL | 1000 m |
Feet above MSL | 3000 ft |
Negative values are also accepted, although at present they would not return any data.
Common geographic datums
Level | Specification |
---|---|
Ground | GND , or SFC |
Mean sea level | MSL |
Datums of meteorological interest
Level | Specification (short) | Specification (long) |
---|---|---|
Freezing level | frzl |
0c-isotherm |
Tropopause | tpp |
tropopause |
Maximum wind level | mwl |
max-wind |
Highest tropospheric freezing level | htfl |
highest-tropospheric-freezing-level |
Clouds
Level | Specification (short) | Specification (long) |
---|---|---|
Boundary layer cloud bottom | bcb |
boundary-cloud-bottom |
Boundary layer cloud top | bct |
boundary-cloud-top |
Low cloud bottom | lcb |
low-cloud-bottom |
Low cloud top | lct |
low-cloud-top |
Mid cloud bottom | mcb |
middle-cloud-bottom |
Mid cloud top | mct |
middle-cloud-top |
High cloud bottom | hcb |
high-cloud-bottom |
High cloud top | hct |
high-cloud-top |
Convective cloud bottom | ccb |
convective-cloud-bottom |
Convective cloud top | cct |
convective-cloud-top |
Data requests: Detail
For brevity, the authentication part of the URLs (
user:passwd@
) will be omitted in the following examples, but either basic authentication or a token need to be used for every request.
List of forecast items
This is data coming from a numerical forecast model, either directly or derived from it.
GET https://wxt.navlost.eu/api/v1/f/
Retrieves a list of available forecast elements, such as wind, temperature, etc.
Response
Content-Type: application/json
An array of objects, each representing an available forecast element. Each object exposes three properties:
name
: Name of the element, used elsewhere in the API.description
: A brief textual description of the element’s contents.unit
: Units of measure, if the element is a scalar.
[ |
Forecast item data
GET https://wxt.navlost.eu/api/v1/f/{elements}
Where {elements}
is one or more element names, separated by a semicolon.
Examples
GET https://wxt.navlost.eu/api/v1/f/RH
Get RH
(relative humidity) element information.
GET https://wxt.navlost.eu/api/v1/f/RH;UGRD;VGRD
Get information for the RH
, UGRD
, and VGRD
elements.
Response
Content-Type: application/json
An array of objects, one for each recognised element containing, in addition to the properties previously described, a list of epochs available (as ISO-8601 formatted strings), and a list of available vertical levels, typically isobaric levels in hectoPascals or a specific surface, such as ground level or mean sea level.
Note that only the minimum and maximum values for epochs and isobaric levels are significant, as interpolation will occur between the closest two epochs/levels if the exact values are not directly available. Do note also that minima and maxima are not necessarily the first and last elements in a list, as can be seen in the following example response.
[ |
Forecast values: at current time
GET https://wxt.navlost.eu/api/v1/f/{elements}/{locations}
or
GET https://wxt.navlost.eu/api/v1/f/{elements}/{locations}/@
Where {locations}
is one or more geographical locations expressed as latitude, longitude in decimal degrees on the EPSG:4326 datum. Multiple locations are separated by a semicolon.
Examples
GET https://wxt.navlost.eu/api/v1/f/TMP/-1.28325,36.81724;-1.03664,37.07752
Get the current TMP
(temperature) value in Nairobi and Thika, Kenya, at ground level.
GET https://wxt.navlost.eu/api/v1/f/TMP;UGRD;VGRD/-1.28325,36.81724;-1.03664,37.07752
As above, but also get surface wind data.
Response
Content-Type: application/json
An object having the following structure:
Root |
Where:
Root
stands for the parent object.latitude,longitude
is a text literal consisting of the location’s latitude fixed to six decimal places, followed by a comma, followed by the location’s longitude also to six decimal places.epoch
is the current UTC time in ISO-8601 format."GND"
is a literal.element
is the name of the requested element.value
is the value corresponding to the above parameters (location, epoch, and element, at ground level). The units for this value, where applicable, may be obtained from the List of forecast items endpoint. In the event of a missing value, where otherwise the request is within the spatial and temporal bounds of the dataset,null
will be returned.error
is an object. It will have at least an"error"
attribute containing a human-readable description of the error condition, in English.
Example response:
{ |
Forecast values: at a specific time
GET https://wxt.navlost.eu/api/v1/f/{elements}/{locations}/{epochs}
Where {epochs}
is one or more UTC epochs, either in a valid ISO-8601 format or as a Unix timestamp, or as an epoch relative to current time (see below). Examples: 2016-05-24T08:00:00Z
, 2016-05-24T08Z
, 1464076800
. Multiple epochs are separated by a semicolon.
Relative Epochs
Epochs can also be expressed relative to present time. This has the advantage that request URLs may be hard-coded in some cases.
These relative epochs start with the @
sign, which is optionally followed by an offset part and a modulo part, both expressed in integer seconds, which for the offset may be a negative number. Thus, the full format is @[offset][%modulo]
.
Offset
The offset is an integer number of seconds, it can be positive, negative, or zero. If present, it is written immediately following the @
sign. If absent, zero is assumed.
Modulo
The modulo is an integer number of seconds. If present, it must be strictly positive. It is written after the offset part, if any, otherwise immediately after the @
sign. It is always preceded by either a %
sign or the literal expression mod
. The latter has the advantage that it does not need to be URL-encoded. Examples below use both expressions.
The resulting epoch is then calculated as: (t + offset) mod modulo
This allows the user to represent a variety of relative points in time, such as:
Relative epoch | Notation(s) |
---|---|
Now | @ |
One hour from now | @3600 , @+3600 |
One and a half hours ago | @-5400 |
Current time, truncated to seconds | @%1 , @mod1 |
Current time, truncated to minutes | @%60 , @mod60 |
Current hour | @%3600 , @mod3600 |
Current time, truncated to nearest even hour | @%7200 , @mod7200 |
Today | @%86400 , @mod86400 |
Tomorrow | @86400%86400 , @86400mod86400 |
Yesterday | @-86400%86400 , @-86400mod86400 |
One week and six hours from now, truncated to nearest hour which is divisible by three | @626400%10800 , @626400mod10800 |
Examples
GET https://wxt.navlost.eu/api/v1/f/TMP/-1.28325,36.81724;-1.03664,37.07752/2016-01-01
GET https://wxt.navlost.eu/api/v1/f/TMP/-1.28325,36.81724;-1.03664,37.07752/2016-01-01T00Z
GET https://wxt.navlost.eu/api/v1/f/TMP/-1.28325,36.81724;-1.03664,37.07752/2016-01-01T00:00:00Z
GET https://wxt.navlost.eu/api/v1/f/TMP/-1.28325,36.81724;-1.03664,37.07752/1451606400
All of the above refer to the same epoch, midnight UTC first of January, 2016.
GET https://wxt.navlost.eu/api/v1/f/TMP/-1.28325,36.81724;-1.03664,37.07752/@%2510800;@10800%2510800;@21600mod10800
Get the weather in three-hourly intervals, the most recent past and the two nearest in the future. Note the URL-escaped percent sign in the first two epochs.
Response
Content-Type: application/json
As in the previous example.
Example response:
{ |
Forecast values: other than ground level.
GET https://wxt.navlost.eu/api/v1/f/{elements}/{locations}/{epochs}/{levels}
Where {levels}
is one or more vertical levels (altitudes), expressed as described earlier in this document, e.g., in aeronautical format (F100
, A5000
), or as a pressure level (hPa700
), or as the expressions SFC
, GND
, frzl
, etc. Some forecast elements may not relate to a particular altitude, and for those the altitude parameter may be omitted. For elements which do require an altitude, if omitted, it will be assumed to be ground level (equivalent to GND
).
Note that you may request the current epoch, alone or in addition to other epochs, by using the
@
shortcut.
Examples
GET https://wxt.navlost.eu/api/v1/f/TMP;UGRD;VGRD/-1.28325,36.81724;-1.03664,37.07752/2016-01-01T00Z;2016-01-01T01Z/GND;hPa500;A3000;M3000
Get the temperature and winds for Nairobi and Thika, at 00Z and 01Z on 2016-01-01, at:
- Ground level (
GND
) - The 500 hectoPascals pressure level (
hPa500
) - 3,000 feet above mean sea level (
A3000
) - 3,000 metres above mean sea level (
M3000
)
GET https://wxt.navlost.eu/api/v1/f/UGRD;VGRD;HGT/-1.28325,36.81724;-1.03664,37.07752/@/mwl
Get the current height of the maximum wind level, and the wind speeds.
Response
Content-Type: application/json
As in the previous cases. The total number of values returned is num_elements × num_locations × num_epochs × num_levels.
{ |
METAR / TAF reports
GET https://wxt.navlost.eu/api/v1/r/{reports}/{icaoOrLoc}?options={options}
Retrieves recent METAR or TAF reports for specific locations.
Where {reports}
is either:
METAR
for METAR reports.TAF
for forecasts.METAR;TAF
orTAF;METAR
for both METAR and TAF reports.
Where {icaoOrLoc}
is one or more valid ICAO identifiers or locations (formatted as latitude,longitude
), with multiple identifiers or locations separated by a semicolon. ICAO identifiers and locations can be mixed freely.
Options
The {options}
parameter controls a number of parameters concerning the search. Its general format is options={option1:value1},{option2:value2}…
. Where the option is a boolean flag, its value may be omitted.
These are the valid options:
count:{count}
: Return up to{count}
reports per station. The default value is 3, and the maximum is 100.radius:{radius}
: When doing a search by geographic location, limit the search radius to{radius}
metres from the given coordinates. Its default is 100,000 metres (100 km), and the maximum is 1,000,000 metres (1,000 km).icaoCount:{icaoCount}
: When doing a search by geographic location, return up to{icaoCount}
stations within the search radius. The default is 1, which returns the closest station to the given location. The maximum is 10.
For the above parameters, values above their maxima are truncated, and negative values are treated as if they were positive.
The following may also be specified:
location
: If specified, the results will include approximate coordinates of the reporting stations.
Examples
GET https://wxt.navlost.eu/api/v1/r/METAR;TAF/HKJK;-4,39?options=location
Get the three latest METAR and TAF reports for Nairobi airport and for whatever is closest to 039° E, 04° S (Mombasa, in this case). Include the location of those airports.
Response
Content-Type: application/json
The structure of the returned object depends on whether a search has been done by ICAO identifier or by coordinates.
By ICAO identifier only:
Parent object |
By coordinates:
Parent object |
{ |
NRPL expressions
Evaluate
GET https://wxt.navlost.eu/api/v1/nrpl/{expr}
POST https://wxt.navlost.eu/api/v1/nrpl/{expr}
POST https://wxt.navlost.eu/api/v1/nrpl
Processes an NRPL expression.
This endpoint accepts indistinctly GET or POST verbs. The expression to be processed consists of the concatentation of the contents of the {expr}
part of the URL plus the request body (in case of POST requests). Either {expr}
or the request body may be empty. If both are present, {expr}
is evaluated first (which is handy for setting variables or pre-loading the stack).
Variables
There are two kinds of predefined global variables in the underlying NRPL service:
Type | Read | Write | Description |
---|---|---|---|
Control variables | ✔ | ✔ | Control certain query parameters, such as epoch and location |
Information variables | ✔ | ✘ | Retrieve data, such as weather element values, relative to the control variables |
These are the currently recognised control variables and their functions:
Variable | Purpose | Example | Default value |
---|---|---|---|
lat |
Set / retrieve the latitude | 45.52 !lat |
0 |
lon |
Set / retrieve the longitude | 3.7 !lon |
0 |
ele |
Set / retrieve the elevation | "A2000" !ele |
"GND" |
epoch |
Set / retrieve the epoch | @2016-01-01T03:30Z@ !epoch |
Current epoch |
The information variables match the name
property of the elements available at the list of forecast items endpoint.
Return value
Content-Type: application/json
This endpoint returns an array with the contents of the NRPL stack after the expression has been evaluated.
Examples
This example retrieves the current temperature, in degrees Celsius, Oslo Gardermoen and Pemba (Mozambique) airports:
GET https://wxt.navlost.eu/api/v1/nrpl/60.202584!lat;11.084127!lon;$TMP;274.15-;-12.991575!lat;40.524191!lon;$TMP;274.15-
Possible response:
[-3.185148103171059,25.581541089734742] |
Same example, but we also return the current timestamp:
GET https://wxt.navlost.eu/api/v1/nrpl/60.202584!lat;11.084127!lon;$TMP;274.15-;-12.991575!lat;40.524191!lon;$TMP;274.15-;$epoch
Possible response:
[-3.175974323564617,25.575446341123666,"2016-01-01T01:32:20.743Z"] |
A more involved example, using a POST request:
# Let us create a file in the current directory |
Possible result:
[ |
Note that this example, like any other NRPL expression, may be run directly off the URL via a GET request, if the user is willing to put up with a certain amount of unwieldiness. The GET equivalent to the above (minus comments, for brevity) would be:
curl -u user:password 'https://wxt.navlost.eu/api/v1/nrpl/60.202584;11.084127;-12.991575;40.524191;NEWSET;!!results;%C2%ABDEPTH;2;GE%C2%BB%C2%AB!lon;!lat;$TMP;273.15-;%22temp%22;OBJECT;SET;$RH;%22rel_humidity%22;ROT;SET;$UGRD;$VGRD;HYPOT;3.6%C3%971.852%C3%B7;%22wind_speed%22;ROT;SET;$lon%22longitude%22ROT;SET;$lat%22latitude%22ROT;SET;$epoch%22epoch%22ROT;SET;$ele%22elevation%22ROT;SET;$$results;SUNION;!!results%C2%BBWHILE;$$results;SET%E2%86%92;DROP' |
© 2016 Aaltronav s.r.o.