Description of the NWX web service
Introduction
The NWX web service is an interface to the wind and weather database at navlost.eu, so that third party applications can access its data.
Index
- Introduction
- Index
- Usage
- Usage Example
- Compression
- Terms of Use
- Acceptance
- Privacy
- Warranty
- Application Requirements For Royalty-free Access
- User Requirements For Royalty-free Access
- Access Restrictions
- Copyright
- Registering an Application
- Registering As a User
- Authentication
- Application Authentication
- Authentication Example For An Application
- User Authentication
- Authentication Example For a User
- Quotas
- Specification
<nwx>
Element<application>
Element<user>
Element<Request>
Element<Response>
Element<error>
Element<warning>
Element<Notice>
Element<Attributes>
Element- Available Data
<AvailableEpochs/>
<AvailableLevels/>
<AvailableGeomagModels/>
<Chart/>
<gph/>
<Geomag/>
<Metar/>
<ProfileGraph/>
<qff/>
<srss/>
<Taf/>
<temp/>
<terrain/>
<Wind/>
- Out of Band Data
- The NwxData Generic Response Format
- Attributes
- Version Notes
Usage
This web service can be accessed via HTTP by sending an
appropriately formatted POST request to the address http://navlost.eu/aero/nwx
.
The body of the request should be an XML document containing a valid
NWX request, as described below in the Specification
section.
Usage Example
Raw HTTP data
POST /aero/nwx HTTP/1.1
Host: www.navlost.eu
Content-Length: 233
Content-Type: application/xml
Pragma: no-cache
Cache-Control: no-cache
<nwx version="0.3.5">
<Request id="2">
<wind id="wpt01" p="42.5,3.1" z="180" u="F" e=""/>
<wind id="wpt02" p="43.55,4.01" z="180" u="F" e=""/>
</Request>
</nwx>
HTTP/1.x 200 OK
Date: Wed, 08 Oct 2008 00:28:48 GMT
Content-Length: 348
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
<nwx version="0.3.5">
<Response id="2">
<Wind id="wpt01" p="42.5,3.1" z="180" u="F" e="">
<dir>243.800812112</dir>
<speed>17.6946284278</speed>
</Wind>
<Wind id="wpt02" p="43.55,4.01" z="180" u="F" e="">
<dir>246.230341105</dir>
<speed>17.015226063</speed>
</Wind>
</Response>
</nwx>
Compression
For low-bandwidth or high-cost connections (such as satellite
or GPRS), it might be desirable to reduce the amount of data traversing
the network. While this specification has been designed with that in
mind (e.g., by allowing an unlimited number of requests to be included
in the same message), the best gain is to be obtained by using
compression, therefore, if the HTTP request includes an Accept-Encoding
header with a value of either gzip
or deflate
,
the server will compress the response.
A compressed response can be detected by the presence of a Content-Encoding
header, although some HTTP clients and libraries will decompress the
data transparently to the user—check your library's
documentation for details.
Compressing even small (<1Kb) messages can result in bandwidth savings of over 60%.
Terms of Use
Your use of this service whether as final user or as an application developer, is subject to the following terms:Acceptance
- As a final user, your acceptance of these terms is implied by your use of the service, be it directly or through a third-party application.
- As a developer, your acceptance of these terms is implied by building into your application the capability to interface with this service.
Privacy
- The following information is systematically collected for every call to the service API: remote IP address, date and time of the request, request URL, HTTP result code, and HTTP response size. In the case of registered applications, name and version of the calling application, and in the case of a registered and logged in user, the user handle. Certain abnormal requests and application errors cause diagnostics to be logged which may contain additional information.
- For application developers who register their work, the following data is additionally collected: the name(s) and version(s) of their application(s), a hash of their application's access password, contact email address and a URL where their application can be used or downloaded.
- For registered users, their user handle and a hash of their password is kept on file. Optionally an email address is recorded.
- From time to time, the full text of requests and responses might be captured for troubleshooting or statistic purposes.
- Blacklists may be kept containing IP addresses, timestamps, and any other information useful to disallow access to the service to disruptive users.
- None of this information will be shared with third parties in any way, or used for purposes unrelated to the provision of this service.
- Logs and other diagnostic data are kept for 90 days.
- Blacklists are kept indefinitely.
Warranty
- No warranty whatsoever is made as to the availability, reliability, or accuracy of any of the data provided by the service.
Application Requirements For Royalty-free Access
- Applications using this service must comply with at least one of the following requirements:
- Be generally accessible to users without charge. A download URL for your application should be available on the internet. User login might be required by your application, as long as registration is free of charge and available to the public at large.
- Be Free and Open Source Software as defined at http://www.fsf.org/licensing/essays/free-sw.html. An application will be considered Free and Open Source if in the public domain, or if distributed under a Free Software licence, as categorised at http://www.fsf.org/licensing/licenses/index_html (both GPL-compatible and GPL-incompatible free licences are acceptable the purposes of these terms).
- Applications which do not comply with either or both of the conditions in the previous point are required to pay access fees. Use the form at http://www.navlost.eu/contact to discuss your requirements.
User Requirements For Royalty-free Access
Compliance with both of the following points is mandatory for royalty-free access by users:- You must not use the data provided by this service for commercial purposes in a systematic manner. Amongst other examples, this includes the sale of any data provided by this service or substantially derived from it, and systematic use of the service for business-related activities (e.g., by an air-taxi company, or a commercial website). Occasional use in a commercial setting is tolerated, as long as it's not the main use by that particular subscriber.
- Your use of the service must not have a significant impact on the service's performance or availability to other users.
Access Restrictions
- Access through means other than described in the service's help page is not permitted.
- Bulk downloads are not permitted, unless explicitly authorised in writing by the service owner.
- Some data provided by the service may be restricted to certain categories of users. You may not use or attempt to use any restricted data for which you have not been granted access by the service owner.
- Access quotas are in place for certain types of use. Where access to the service or part of it is denied in the form of a "Quota Exceeded" or similar error, you must not attempt to circumvent it.
- You may not sell or redistribute data obtained from this service in any form for commercial purposes.
Copyright
- Applications which access the service must include the copyright notice "(subject) © (year) Diego Berge <http://navlost.eu/>", where (subject) should be replaced by one of the phrases "NWX Service", "NWX Data", or "Weather", and (year) should be replaced by the current year. This notice must be displayed wherever your own application's copyright notices are shown (e.g., in a splash screen, or an About box).
- Any other rendering of the data (e.g., in a publication) must include the copyright notice "© (year) Diego Berge <http://navlost.eu/>".
- Some service content might be subject to additional copyright. In those cases, the affected data will incorporate a copyright notice which must be displayed along with the content.
Registering An Application
Developers of third-party applications wishing to access the service are requested to register their applications by contacting me via http://www.navlost.eu/contact. Registering is free of charge and by using the application, users are not subject to the preset quotas which apply to anonymous requests.Registering As a User
Individual users are not currently required to register in order to access the service as long as they comply with the terms set above for royalty-free access. With the upcoming addition of new data subject to more restrictive access policies, a way for users eligible to access such data will be provided.Authentication
Registered users and applications accessing the service are required to authenticate themselves on every request by using the following mechanisms.Application Authentication
Applications are required to send authentication credentials on every message. This is implemented via the<application/>
element. This element includes the following attributes related to
authentication:"name"
attribute: holds the application's name as given in the registration details"instance"
attribute: holds the application's instance number"timestamp"
attribute: holds the current UTC timestamp in"YYYY-MM-DD HH:MM:SS"
format"token"
attribute: holds the authentication token, which is formed by concatenating the name and version attributes with a SHA-1 sum of the application's secret (delivered upon registration), and followed by the timestamp attribute, then taking the SHA-1 sum of the whole thing.
Authentication Example For An Application
Assume we have an application named Ajax at version 1.0.0, its secret is "abc" and the current UTC time is 13:59:30 on the 15th of October, 2010. We proceed as follows:- Calculate the SHA-1 sum of the secret to obtain
"a9993e364706816aba3e25717850c26c9cd0d89d"
. Note that typically the pre-calculated SHA-1 sum would be included directly in your application code, rather than the actual secret. - Concatenate all the above data to obtain the text string
"Ajax1.0.0a9993e364706816aba3e25717850c26c9cd0d89d2010-10-15 13:59:30"
. - Calculate the SHA-1 sum of the above to obtain
"92ee017eadde0bd3282b8d796664b3584cbfa1f0"
. This is the value of your"token"
attribute.
User Authentication
Applications supporting registered users are required to send user authentication credentials on every message. This is implemented via the<user/>
element (note that the syntax of this element has changed since the
previous version of this specification). This element includes the
following attributes related to authentication:"id"
attribute: holds the user name as given in the registration details"timestamp"
attribute: holds the current UTC timestamp in"YYYY-MM-DD HH:MM:SS"
format"token"
attribute: holds the authentication token, which is formed by concatenating the ID attribute with a SHA-1 sum of the user's secret (delivered upon registration), and followed by the timestamp attribute, then taking the SHA-1 sum of the whole thing.
Authentication Example For A User
Assume we have a user name "jdoe" with a password "abc" and the current UTC time is 13:59:30 on the 15th of October, 2010. We proceed as follows:- Calculate the SHA-1 sum of the user's password to obtain
"a9993e364706816aba3e25717850c26c9cd0d89d"
. Note that if remembering the user's credentials, the application would be expected to store the SHA-1 sum of the password, rather than the password itself. - Concatenate all the above data to obtain the text string
"jdoea9993e364706816aba3e25717850c26c9cd0d89d2010-10-15 13:59:30"
. - Calculate the SHA-1 sum of the above to obtain
"58ec3d759a77c75d19d228c9cf8a49c8e3ed11ad"
. This is the value of your"token"
attribute.
Quotas
As the service has been growing in popularity faster than the supporting server has been growing in resources, it is starting to become necessary to rationalise the use of server capacity. To this end, since late September, 2009, a quota system is in place which limits access to the service to a certain number and type of requests per day and per IP address. Users of registered applications are not subject to this quota system at the moment, and if it is felt necessary to apply quotas to them in the future, it will be discussed with the application developers how this can be best approached in order to minimise any impact in the final user experience.The quota system will undergo a series of adjustments in the course of the next few months, gradually reducing the usage quota for unregistered users and applications. For this reason, developers of existing clients are encouraged to register their applications as soon as possible.
Current Quota
As of now, unregistered applications are limited to a maximum of 900 requests of any type per IP in any 24 hour period. Registered applications can make unlimited requests.Future Quotas
The current limit of 900 requests per IP and 24 hour period will be phased out by the end of 2009 and will be replaced by a "credits" system where usage is determined by the type of requests being made, rather than solely the number of connections. This acknowledges the fact that not all requests are equal in terms of computing resources.Specification
Every NWX document has <nwx>
as its root element—this element is required. A <nwx>
element's allowed contents depend on whether the document is a request
or a response message:
- For a request, it contains zero or more
<Request>
elements. - For a response, it contains zero or
more
<Response>
elements. It may additionally contain one or more<error>
,<warning>
, or<Notice>
elements.
<nwx>
Element
- Description
- This is the root element of every NWX request or response.
- Attributes
- A
version
attribute should be specified to indicate the version of the service that the client implements. If noversion
attribute is specified, the server will use the most recent version. - Contents
- It contains zero or more of the following elements:
<user>
,<Request>
,<Response>
,<warning>
,<error>
. - Example
-
<nwx version="0.3.5">
</nwx>
<application>
Element
- Description
- Authentication credentials of the application accessing the service. See the Application Authentication section for more info
- Attributes
- The following attributes are required (refer to the Authentication section
above):
name
: Name of the application accessing the service.instance:
Instance number of the application accessing the service.timestamp:
UTC timestamp.token:
authentication token for this application.
- Contents
- This element has no content
- Example
<application name="Ajax" instance="0" token="92ee017eadde0bd3282b8d796664b3584cbfa1f0" timestamp="2010-15-10 13:59:30"/>
<user>
Element
- Description
- Authentication credentials of the individual user accessing the service. See the User Authentication section for more info
- Attributes
- The following attributes are required:
id
: ID of the user accessing the service.timestamp
: UTC timestamp.token
: user's authentication token, as described in User Authentication.
- Contents
- This element has no content
- Example
<user id="jdoe" token="58ec3d759a77c75d19d228c9cf8a49c8e3ed11ad" timestamp="2010-10-15 13:59:30"/>
<Request>
Element
- Description
- This element identifies a service request from a client to the server.
- Attributes
- Optionally, the element may contain an
id
attribute, which can be used to uniquely identify each request and its associated response. - Contents
- A request contains one or more of the elements defined in the Available Data section.
- Example
-
<Request id="1"> <AvailableEpochs/> </Request>
<Response>
Element
- Description
- This element identifies a service response back from the
server to a client. There is one
<Response>
element for every<Request>
element in a valid NWX request message. - Attributes
- If an
id
attribute was used during the request, its value will be duplicated on the matching response.
For requests where this is applicable, anexpires
attribute will be included, the purpose of which is to allow clients to implement caching. The content of this attribute is the UTC date and time of the next scheduled weather database update—note that it is possible for this date to be in the past, this normally indicates that a scheduled update is in progress. - Contents
- It contains one or more of the elements defined in the Available Data section.
- Example
-
<Response id="1" expires="2008-10-08 12:20:00"> <AvailableEpochs> <epoch>2008-10-08 06:00:00</epoch> <epoch>2008-10-08 09:00:00</epoch> </AvailableEpochs> </Response>
<error>
Element
- Description
- This element offers a textual description of any condition which prevents all or part of the client request to be fulfilled. This is only ever present in server-originated messages.
- Attributes
- The
code
attribute is always present and uniquely identifies the type of error which has occurred. This value is unique across all errors and warnings in the system. - Contents
- This element contains a textual description of any error conditions which have occurred, possibly including diagnostic information and/or pointers to the offending parts of the request.
- Example
-
<error code="0">Malformed XML</error>
<warning> Element
- Description
- This element offers a textual description of any condition which, while not necessarily preventing the request to be fulfilled, could be indicative of a problem.
- Attributes
- The
code
attribute is always present and uniquely identifies the type of error which has occurred. This value is unique across all errors and warnings in the system. - Contents
- This element contains a textual description of the condition which has raised the warning, possibly including diagnostic information and/or pointers to the part of the request which caused the warning.
- Example
-
<warning code="4">Unrecognised element: Vind</warning>
<Notice> Element
- Description
- This element is used to notify the client of events
affecting the normal operation of the system, such as maintenance or
planned outages. It contains both machine-parseable and human-readable
information.
As an option, the user agent may elect to display the contents of a<Notice>
element to the user and/or take semi-automated action, such as offering the user to disable NWX features while the system undergoes maintenance, or simply not display errors if connection attempts fails during that time. - Attributes
-
id
: Contains a unique ID for this notice. As a notice will appear on every request during its time of applicability, the client can use this ID to keep track of any notices and can decide whether to carry out any actions such as showing the notice text to the user or changing the software's behaviour based on whether a notice has already been seen or not.category
: Identifies the type of event this notice informs about. Currently defined categories areserver-shutdown
,server-maintenance
, andnormal-operation
. The first implies that service will be unavailable during part or all of the applicability period, the second implies that service should be available, but there might be brief interruptions, and the third is used when a maintenance operation has been cancelled or deferred.
Based on the value of this attribute, the client may decide to carry out certain actions, such as automatically disable NWX requests during the time of applicability.priority
: Identifies the priority of this notice. Possible values in increasing order of priority are lowest, low, normal, high, highest. The client may use this value to decide whether to show the text of the notice to the user (perhaps based on a user-set preference).epoch-start
: Date and time when the event being notified is expected to start.epoch-end
: Date and time when the event being notified is expected to end. This can be used in conjunction withepoch-start
to carry out certain actions automatically, such as disabling connection attempts to the NWX server between those times.
- Contents
- This element contains one
<title>
element and one or more<body>
elements. Their descriptions are as follows:<title></title>
contains a short human-readable textual description of the event being notified.<body></body>
contains a detailed description of the event in a CDATA section. This element always includes the attributemimetype
with the MIME type of the element content. If more than one<body>
are present, one will always be of type "text/plain", while the other may be any valid MIME type which would be useful for conveying information, such as "text/html" or "application/pdf".
- Example
-
<Notice id="urn:uuid:6a2dbd58-7ea8-11de-95b5-00163e9b2a1e" category="server-shutdown" priority="high" epoch-start="2009-08-01 12:30:00" epoch-end="2009-08-01 20:30:00"> <title>NWX Server Maintenance</title> <body mimetype="text/plain"><![CDATA[ The NWX server will be going down for scheduled maintenance on the 1st of August between 12:30 and 20:30 UTC. During this time weather forecast features will be unavailable. We apologise for the inconvenience.]]> </body> </Notice>
<Attributes> Element
- Description
- This container element can be used to define one or more attributes which will be applied to its children. It is useful as shorthand to avoid duplication when many elements share common attributes, such as the same epochs or positions.
- Attributes
- Any number of arbitrary attributes can be defined and they will be applied to all of the element's children. Attributes redefined lower down in the hierarchy take precedence over those with the same name on upper levels.
- Contents
- This element can contain zero or more of the elements described in the Available Data section. Additionally, it can also contain other instances of itself, as shown in the second example below.
- Example
In this example we take advantage of the <Attributes/> element to abbreviate this request:
<nwx version="0.3.5"> <Request id="1"> <Wind id="wpt01" p="42.5,3.1" e="" z="120" u="F"/> <qff id="wpt01" p="42.5,3.1" e=""/> <temp id="wpt01" p="42.5,3.1" e="" z="120" u="F"/> <geomag id="wpt01" p="42.5,3.1" e="" model="WMM2010"/> <Metar id="wpt01" p="42.5,3.1" count="2"/> </Request> </nwx>
With this new element, it can be equivalently represented as:
<nwx version="0.3.5"> <Request id="1"> <Attributes id="wpt01" p="42.5,3.1" e="" z="120" u="F"> <Wind/> <qff/> <temp/> <geomag model="WMM2010"/> <Metar count="2"/> </Attributes> </Request> </nwx>
In this case, the result would be something like:
<?xml version="1.0" encoding="UTF-8"?> <nwx version="0.3.5"> <Response id="1" expires="2010-04-03 00:20:00"> <Attributes id="wpt01" p="42.5,3.1" e="2010-04-02 18:00:00" z="120" u="F"> <Wind> <dir>271</dir> <speed>20</speed> </Wind> <qff p="42.5000,3.1000">1015</qff> <temp>-9.1</temp> <Geomag model="WMM2010"> <decl>0.0782</decl> <ddecl>0.1133</ddecl> </Geomag> <Metar p="42.733,2.867" dist="17.4" icao="LFMP"> <report epoch="2010-04-02 20:00:00"><![CDATA[LFMP 022000Z AUTO 19002KT 9999NDV NSC 11/08 Q1016]]></report> <report epoch="2010-04-02 19:00:00"><![CDATA[LFMP 021900Z AUTO 02006KT 9999NDV FEW047 12/09 Q1015]]></report> </Metar> </Attributes> </Response> </nwx>
A slightly more involved example is used here to demonstrate nesting and the higher priority given to more deeply nested attribute definitions:
Note how the children <Attributes/> elements inherit the epoch from their parent, how the<nwx version="0.3.5"> <Request id="1"> <Attributes e=""> <Attributes id="wpt01" p="42.5,3.1" z="120" u="F"> <Wind z="80"/> <Wind z="100"/> <Wind/> <Wind z="140"/> <Wind z="160"/> <qff/> <temp/> <geomag model="WMM2010"/> <Metar count="2"/> </Attributes> <Attributes id="wpt02" p="43.55,4.01" z="180" u="F"> <Wind z="140"/> <Wind z="160"/> <Wind/> <Wind z="200"/> <Wind z="220"/> <qff/> <temp/> <geomag model="WMM2010"/> <Metar count="2"/> </Attributes> </Attributes> </Request> </nwx>
z
attributes are overridden for some of the <Wind/> requests, and how for some elements the "predefined" attributes are complemented by additional attributes in the element itself.
Available Data
Version 0.0 implements the following data elements:
<AvailableEpochs/>
Get available epochs<AvailableLevels/>
Get available pressure levels<Chart/>
Get forecast charts<gph/>
EXPERIMENTAL Get geopotential height information<Metar/>
Get METARs<Taf/>
Get TAFs<temp/>
Get temperature information<Wind/>
Get wind information
Version 0.1 also supports:
<terrain/>
EXPERIMENTAL Get terrain height information
Version 0.1.1 also supports:
<ProfileGraph/>
EXPERIMENTAL Draw a route's profile view
Version 0.3.3 also supports:
<srss/>
Calculate sunrise and sunset times
<AvailableEpochs>
(Request)
- Description
- Requests the list of epochs for which wind/weather information is currently available.
- Attributes
- Versions 0.3.0 and latter support the
attr
attribute, which restricts the results to the set of epochs for which a given feature is valid or available. This is not necessarily a subset of the epochs returned by an unrestricted request.
Currently the only acceptable value isattr="dvsi"
, which returns epochs for which DVSI data is available (see the description of the Chart request for more details). - Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <AvailableEpochs/> </Request> </nwx>
<AvailableEpochs>
(Response)
- Description
- Contains the list of epochs for which wind/weather information is currently available.
- Attributes
- As given in the request.
- Contents
- Zero or more
<epoch>
elements. The content of each is a UTC date and time in ISO-6801 format (YYYY-MM-DD hh:mm:ss) to seconds precision. Any weather data requested should be referred precisely to one of the epochs in this list. - Example
-
<nwx version="0.3.5"> <Response id="1"> <AvailableEpochs> <epoch>2008-10-08 06:00:00</epoch> <epoch>2008-10-08 09:00:00</epoch> <AvailableEpochs/> </Response> <nwx>
<AvailableLevels>
(Request)
- Description
- Requests the list of pressure levels for which weather information is currently available.
- Attributes
- nil
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <AvailableLevels/> </Request> </nwx>
<AvailableLevels>
(Response)
- Description
- Contains the list of pressure levels for which weather information is currently available.
- Attributes
- nil
- Contents
- Zero or more
<level>
elements, each containing a pressure level in hectopascals or the units indicated in theu
attribute. - Example
-
<nwx version="0.3.5"> <Response id="1"> <AvailableLevels> <level u="hPa">1000</level> <level u="hPa">500</level> <AvailableLevels/> </Response> <nwx>
<AvailableGeomagModels>
(Request) — New in version 0.2.5
- Description
- Requests the list of available geomagnetic model grids.
- Attributes
- nil
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <AvailableGeomagModels/> </Request> </nwx>
<AvailableGeomagmodels>
(Response)
- Description
- Contains the list of available geomagnetic models.
- Attributes
- nil
- Contents
- Zero or more
<GeomagModel>
elements, with the following structure:<GeomagModel>
Model name
<name></name>
Base epoch of the grid data
<epoch type="base"></epoch>
First epoch for which the model is valid
<epoch type="first"></epoch>
Last epoch for which the model is valid
<epoch type="last"></epoch>
Resolution in the latitude axis (in sexagesimal degrees)
<resolution type="lat" u="deg"></resolution>
Resolution in the longitude axis (in sexagesimal degrees)
<resolution type="lon" u="deg"></resolution>
</GeomagModel>
- Example
-
<nwx version="0.3.5"> <Response id="1" expires="2009-10-06 18:20:00"> <AvailableGeomagModels> <GeomagModel> <name>WMM2005</name> <epoch type="base">2009</epoch> <epoch type="first">2005</epoch> <epoch type="last">2010</epoch> <resolution type="lat" u="deg">0.5</resolution> <resolution type="lon" u="deg">0.5</resolution> </GeomagModel> <GeomagModel> <name>IGRF-10</name> <epoch type="base">2009</epoch> <epoch type="first">1900</epoch> <epoch type="last">2010</epoch> <resolution type="lat" u="deg">0.5</resolution> <resolution type="lon" u="deg">0.5</resolution> </GeomagModel> </AvailableGeomagModels> </Response> </nwx>
<Wind>
(Request)
- Description
- Request the wind vector at a specific position and altitude at a given epoch.
- Attributes
- The following attributes are required:
p
: extended geographic position expressed as latitude,longitude in decimal degrees on the WGS84 datum. Valid range is from -90.0 to 90.0 for latitudes and -180.0 to 180.0 for longitudes.z
: extended pressure level in hectopascals, or flight level or altitude in feet or metres. This value must correspond to a pressure level at a height not below the highest pressure level in the<AvailableLevels>
list, and at a height not above the lowest pressure level in that list. It does not, however, need to correspond precisely to one of the listed levels—an interpolation will be carried out between the two nearest levels to come up with the resulting wind vector.u
: designator of the units in which thez
value has been expressed. It must be one of the following: F for a flight level in hundreds of feet (e.g., F85, F130), A for an altitude in feet (e.g., A4000, A8500), S for a metric flight level (e.g., S30, S50), or M for a metric altitude (e.g., M1500, M6000).e
: epoch for which the wind data is requested. The epoch should be not earlier than the earliest epoch returned by<AvailableEpochs>
, and no latter than the latest available epoch. If this value does not match exactly one of the forecast epochs an interpolation will be carried out between the two nearest available epochs.
id
: it contains an ID which should uniquely identify the wind request, in order to facilitate matching multiple wind requests with their corresponding responses.
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <Wind id="wpt01" p="42.5,3.1" z="120" u="F" e=""/> <Wind id="wpt02" p="43.55,4.01" z="180" u="F" e=""/> </Request> </nwx>
<Wind>
(Response)
- Description
- A polar vector representing the wind force at a given location and time.
- Attributes
- See the
<Wind>
(Request) section above. Any request attributes are copied verbatim to the response in order to faciliate identification. - Contents
- Each
<Wind>
element contains the following two sub-elements:<dir></dir>
: Geographical direction from which the wind is blowing, in degrees True.<speed></speed>
: Wind speed in knots.
- Example
-
<nwx version="0.3.5"> <Response id="1"> <Wind id="wpt01" p="42.5,3.1" z="120" u="F" e=""/> <dir>243.324931128</dir> <speed>17.2134607817</speed> </Wind> <Wind id="wpt02" p="43.55,4.01" z="180" u="F" e=""/> <dir>246.230341105</dir> <speed>17.015226063</speed> </Wind> </Response> </nwx>
<Chart>
(Request)
- Description
- Request an image depicting weather information for a given area.
- Attributes
- The following attributes are required:
x
: Width of the resulting image in pixelsy
: Height of the resulting image in pixelsz
: Pressure level of interest. Must be one of the values returned by<AvailableLevels>
e
: Epoch of interest. Must be one of the values returned by<AvailableEpochs>
lat0
: Latitude of the lower edge of the image, in decimal degrees on the WGS84 datum.lat1
: Latitude of the upper edge of the image, in decimal degrees on the WGS84 datum.lon0
: Longitude of the left edge of the image, in decimal degrees on the WGS84 datum.lon1
: Longitude of the right edge of the image, in decimal degrees on the WGS84 datum.
id
: it contains an ID which should uniquely identify the chart request, in order to facilitate matching multiple chart requests with their corresponding responses.layout
: Can be one of"overlay"
(which is the default) or"map"
, the latter shows a frame around the chart, optionally a title (see<theme>title text</theme>
below), and possibly a colour bar legend depending on the type of output. This format is usually not suitable where the user needs to georeference the output.background
: If it has the value"transparent"
, the resulting image will hace a transparent background, suitable for use as an overlay.output
: (New in version 0.2.3) Output method. If specified, it can take one of the values indicated in the out-of-band output section. If not specified, the data will be returned inline.
- Contents
- Zero or more
<theme></theme>
elements containing the name of a theme, or category of information which one wants depicted on the map. The possible values and textual description for each will in the future be provided by a mechanism similar to<AvailableEpochs>
. For the moment, these are some of the available themes:setmpdraw on
: Draws coastlines and political boundaries.setgrid on
: Draws a lat/lon grid.preciptype
: Precipitation type: rain, freezing rain, hail, snowprmslmsl
: Atmospheric pressure reduced at mean sea level (QFF)hgt0c
: Freezing level (0°C isotherm)wind
: Wind barbs representing wind direction and strengthhgtprs
: Geopotential height, in feet. Usehgtprs rainbow
for different coloured contourstmpsfc
: Surface temperature, as a shade or contour plot. Usetmpsfc c
for a contour plot, you can optionally specify the contour interval, e.g.:tmpsfc c 5
tmpsfc_g
: Surface temperature, as a numeric gridtmpprs_g
: Temperature at the selected pressure level, as a numeric gridrhprs
: Relative humidity at selected level. Userhprs c
for a contour plotcapesfc
: Convective actionapcpsfc
: Accumulated precipitation in the last 3hrtcc x
: Total cloud cover for low, mid, and high level clouds. Replacex
withl
,m
, orh
, respectivelytccc x
: As above, but shows a contour plot instead.title text
: New in version 0.3.3. Iflayout="map"
, showtext
as a title above the graphic. It has no effect for other layouts.presclt x
: Cloud top altitude for low, mid, and high level clouds. Replacex
withl
,m
, orh
, respectivelyincloud l
: Cloud density at the selected level. Replacel
with a pressure level in millibars to obtain a plot of cloud density at that level, e.g.:incloud 723
incloud l 1
: Freezing cloud density at the selected level. As above, but only show cloud density if above the freezing level.dvsi
: Deformation Vertical Shear Index (DVSI) between the selected level and the one below it, an indicator of the likelyhood of clear air turbulence in a given area. This is an experimental feature available from version 0.3.0.route
: New in version 0.3.3. Plot a flight route on the chart, optionally naming the waypoints. When using this theme,<Chart/>
must contain one or more<route></route>
subelements, each containing a flight route. The format of<route></route>
subelements is exactly as described in the equivalent element of the <ProfileGraph/> request, with the exception that more than one route may be defined. Routes may contain anid
attribute, which can be referenced from the theme element like this:<theme>route id</theme>
, whereid
corresponds to the value given in the route's id attribute. See the second example below for more info.
- Example 1—simple chart request (see output)
-
<nwx version="0.3.5"> <Request id="1"> <Chart id="c01" x="800" y="600" z="700" e="" lat0="30" lat1="65" lon0="-20" lon1="35"> <theme>prmslmsl</theme> <theme>wind</theme> </Chart> </Request> </nwx>
- Example 2—chart request with "map" layout and two routes shown (see output)
-
<nwx version="0.3.5"> <Request id="1"> <Chart id="c01" x="800" y="600" z="300" e="" lat0="30" lat1="65" lon0="-20" lon1="35" layout="map"> <route id="rte1"> <wpt name="LFLB" id="LFLB" p="45.63927,5.880122"/> <wpt id="TOC1" p="45.66734,5.404942" z="100" u="F"/> <wpt id="MEBAK2" p="45.70806,4.648889" z="100" u="F"/> <wpt id="BOC3" p="45.76801,4.301144" z="100" u="F"/> <wpt id="TIS5" p="45.88183,3.553578" z="120" u="F"/> <wpt id="TOD6" p="46.02392,3.015765" z="120" u="F"/> <wpt id="GERVA7" p="46.05764,2.874306" z="100" u="F"/> <wpt id="LMG8" p="45.81593,1.025572" z="100" u="F"/> <wpt id="NORON9" p="45.48472,0.6775" z="100" u="F"/> <wpt id="VELIN10" p="44.98,0.1555556" z="100" u="F"/> <wpt id="TOD11" p="44.95213,-0.0287319" z="100" u="F"/> <wpt name="LFBD" id="LFBD" p="44.82865,-0.7153444"/> </route> <route id="rte2"> <wpt name="LFBO" id="LFBO" p="43.63513,1.367856"/> <wpt id="TOC1" p="43.88459,1.739923" z="100" u="F"/> <wpt id="GAI2" p="43.95404,1.824175" z="100" u="F"/> <wpt id="CFA3" p="45.78747,3.192194" z="100" u="F"/> <wpt id="MOU4" p="46.70677,3.631678" z="100" u="F"/> <wpt id="RLP5" p="47.9063,5.249167" z="100" u="F"/> <wpt id="EPL6" p="48.31782,6.059403" z="100" u="F"/> <wpt id="GIVOR7" p="48.65861,6.391389" z="100" u="F"/> <wpt id="BOC8" p="49.20649,6.464759" z="100" u="F"/> <wpt id="AKELU9" p="49.36694,6.463889" z="120" u="F"/> <wpt id="SUTAL10" p="49.46667,6.391667" z="120" u="F"/> <wpt id="LIMGO11" p="49.63722,6.281667" z="120" u="F"/> <wpt id="TALUK12" p="50.08861,6.648056" z="120" u="F"/> <wpt id="ULMEN13" p="50.22167,6.875278" z="120" u="F"/> <wpt id="RUDUS14" p="50.0475,8.078333" z="120" u="F"/> <wpt id="TOBAK15" p="50.57167,8.785833" z="120" u="F"/> <wpt id="GISEM16" p="50.63556,8.819444" z="120" u="F"/> <wpt id="WRB17" p="51.50569,9.110914" z="120" u="F"/> <wpt id="HLZ18" p="52.36339,10.79522" z="120" u="F"/> <wpt id="BATEL19" p="52.54694,11.09972" z="120" u="F"/> <wpt id="BKD20" p="53.03452,11.54621" z="120" u="F"/> <wpt id="ARGAD21" p="54.50611,13.49611" z="120" u="F"/> <wpt id="ASDIN22" p="54.65833,13.76861" z="120" u="F"/> <wpt id="DETNI23" p="54.91667,14.34417" z="120" u="F"/> <wpt id="ROE24" p="55.06558,14.75869" z="120" u="F"/> <wpt id="KOLJA25" p="56,16.81467" z="120" u="F"/> <wpt id="EVONA26" p="57.165,19.92472" z="120" u="F"/> <wpt id="LOGNA27" p="57.84306,21.66028" z="120" u="F"/> <wpt id="MASIS28" p="58.65583,23.36917" z="120" u="F"/> <wpt id="SULUN30" p="58.97167,24.06861" z="120" u="F"/> <wpt name="EETN" id="EETN" p="59.41333,24.8325"/> </route> <theme>title Example Map Showing Cloud Tops And Two Routes</theme> <theme>presclt l</theme> <theme>prmslmsl</theme> <theme>wind</theme> <theme>setmpdraw on</theme> <theme>route</theme> <theme>route</theme> </Chart> </Request> </nwx>
<Chart>
(Response)
- Description
- A PNG image depicting weather information for a given area
- Attributes
- See the
<Chart>
(Request) section above. Any request attributes are copied verbatim to the response in order to faciliate identification. - Contents
- Each
<Chart>
element contains the following sub-elements:<expires></expires>
: UTC expiry time and date of this chart. Corresponds to the next weather database update cycle. The image can be cached and reused until the time indicated by this element.<data></data>
: Image data, Base64 encoded with CRLF line breaks every 76 characters, as per RFC2045 semantics.<href></href>
: Only present in versions prior to 0.3.0. See the section on out-of-band data for the implementation in latter versions. URL from where a copy of this image might be downloaded. Note that this URL is only valid until the expiration time indicated in the response.
- Example
-
(Once decoded, the above chart could look something like this example).<nwx version="0.3.5"> <Response id="1"> <Chart id="c01" x="800" y="600" z="700" e="" lat0="30" lat1="65" lon0="-20" lon1="35"> <expires>2008-10-09 00:20:00</expires> <data><![CDATA[iVBORw0KGgoAAAANSUhEUgAAAyAAAAJYBAMAAABoWJ9DAAAAD1BMVEX///8AAABgYGDwgiiqqqpb M7wTAAAgAElEQVR4nOy9CZrkptI2CqIWICq9AJXqW4Cy5QVk2b3/NV3FBAEEGjKr233/52B3pQbE 9EJMBODi/8IfFdzo/hf+qPA/QP6w8Dogb68X4vEnJPFn1ON/I+RPC/8D5A8L/wPkDwv/A+QPC/8D 5A8L/5OyJPwZ9XC3FcPyfAp/RkVeT+JX1mM9HWSEhPzoBWz+F1IIZTOfDy3JCv8vI1O2kwr9yi7b [....] 3rUYDlGR+y906kWIZ/VG1tVdvyvVu97/hy5f4ilaGXEAwRn5iD5ikTX/XwPks1HoZzN1Hj0we//v 6W+P4x/qZUL/HiD/v+jv909vIvIfII18j8Y7/N6K9h8gjJy+coXiB3Er/QeIR9ikselztfe/rIxp R4wvGRIAAAAASUVORK5CYII=]]> </data> <href><![CDATA[http://www.navlost.eu/aero/met?z=700&t=3&winf=prmslmsl%3Bwind&x=800&y=600&lon0=-20&lon1=35&lat0=30&lat1=65&img=5]]></href> </Chart> </Response> </nwx>
<Metar>
(Request)
- Description
- Requests METAR reports for a given ICAO identifier or near a given position.
- Attributes
- One of the following attributes must be present:
p
: geographic position expressed as latitude,longitude in decimal degrees on the WGS84 datum. Valid range is from -90.0 to 90.0 for latitudes and -180.0 to 180.0 for longitudes. The server will return METAR reports for the nearest available location.icao
: Four-letter ICAO identifier of the location for which to obtain the METARs.
maxage
: Do not return METARs from locations for which the most recent report is older thanmaxage
hours. Note that if used together with thep
option, you will get reports for the closest ICAO location for which reports newer thanmaxage
hours are available, which may not necessarily be the closest ICAO location.count
: Return the latestcount
reports for the given location or position. If not present, only the most recent report is returned
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <Metar p="46,5" maxage="3" count="2"/> </Request> </nwx>
<Metar>
(Response)
- Description
- Contains the text of the requested METAR.
- Attributes
-
p
: In the response, this attribute contains the coordinates of the location the METAR refers to.dist
: Only present if a position was given in the request. Contains the distance in nautical miles between the location in the request and the location of the METAR observation.icao
: Four-letter ICAO identifier of the METAR location.
- Contents
- Zero or more
<report/>
elements, each of which contains anepoch
attribute with the date and time of the METAR observation, and the text of the METAR as character data. - Example
-
<?xml version="1.0" encoding="UTF-8"?> <nwx version="0.3.5"> <Response id="1"> <Metar p="45.733,5.083" dist="16.4" icao="LFLL"> <report epoch="2008-11-07 21:00:00"> <![CDATA[LFLL 072100Z 14003KT 9999 SCT040 BKN060 11/09 Q1019 NOSIG]]> </report> <report epoch="2008-11-07 20:00:00"> <![CDATA[LFLL 072000Z 20003KT 170V230 9999 -RA SCT046 BKN060 12/08 Q1018 NOSIG]]> </report> </Metar> </Response> </nwx>
<Taf>
(Request)
- Description
- Requests TAF reports for a given ICAO identifier or near a given position.
- Attributes
- One of the following attributes must be present:
p
: geographic position expressed as latitude,longitude in decimal degrees on the WGS84 datum. Valid range is from -90.0 to 90.0 for latitudes and -180.0 to 180.0 for longitudes. The server will return TAF reports for the nearest available location.icao
: Four-letter ICAO identifier of the location for which to obtain the TAFs.
maxage
: Do not return TAFs from locations for which the most recent report is older thanmaxage
hours.count
: Return the latestcount
reports for the given location or position. If not present, only the most recent report is returned
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <Taf p="46,5"/> </Request> </nwx>
<Taf>
(Response)
- Description
- Contains the text of the requested TAF.
- Attributes
-
p
: In the response, this attribute contains the coordinates of the location the TAF refers to.dist
: Only present if a position was given in the request. Contains the distance in nautical miles between the location in the request and the location of the TAF.icao
: Four-letter ICAO identifier of the TAF location.
- Contents
- Zero or more
<report/>
elements, each of which contains anepoch
attribute with the date and time of the TAF, and the text of the TAF as character data. - Example
-
<?xml version="1.0" encoding="UTF-8"?> <nwx version="0.3.5"> <Response id="1"> <Taf p="45.733,5.083" dist="16.4" icao="LFLL"> <report epoch="2008-11-07 17:00:00"> <![CDATA[TAF LFLL 071700Z 0718/0824 VRB03KT 9999 SCT030 BKN055 PROB30 TEMPO 0718/0802 RA BECMG 0802/0804 6000 OVC015 BECMG 0810/0812 9999 SCT040 BECMG 0813/0815 16004KT BECMG 0819/0821 18010KT]]> </report> </Taf> </Response> </nwx>
<gph>
(Request)
- Description
- Request geopotential height information (i.e., actual aircraft altitude above mean sea level, as opposed to that indicated by the altimeter) at a given position, (indicated) altitude, and epoch.
- Attributes
- The following attributes are required:
p
: extended geographic position expressed as latitude,longitude in decimal degrees on the WGS84 datum. Valid range is from -90.0 to 90.0 for latitudes and -180.0 to 180.0 for longitudes.z
: extended pressure level in hectopascals, or flight level or altitude in feet or metres. This value must correspond to a pressure level at a height not below the highest pressure level in the<AvailableLevels>
list, and at a height not above the lowest pressure level in that list. It does not, however, need to correspond precisely to one of the listed levels—an interpolation will be carried out between the two nearest levels if necessary.u
: designator of the units in which thez
value has been expressed. It must be one of the following: hPa for a pressure level in hectopascals, F for a flight level in hundreds of feet (e.g., F85, F130), A for an altitude in feet (e.g., A4000, A8500), S for a metric flight level (e.g., S30, S50), or M for a metric altitude (e.g., M1500, M6000).e
: epoch for which the information is requested. Currently it must match precisely one of the values supplied in the<AvailableEpochs>
response, although this is expected to change in the future to allow arbitrary epochs within the time range delimited by the available epochs, with interpolation taking place in the time dimension as well as in space.
id
: it contains an ID which should uniquely identify this request, in order to facilitate matching requests with their corresponding responses.
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <gph id="wpt01" p="42.5,3.1" z="6000" u="A" e=""/> <gph id="wpt02" p="43.55,4.01" z="180" u="F" e=""/> </Request> </nwx>
<gph>
(Response)
- Description
- Forecast actual altitude in feet above mean sea level corresponding to the pressure level, flight level, or altitude specified in the request.
- Attributes
- See the
<gph>
(Request) section above. Any request attributes are copied verbatim to the response in order to faciliate identification.
Additionally, aq
attribute will be present. This indicates the estimated maximum interpolation error (in feet) for the result. A non-interpolated value (i.e., corresponding to a pressure level for which geopotential height information is directly available in the forecast) will haveq="0"
. Note that geopotential height information is available for many more pressure levels than those returned by<AvailableLevels/>
. - Contents
- Forecast geopotential altitude, in feet.
- Example
-
<nwx version="0.3.5"> <Response id="1"> <gph id="wpt01" p="42.5,3.1" z="6000" u="A" e="" q="12"/>6380</gph> <gph id="wpt02" p="43.55,4.01" z="180" u="F" e="" q="11"/>18768</gph> </Response> </nwx>
<qff>
(Request)
– New in version 0.3.2
- Description
- Request atmospheric pressure reduced to mean sea level (using actual density and temperature) at a given position and epoch.
- Attributes
- The following attributes are required:
p
: extended geographic position expressed as latitude,longitude in decimal degrees on the WGS84 datum. Valid range is from -90.0 to 90.0 for latitudes and -180.0 to 180.0 for longitudes. Note that this accepts point lists and ranges as well as single positions. Refer to Extendedp
attribute for more info.e
: epoch for which the data is requested. The epoch should be not earlier than the earliest epoch returned by<AvailableEpochs>
, and no latter than the latest available epoch. If this value does not match exactly one of the forecast epochs an interpolation will be carried out between the two nearest available epochs.
id
: it contains an ID which should uniquely identify this request, in order to facilitate matching requests with their corresponding responses.
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <qff id="wpt01" p="42.5,3.1" e=""/> <qff id="wpt02" p="43.55,4.01" e=""/> </Request> </nwx>
<qff>
(Response)
- Description
- Forecast mean sea level pressure (QFF), in hectopascals (hPa), or equivalently, millibars.
- Attributes
- See the
<qff>
(Request) section above. Any request attributes are copied verbatim to the response in order to faciliate identification.
- Contents
- Forecast mean sea level pressure in hectopascals.
- Example
-
<nwx version="0.3.5"> <Response id="1"> <qff id="wpt01" p="42.5,3.1" e=""/>1008</qff> <qff id="wpt02" p="43.55,4.01" e=""/>1009</qff> </Response> </nwx>
<Geomag>
(Request)
– New in version 0.2.5
- Description
- Calculate the magnetic declination value at a specific position and epoch.
- Attributes
- The following attributes are required:
p
: extended geographic position expressed as latitude,longitude in decimal degrees on the WGS84 datum. Valid range is from -90.0 to 90.0 for latitudes and -180.0 to 180.0 for longitudes.e
: epoch for which to calculate the declination. The epoch should be not earlier than the earliest epoch returned by<AvailableGeomagModels/>
, and no latter than the latest epoch returned by same.model
: Geomagnetic model to use. This value must match the content of the<name>
element in one of the<GeomagModel>
instances returned by<AvailableGeomagModels/>
.
id
: it contains an ID which should uniquely identify the wind request, in order to facilitate matching multiple wind requests with their corresponding responses.
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <Geomag id="wpt01" p="42.5,3.1" e="" model="IGRF-10"/> <Geomag id="wpt02" p="43.55,4.01" e="" model="IGRF-10"/> </Request> </nwx>
<Geomag>
(Response)
- Description
- Declination and secular variation in sexagesimal degrees.
- Attributes
- See the
<Geomag>
(Request) section above. Any request attributes are copied verbatim to the response in order to faciliate identification. - Contents
- Each
<Geomag>
element contains the following two sub-elements:<decl></decl>
: Magnetic declination in sexagesimal degrees (negative: West, positive: East) at mean sea level at the epoch and position requested, according to the model indicated.<ddecl></ddecl>
: Secular variation in degress per year (same sign convention as above) for the position and model indicated.
NAN
(Not a Number) will be returned instead of the declination and secular variation values. - Example
-
<nwx version="0.3.5"> <Response id="1" expires="2009-10-06 18:20:00"> <Geomag id="wpt01" p="42.5,3.1" e="" model="IGRF-10"> <decl>-0.1419</decl> <ddecl>0.1083</ddecl> </Geomag> <Geomag id="wpt02" p="43.55,4.01" e="" model="IGRF-10"> <decl>0.0921</decl> <ddecl>0.11</ddecl> </Geomag> </Response> </nwx>
<terrain>
(Request)
– New in version 0.1
- Description
- Request terrain height information. This is derived from the 3 arc-seconds SRTM data, downsampled to one arc-minute while retaining the highest terrain elevation for each cell, and applying a geoidal correction based on a low-resolution (10 degrees) derivation of EGM96.
- Attributes
- The following attributes are required:
p
: extended geographic position expressed as latitude,longitude in decimal degrees on the WGS84 datum. Valid range is from -90.0 to 90.0 for latitudes and -180.0 to 180.0 for longitudes. Note that this accepts point lists and ranges as well as single positions. Refer to Extendedp
attribute for more info.
id
: it contains an ID which should uniquely identify this request, in order to facilitate matching requests with their corresponding responses.
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <terrain id="wpt01" p="42.5,3.1"/> <terrain id="leg01" p="43.63,1.37:43.65,0.56:20 43.65,0.56:43.4667,-00.0184:20 43.4667,-00.0184:43.37,-0.72:20 43.37,-0.72:43.4683,-01.5311:20 43.4683,-01.5311"/> </Request> </nwx>
<terrain>
(Response)
- Description
- Terrain height in feet for the specified position(s) is returned.
- Attributes
- See the
<terrain>
(Request) section above. Anyid
attribute, if present, is copied in the response. Thep
attribute is expanded to a list and copied in the response. - Contents
- Terrain height, in feet. For certain areas, the SRTM model
is missing height information—A value of
-32768
in the response indicates that no terrain data is available for that location. - Example
-
<nwx version="0.3.5"> <Response id="1"> <terrain id="wpt01" p="42.5000,3.1000">767</terrain> <terrain id="leg01" p="43.6300,1.3700…43.4683,-1.5311"> 416 498 521 593 692 695 521 567 626 649 616 524 544 623 636 620 738 662 662 646 662 823 708 692 705 580 695 633 629 685 721 823 725 646 551 587 698 685 469 656 839 839 810 885 892 925 846 882 764 738 826 816 564 459 738 764 433 321 242 449 613 705 705 698 554 662 511 321 311 331 406 426 449 344 344 275 314 203 278 269 236 59 144 </terrain> </Response> </nwx>
<ProfileGraph>
(Request) – New in version 0.1.1
- Description
- Draw a route's profile view, optionally showing terrain height, the flight path's geopotential altitude, and weather.
- Attributes
- The following attributes can be specified. They are all
optional and if not specified default values will be provided:
width
: output image's width in pixels.height
: output image's height in pixels.xmargin
: margin to leave around the top and bottom sides, in pixels.ymargin
: margin to leave around the left and right sides, in pixels.hmin
: minimum altitude shown at the bottom of the graph, in feet.hmax
: maximum altitude shown at the top of the graph, in feet.hdiv
: number of scale divisions for the altitude.e
: epoch of the flight. If specified, it must be one of the values returned by <AvailableEpochs>. If not specified, the flight path will be shown using barometric altitudes—note that this will not show an accurate terrain clearance, so if at all possible an epoch should always be provided.output
: (New in version 0.2.3) Output method. If specified, it can take one of the values indicated in the out-of-band output section. If not specified, the data will be returned inline.mimetype
: (New in version 0.3.3) Output format. If specified, must be one of the supported output MIME types:image/png
orimage/svg+xml
for v0.3.3, while version 0.3.4 additionally supportsimage/gif
andimage/jpeg
, and version 0.3.5 supportsapplication/x-nwxdata+xml
. It defaults toimage/png
.
- Contents
- The following elements may be specified:
<route>
: Used to define the flight path. It has no attributes and consists of a series of<wpt>
sub-elements. The syntax and semantics for these is exactly the same as for the<Wind>
element, with the one exception that thez
(and correspondingu
) attributes can be omitted, to denote a height of zero feet (i.e., terrain altitude, useful for departure and destination points).
The order of the<wpt>
sub-elements defines the flight route.<terrain/>
: If present, terrain relief below the route's flight path will be drawn. It has no attributes or content.<flightpath/>
: If present, a line representing the route's flight path will be drawn at the appropriate altitude. If a valid epoch has been specified in the<ProfileGraph>
parent element, then this will be a geopotential height—i.e., taking into account forecast atmospheric pressure and density. This element has no attributes or content.<Weather/>
: If present and a valid epoch has been specified in the<ProfileGraph>
parent element, then weather information will be shown in the chart according to the contents of the<theme>
subelements. Presently implemented themes are<theme>frzlvl</theme>
to show the freezing level along the route, and<theme>clouds</theme>
to show a cross-section of cloud base, tops, and density along the route.<colour/>
: Specifies a colour to use for a graphical element. It requires two attributes,element
andvalue
.element
can be one ofbackground
,flightpath
,terrain
, ortext
.value
is an hexadecimal RGB colour triplet of the form 0xttrrggbb, where tt is the alpha channel value (transparency), and rr, gg, bb are the red, green, and blue channels respectively. Each can take a value from0x00
to0xff
, except for the alpha channel which has a range from from0x00
to0x7f
(0 to 127). For example, to obtain a 50% transparent white background you may use<colour element="background" value="0x7fffffff"/>
.
The<colour/>
element may be repeated with a differentelement
value each time.<style/>
: Valid only ifmimetype="image/svg+xml"
. For SVG graphics, the user can modify or replace the default stylesheet. User style can be embedded in the document or linked from external stylesheets, and can use any styling format supported by the SVG standard (and their target implementation).
For inline styles, enter the styling instructions as the element's content, as illustrated in example 2.
Linking external stylesheets is done by providing anhref
attribute in the<style/>
element, pointing to the resource containing the external stylesheet. Please note: external stylesheets are only supported when using one of the out of band output options, as otherwise the<?xml-stylesheet ?>
processing instruction would be lost.
In either case, thetype
attribute must be provided and must indicate the styling language used, as per the SVG standard.
This subelement may be provided multiple times. Each one generates a separate<style/>
or<?xml-stylesheet ?>
element in the resulting SVG document.
If any instance of a<style/>
element contains an attribute with nameaction
and valuereplace
, then the default style is replaced by the user provided styles, otherwise the latter complement the former. Use ofaction="replace"
is recommented when linking external stylesheets, to prevent the built-in style from overriding the external stylesheet's instructions.
Example 1—a simple request with PNG output (see output)-
<nwx version="0.3.5"> <user id="" hash=""/> <Request id="2"> <ProfileGraph width="1000" height="600" hmin="0" hmax="12000" hdiv="5" e=""> <route> <wpt name="LELL" p="41.52090,002.10503"/> <wpt name="" p="41.52090,002.40503" z="6000" u="A"/> <wpt name="GEMAS" p="41.84498,000.73026" z="90" u="F"/> <wpt name="GIROM" p="42.77486,000.99730" z="100" u="F"/> <wpt name="ASPET" p="43.00000,000.97972" z="70" u="F"/> <wpt name="LFBO" p="43.63500,001.36778"/> </route> <terrain/> <Weather> <theme>clouds</theme> <theme>frzlvl</theme> </Weather> <flightpath/> </ProfileGraph> </Request> </nwx>
- Example 2—an SVG request with styles and out of band output (see output as SVG, or the equivalent PNG result.)
-
<nwx version="0.3.5"> <Request id="P1"> <ProfileGraph width="1024" height="600" hmin="0" hmax="18000" hdiv="18" e="" mimetype="image/svg+xml" output="oob"> <route> <wpt id="LFBO" p="43.63513,1.367856"/> <wpt id="TOC1" p="43.88459,1.739923" z="100" u="F"/> <wpt id="GAI2" p="43.95404,1.824175" z="100" u="F"/> <wpt id="CFA3" p="45.78747,3.192194" z="100" u="F"/> <wpt id="MOU4" p="46.70677,3.631678" z="100" u="F"/> <wpt id="RLP5" p="47.9063,5.249167" z="100" u="F"/> <wpt id="EPL6" p="48.31782,6.059403" z="100" u="F"/> <wpt id="GIVOR7" p="48.65861,6.391389" z="100" u="F"/> <wpt id="BOC8" p="49.20649,6.464759" z="100" u="F"/> <wpt id="AKELU9" p="49.36694,6.463889" z="120" u="F"/> <wpt id="SUTAL10" p="49.46667,6.391667" z="120" u="F"/> <wpt id="LIMGO11" p="49.63722,6.281667" z="120" u="F"/> <wpt id="TALUK12" p="50.08861,6.648056" z="120" u="F"/> <wpt id="ULMEN13" p="50.22167,6.875278" z="120" u="F"/> <wpt id="RUDUS14" p="50.0475,8.078333" z="120" u="F"/> <wpt id="TOBAK15" p="50.57167,8.785833" z="120" u="F"/> <wpt id="GISEM16" p="50.63556,8.819444" z="120" u="F"/> <wpt id="WRB17" p="51.50569,9.110914" z="120" u="F"/> <wpt id="HLZ18" p="52.36339,10.79522" z="120" u="F"/> <wpt id="BATEL19" p="52.54694,11.09972" z="120" u="F"/> <wpt id="BKD20" p="53.03452,11.54621" z="120" u="F"/> <wpt id="ARGAD21" p="54.50611,13.49611" z="120" u="F"/> <wpt id="ASDIN22" p="54.65833,13.76861" z="120" u="F"/> <wpt id="DETNI23" p="54.91667,14.34417" z="120" u="F"/> <wpt id="ROE24" p="55.06558,14.75869" z="120" u="F"/> <wpt id="KOLJA25" p="56,16.81467" z="120" u="F"/> <wpt id="EVONA26" p="57.165,19.92472" z="120" u="F"/> <wpt id="LOGNA27" p="57.84306,21.66028" z="120" u="F"/> <wpt id="MASIS28" p="58.65583,23.36917" z="120" u="F"/> <wpt id="SULUN30" p="58.97167,24.06861" z="120" u="F"/> <wpt id="EETN" p="59.41333,24.8325"/> </route> <Weather> <theme>clouds</theme> <theme>frzlvl</theme> </Weather> <flightpath/> <terrain/> <style href="http://navlost.eumedia/profilegraph-default-style.css" type="text/css" action="replace" /> <style type="text/css"><![CDATA[ svg { background: #d2d2d2; } polyline.flightpath { fill: none; stroke: green; stroke-width: 3px; opacity: .6; } ]]></style> </ProfileGraph> </Request> </nwx>
<ProfileGraph>
(Response)
- Description
- An image is returned depicting the requested profile.
- Attributes
- See the
<ProfileGraph>
(Request) section above. All request attributes are copied on the response. - Contents
- In the case of an inline response, one
<data>
element is returned with amimetype
attribute matching that entered in the request, or a default ofimage/png
.
For PNG, the<data>
element contains a CDATA section with the Base64 encoded image.
For SVG, the resulting XML document is embedded as a child of<data>
. See the out of band section for a description of the behaviour and return data of the different out of band options. - Example 1—inband PNG
-
<?xml version="1.0" encoding="UTF-8"?> <nwx version="0.3.5"> <Response id="2" expires="2008-12-31 06:20:00"> <ProfileGraph width="1000" height="600" hmin="0" hmax="12000" hdiv="5" e=""> <data mimetype="image/png"> <![CDATA[iVBORw0KGgoAAAANSUhEUgAAA+gAAAJYCAIAAAB+fFtyAAAgAElEQVR4nO3df2xdd3038FPnl9PE MqwFQZ2maTM1/FipqMSGcD0vAlrEEETzkq3mR6klBKUDJDppoEhUgkX7gwkxpq4wFVergp/GmQu4 haVMjzYryRCqVgHqaJtsNARZQFaKTOLGSdT0+eP0ub6xfX/63nO+33NeLyF08z33pMfJvTfv+76f [....] lbt27VpyIZrMrP6pKvlQX8PPbCuXGb3mmms+8pGPJEnS8Aly2fT0dPeOGAAA6AijMgAAEAHBHQAA IiC4AwBABAR3AACIgOAOAAAR+H/np7a3/1QLhwAAAABJRU5ErkJggg== ]]> </data> </ProfileGraph> </Response> </nwx>
- Example 2—out of band SVG data
-
<?xml version="1.0" encoding="UTF-8"?> <nwx version="0.3.5"> <Response id="Prof1" expires="2010-02-08 00:20:00"> <ProfileGraph width="1024" height="600" hmin="0" hmax="18000" hdiv="18" e="" mimetype="image/svg+xml" output="oob"> <id>urn:uuid:1ccacb7c-1422-11df-bcde-00163e9b2a1e</id> </ProfileGraph> </Response> </nwx>
Note: this would be followed by a GET request on
http://www.navlost.eu/nwxs/oob/urn:uuid:1ccacb7c-1422-11df-bcde-00163e9b2a1e
, as explained elsewhere.
<ProfileGraph/>
response with MIME type application/x-nwxdata+xml
A request with mimetype="application/x-nwxdata+xml"
set generates an NwxData response with the
following characteristics.
Element | Id | Description |
---|---|---|
<value/> | contenttype |
It always has the value profilegraph . |
<value/> | title |
It contains a default title for this profile. Currently this cannot be set as part of the request. |
<tupleList/> | flightpath |
Contains the data for the flightpath, particularly geopotential
altitude. Returned if the <flightpath/> element
was present in the request. |
<tupleList/> | weather |
If any weather or terrain data has been requested, this element
will be present. Its exact contents will depend on which
<theme/> elements have been used. |
|
|
The following fields are always present in <tupleList id="flightpath"/>
:
Field Name | Description |
---|---|
lat | Geodetic latitude, in sexagesimal degrees (WGS84 datum). |
lon | Geodetic longitude, in sexagesimal degrees (WGS84 datum). |
di | Ellipsoidal distance (WGS84 ellipsoid) from the first position, in nautical miles to a precision of one cable (0.1 nm). |
gph | Geopotential altitude in feet. |
The following fields can be present in <tupleList id="weather"/>
:
Field Name | Generated By | Description |
---|---|---|
lat |
Always present | Geodetic latitude, in sexagesimal degrees (WGS84 datum). |
lon |
Always present | Geodetic longitude, in sexagesimal degrees (WGS84 datum). |
cloud:low:bottom |
<theme>clouds</theme> |
Cloud base for low, mid, and high layers, respectively, in geopotential feet. |
cloud:low:top |
<theme>clouds</theme> |
Cloud tops for low, mid, and high layers, respectively, in geopotential feet. |
cloud:low:density |
<theme>clouds</theme> |
Cloud density for low, mid, and high layers, respectively, as a percentage (0-100) |
precip |
<theme>precip</theme> |
Categorical precipitation type. Can be one of null (no precipitation / no data), rain , frzr (freezing rain), or snow . |
frzlvl |
<theme>frzlvl</theme> |
Freezing level (0 °C isotherm), in geopotential feet. |
terrain |
<terrain/> |
Terrain elevation, in feet. |
Example:
<?xml version="1.0"?>
<NwxData xmlns:nwxdata="http://www.navlost.eu/nwxs/doc/help#nwxdata" version="0.0">
<value type="string" id="contenttype">profilegraph</value>
<value type="string" id="title">Weather Profile (2010-04-12 22:54:43Z)</value>
<tupleList fieldtypes="double;double;double;int" fieldnames="lat;lon;di;gph" fs=";"
rs=" " id="flightpath">
43.6351;1.3679;0.0;400
43.8846;1.7399;22.0;9760
43.9540;1.8242;27.6;9758
[....]
58.6558;23.3692;1277.8;12407
58.9717;24.0686;1306.7;12412
59.4133;24.8325;1342.2;75
</tupleList>
<tupleList fieldtypes="double;double;string;int;int;int;int;int;int;int;int;int;int;int"
fieldnames="lat;lon;precip;cloud:low:top;cloud:low:bottom;cloud:low:density;cloud:middle:top;cloud:middle:bottom;cloud:middle:density;cloud:high:top;cloud:high:bottom;cloud:high:density;frzlvl;terrain" fs=";" rs=" " id="weather">
43.6351;1.3679;null;8425;4999;12;18706;15456;3;28152;23202;2;4369;400
43.6658;1.4134;null;8453;5155;12;18595;15428;3;28073;23259;2;4361;331
[....]
59.4091;24.8251;null;145440;145440;0;145440;145440;0;145440;145440;0;0;75
59.4133;24.8325;null;145440;145440;0;145440;145440;0;145440;145440;0;0;75
</tupleList>
</NwxData>
<temp>
(Request)
- Description
- Request temperature information at a specific position and altitude at a given epoch.
- Attributes
- The following attributes are required, unless otherwise noted:
p
: extended geographic position expressed as latitude,longitude in decimal degrees on the WGS84 datum. Valid range is from -90.0 to 90.0 for latitudes and -180.0 to 180.0 for longitudes. Note that this accepts point lists and ranges as well as single positions. Refer to Extendedp
attribute for more info.z
(optional): extended pressure level in hectopascals, or flight level or altitude in feet or metres. This value must correspond to a pressure level at a height not below the highest pressure level in the<AvailableLevels>
list, and at a height not above the lowest pressure level in that list. It does not, however, need to correspond precisely to one of the listed levels—an interpolation will be carried out between the two nearest levels to come up with the resulting temperature.
Leave out this attribute (and the correspondingu
specification) to request the forecast temperature at ground level.u
(optional): designator of the units in which thez
value has been expressed. It must be one of the following: hPa for a pressure level in hectopascals, F for a flight level in hundreds of feet (e.g., F85, F130), A for an altitude in feet (e.g., A4000, A8500), S for a metric flight level (e.g., S30, S50), or M for a metric altitude (e.g., M1500, M6000). If thez
attribute has been omitted, then this can be left out as well (see above).e
: epoch for which the data is requested. The epoch should be not earlier than the earliest epoch returned by<AvailableEpochs>
, and no latter than the latest available epoch. For versions up to and including 0.3.1, it must match precisely one of the values supplied in the<AvailableEpochs>
response—from version 0.3.2 onwards, interpolation between the two nearest available epochs will be carried out as necessary.
id
: it contains an ID which should uniquely identify the request, in order to facilitate matching multiple requests with their corresponding responses.
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <temp id="wpt01" p="42.5,3.1" z="120" u="F" e=""/> <temp id="wpt02" p="43.55,4.01" z="180" u="F" e=""/> </Request> </nwx>
<temp>
(Response)
- Description
- A floating point value representing the temperature in
Celsius at a given location and time. If an extended
p
attribute has been used which expanded to more than one location, a space-separated list of values are returned. - Attributes
- See the
<temp>
(Request) section above. Any request attributes are copied verbatim to the response in order to faciliate identification, except for an extendedp
attribute which will be expanded as necessary. - Contents
- Forecast temperature, in degrees Celsius
- Example
-
<nwx version="0.3.5"> <Response id="1"> <temp id="wpt01" p="42.5,3.1" z="120" u="F" e=""/> 5.1 </temp> <temp id="wpt02" p="43.55,4.01" z="180" u="F" e=""/> -7.5 </temp> </Response> </nwx>
<srss>
(Request)
- Description
- Give sunrise and sunset times at a given position on a given date.
- Attributes
- The following attributes are required, unless otherwise noted:
p
: extended geographic position expressed as latitude,longitude in decimal degrees on the WGS84 datum. Valid range is from -90.0 to 90.0 for latitudes and -180.0 to 180.0 for longitudes. Note that this accepts point lists and ranges as well as single positions. Refer to Extendedp
attribute for more info.e
: epoch for which the data is requested. The epoch should be in the range 1800-01-01 to 2100-01-01 for reasonably accurate results. The calendar used is the Gregorian calendar, extrapolated backward through time.
id
: it contains an ID which should uniquely identify the request, in order to facilitate matching multiple requests with their corresponding responses.
- Contents
- nil
- Example
-
<nwx version="0.3.5"> <Request id="1"> <srss p="48.86,2.35" e="2010-06-10"/> <srss p="69.68,18.94" e="2010-05-17"/> </Request> </nwx>
<srss>
(Response)
- Description
- A number of subelements returning the epochs of official
sunrise and sunset, as well as beginning and end of civil, nautical,
and astronomical twilights.
The epochs are returned to the nearest minute and are theoretically accurate to within about two minutes for mid latitudes. Accuracy degrades nearer to the poles as a result of the shallower elevation of the sun. - Attributes
- See the
<srss>
(Request) section above. Any request attributes are copied verbatim to the response in order to faciliate identification, except for an extendedp
attribute which will be expanded as necessary. - Contents
- The following subelements:
<sr/>
: Contains the epoch of sunrise (sun zenith angle of 90°50'), or one ofdnr
ordns
if the sun does not rise or does not set on this particular date and location.<ss/>
: Contains the epoch of sunset,dnr
ordns
.<bct/>
: Contains the epoch of beginning of civil twilight (sun zenith angle of 96°),dnr
ordns
.<ect/>
: Contains the epoch of end of civil twilight, ordns
.<bnt/>
: Contains the epoch of beginning of nautical twilight (sun zenith angle of 102°),dnr
ordns
.<ent/>
: Contains the epoch of end of nautical twilight,dnr
ordns
.<bat/>
: Contains the epoch of beginning of astronomical twilight (sun zenith angle of 108°),dnr
ordns
.<eat/>
: Contains the epoch of end of astronomical twilight,dnr
ordns
.<st/>
: Contains the epoch of the sun's transit over the observer's location on the given date.
- Example
-
<?xml version="1.0" encoding="UTF-8"?> <nwx version="0.3.5"> <Response id="1"> <srss p="48.8600,2.3500" e="2010-06-10"> <sr>2010-06-10 03:47</sr> <ss>2010-06-10 19:53</ss> <bct>2010-06-10 03:05</bct> <ect>2010-06-10 20:35</ect> <bnt>2010-06-10 02:05</bnt> <ent>2010-06-10 21:35</ent> <bat>2010-06-10 00:05</bat> <eat>2010-06-10 23:35</eat> <st>2010-06-10 11:50</st> </srss> <srss p="69.6800,18.9400" e="2010-05-17"> <sr>2010-05-16 22:46</sr> <ss>2010-05-17 22:35</ss> <bct>dns</bct> <ect>dns</ect> <bnt>dns</bnt> <ent>dns</ent> <bat>dns</bat> <eat>dns</eat> <st>2010-05-17 10:41</st> </srss> </Response> </nwx>
Out-of-Band Data
A notable shortcoming of XML is the difficulty and inefficiency of representing binary data in a document. A common approach is to encode the binary information into an equivalent text representation such as Base64. This however significantly increases the size of the document, and requires unencoding by the client, with the consequent use of resources.
In order to provide a more efficient alternative, certain
requests, such as <Chart>
and <ProfileGraph>
accept an output
attribute which gets around
the aforementioned problems by transmitting the data separately (or
instead of) the XML response: i.e., the data is sent out of band
relative to the XML.
The output
attribute is available on
NWX versions 0.2.3 and above, and currently recognises three possible
values:
output="oob"
Instead of
returning the data inline, the response contents for this item are
replaced by an <id/>
element containing a UUID (Universally Unique ID). The client can then
retrieve the content by making an immediate GET request to
http://navlost.eu/nwxs/oob/response-uuid
,
where response-uuid
is the content of the <id/>
element.
Example request:
<nwx version="0.3.5">
<Request id="1">
<Chart id="c01" x="800" y="600" z="700" e="" lat0="30" lat1="65" lon0="-20" lon1="35" output="oob">
<theme>prmslmsl</theme>
<theme>wind</theme>
</Chart>
</Request>
</nwx>
Response:
<nwx version="0.3.5">
<Response id="1">
<Chart id="c01" x="800" y="600" z="700" e="" lat0="30" lat1="65" lon0="-20" lon1="35" output="oob">
<expires>2008-10-09 00:20:00</expires>
<id>urn:uuid:47231b88-b1ec-11de-b1bb-00163e9b2a1e</id>
</Chart>
</Response>
</nwx>
Upon receiving this response, the client should perform a GET
request on http://navlost.eu/nwxs/oob/urn:uuid:47231b88-b1ec-11de-b1bb-00163e9b2a1e
within the next 10 minutes. After that time has elapsed, the UUID will
expire and the data will become unavailable, necessitating a new
request.
output="multipart/mixed"
A disadvantage of the OOB option is that the client has to
place a
second request to retrieve the data, with the consequent overhead.
Instead, a client may choose to request a multipart response. In such a
response, the data will be MIME encoded as a multipart document, with
the XML part of the response as the first part, and each out-of-band
payload in a different section. In this case, the different parts can
be associated to their corresponding requests by the presence of
a Content-ID
header with its value
matching the content of the <id/>
element in the corresponding response.
output="redirect"
This third option is provided since 0.2.5, and is a simpler alternative to the relative difficulty of handling MIME multipart responses, while still avoiding the need of a second request. If this option is used, the server will reply with an HTTP 303 redirection towards the binary content of the response.
An obvious limitation of this approach is that the client's
XML cannot contain any requests other than the one with the
element with the output="redirect"
attribute, as any previous responses will be lost, and processing stops
at the element in question.
The NwxData Generic Response Format
NwxData is a simple XML-based format to return arbitrary numeric or alphanumeric data from an NWX request.
Responses in this format can represent key/value pairs, and
key/tupleset pairs (a tupleset being a list of
tuples, or key/value pairs), and are identified by a MIME type
of application/x-nwxdata+xml
.
The root element of an NwxData document is <NwxData/>
.
It contains a version
attribute identifying the version of the
NwxData specification it complies with.
An NwxData document may contain any number of instances of the subelements
<value/>
, and <tupleList/>
.
<value/>
Element
- Description
- Defines a single value of the type indicated by its
type
attribute - Attributes
-
Attribute Definition id
Uniquely identifies this particular element in this <NwxData/>
document.type
Indicates the storage type of the element contents, which can be one of int
,double
, orstring
. - Contents
- The value of the expression.
- Example
Can be understood as defining a floating point variable pi=3.1416.<value type="double" id="pi">3.1416</value>
<tupleList/>
Element
- Description
- This element returns a list of tuples, or in other words, a table of values where each column represents an attribute and each row an instance.
- Attributes
-
Its attributes are:
Attribute Definition id
Uniquely identifies this particular element within <ProfileGraphData/>
fs
Contains the string used to separate the different values in a tuple. rs
Contains the string used to separate the different tuples. fieldtypes
An fs
-separated list indicating the type of each element in a tuple. Possible values are as for the<value/>
element.fieldnames
An fs
-separated list of names for each element in a tuple. - Contents
- The contents of this element are
rs
-separated tuples offs
-separated elements. - Example
-
<tupleList fieldtypes="double;double;double;int" fieldnames="lat;lon;di;gph" fs=";" rs=" " id="flightpath"> 43.6351;1.3679;0.0;400 43.8846;1.7399;22.0;9769 43.9540;1.8242;27.6;9768 [....] 58.6558;23.3692;1277.8;12408 58.9717;24.0686;1306.7;12409 59.4133;24.8325;1342.2;75 </tupleList>
Attributes
p
– (Request/Response)
– New in v0.1
This attribute expresses one or multiple geographical positions. Positions are always expressed as latitude, longitude in decimal degrees in the WGS84 datum. In version 0.1, this attribute can take the following forms:
- Single position:
- Format
lat,lon
where lat is any floating point number between -90 and 90, and lon is any floating point number between -180 and 180, both inclusive.- Example
42.5,3.1
- Result
- This expresses the position at 42.5 degrees of latitude North, 3.1 degrees of longitude East.
- Position sequence:
- Format
lat0,lon0:lat1,lon1:div
wherelat
andlon
are as above, anddiv
is the number of divisions. The distance between the first and the second point is divided indiv
divisions, andlat
-1 points are generated, including the first point but excluding the last.- Example
40.0,3.0:45.0,8.0:5
- Result
40.0000,3.0000 41.0172,3.9380 42.0264,4.9052 43.0270,5.9033 44.0184,6.9343
— note that the distance on the ellipsoid between any two consecutive points is the same. Note also how the endpoint is not included.
- Position list:
- Format (simple)
lat0,lon0 lat1,lon1 ...latn,lonn
wherelat
andlon
are as above, and points are separated from each other by whitespace. This simply outputs each point in the sequence.- Example
40.0,3.0 41.5,3.0 42.0,3.5
- Result
40.0,3.0 41.5,3.0 42.0,3.5
- Format (advanced)
posspec0 posspec1 ...posspecn
whereposspec
is either a single position or a position sequence specification as described above. Each item is expanded until a sequence consisting solely of single position values is obtained.- Example
43.63,1.37:43.65,0.56:20 43.65,0.56:43.4667,-00.0184:20 43.4667,-00.0184:43.37,-0.72:20 43.37,-0.72:43.4683,-01.5311:20 43.4683,-01.5311
— this samples the route LFBO AUCHE TAN ORTEZ LFBZ- Result
43.6300,1.3700 43.6311,1.3295 43.6323,1.2890 43.6334,1.2485 43.6345,1.2080 43.6355,1.1676 43.6366,1.1271 43.6377,1.0866 43.6387,1.0461 43.6397,1.0056 43.6407,0.9651 43.6417,0.9246 43.6427,0.8841 43.6437,0.8436 43.6446,0.8031 43.6455,0.7625 43.6465,0.7220 43.6474,0.6815 43.6483,0.6410 43.6491,0.6005 43.6500,0.5600 43.6409,0.5310 43.6318,0.5020 43.6227,0.4730 43.6136,0.4440 43.6045,0.4151 43.5953,0.3861 43.5862,0.3572 43.5770,0.3282 43.5679,0.2993 43.5587,0.2704 43.5495,0.2414 43.5404,0.2125 43.5312,0.1836 43.5220,0.1548 43.5128,0.1259 43.5036,0.0970 43.4944,0.0681 43.4852,0.0393 43.4759,0.0104 43.4667,-0.0184 43.4667,-0.0184 43.4620,-0.0535 43.4572,-0.0887 43.4525,-0.1238 43.4477,-0.1589 43.4429,-0.1940 43.4381,-0.2291 43.4333,-0.2642 43.4285,-0.2993 43.4237,-0.3344 43.4189,-0.3695 43.4140,-0.4046 43.4092,-0.4396 43.4043,-0.4747 43.3995,-0.5098 43.3946,-0.5448 43.3897,-0.5799 43.3848,-0.6149 43.3799,-0.6499 43.3749,-0.6850 43.3700,-0.7200 43.3700,-0.7200 43.3751,-0.7605 43.3801,-0.8010 43.3851,-0.8415 43.3901,-0.8820 43.3951,-0.9225 43.4001,-0.9631 43.4051,-1.0036 43.4100,-1.0441 43.4149,-1.0847 43.4199,-1.1252 43.4248,-1.1658 43.4297,-1.2063 43.4345,-1.2469 43.4394,-1.2875 43.4443,-1.3281 43.4491,-1.3687 43.4539,-1.4093 43.4587,-1.4499 43.4635,-1.4905 43.4683,-1.5311
z
– (Request/Response)
– New in v0.3.5
This attribute expresses one or multiple positions in the
vertical axis. Positions are expressed as a scalar in the units
specified in the related u
attribute. It can
take the following forms:
- Single position:
- Format
z
where z is any numeric value valid in the context in which it is being used.- Example
10500
- Result
- This expresses a scalar value of 10500 units (the
type of which will normally be specified via
u
).
- Position sequence:
- Format
z0:z1:div
wherez0
is the start point of the sequence,z1
is the end point, anddiv
is the number of divisions. The distance between the first and the second point is divided indiv
divisions, andzn-1
points are generated, including the first point but excluding the last.- Example
300:150:3
- Result
300 250 200
— note how the endpoint is not included.
- Position list:
- Format (simple)
z0 z1 ...zn
wherez
is a numeric scalar, and values are separated from each other by whitespace. This simply outputs each value in the sequence.- Example
364 3243 4781 6394 9882 13800 18289
- Result
364 3243 4781 6394 9882 13800 18289
- Format (advanced)
posspec0 posspec1 ...posspecn
whereposspec
is either a single value or a sequence specification as described above. Each item is expanded until a sequence consisting solely of single scalar values is obtained.- Example
300:150:3 150 125 100:40:3 40
- Result
300 250 200 150 125 100 80 60 40
Version Notes
New in v0.3.5
- Implemented the NwxData generic response format.
- New
mimetype="x-nwxdata+xml"
output format supported by the <ProfileGraph/> request. - Heavier caching for <ProfileGraph/> requests. Avoids generating duplicate profiles when the same data is requested more than once.
- Implemented the
z
extended attribute. - Now all requests, except
<Metar/>
and<Taf/>
accept extended geographic positions and where applicable, the extendedz
attribute. - Implemented the
u
attribute for <AvailableLevels/> requests. - Introduced per-request load limiting caps for <ProfileGraph/> and <Chart/> requests.
New in v0.3.4
- New <Attributes/> container element.
- GIF and JPEG image output formats supported by the <ProfileGraph/> request.
New in v0.3.3
- New <srss/> request, giving the time of sunrise and sunset.
- Added
<theme>route</theme>
to <Chart/> request. - Improved performance of <ProfileGraph/> request, new option to produce SVG graphics with custom styling, and improved performance of subsequent requests on a route the same as or similar to a previously calculated one, by caching route data.
New in v0.3.2
- New <qff/> request, for mean sea level pressure.
- Improved performance of <temp/> request, added option to return ground level temperature.
New in v0.3.0
- New backend, giving more epochs and better availability.
- New
<theme>dvsi</theme>
theme in the <Chart/> request. - Removed
<href></href>
from the <Chart/> request. Replaced by the newoutput
attribute. - New optional
attr
attribute in the <AvailableEpochs/> request.
New in v0.2.5
- New
<AvailableGeomagModels/>
and<Geomag/>
requests, giving access to the server's database of geomagnetic models. - New
redirect
option added for out of band output.
New in v0.2.4
- New
xmargin
andymargin
attributes added to<ProfileGraph>
. - Various backend improvements.
New in v0.2.3
- The
<ProfileGraph>
request now can include weather information (cloud profiles and freezing level) - New
output
attribute added to certain requests (<Chart>
and<ProfileGraph>
), which instructs the server to return the data either out of band or in-band as a MIME multipart message (more info to follow, or contact me for details) - New
<Notice>
response element to notify clients of important system information, such as scheduled maintenance.
New in v0.2.1
- For METAR and TAF requests which include an
icao
attribute, return a warning if the specified ICAO identifier is not found in the server's database. Prior to this, an empty response was being returned.
New in v0.2
- Altitudes (
z
andu
attribute pairs) can now be expressed in hectoPascals for for all elements taking altitude information. Useu="hPa"
oru="mb"
to indicate that the value ofz
is an atmospheric pressure level.
New in v0.1.1
- Added
ProfileGraph
request (see description)
New in v0.1
- Added extended
p
attribute (see description) - Added
terrain
request (see description)