Projects/Plasma/Weather/Ions: Difference between revisions

From KDE TechBase
(Update to follow the current spec, add mentions about WeatherFormula::Unit, add 'list' request)
m (Text replace - "<code>" to "<syntaxhighlight lang="text">")
 
(11 intermediate revisions by 4 users not shown)
Line 2: Line 2:
This page describes the general naming specification and other information regarding to the Ions. All the data may not be used by the applet(s). If you are going to write an applet or an Ion you should follow this specification to make all parts compatible with each other.
This page describes the general naming specification and other information regarding to the Ions. All the data may not be used by the applet(s). If you are going to write an applet or an Ion you should follow this specification to make all parts compatible with each other.


For providing the weather units use WeatherFormula::Unit so that the applet can easily convert between the units by the user's preference. See plasma/weather/formulas.h for the enum of supported formats, which currently includes the following units:
For providing the weather units use WeatherUtils::Unit (which can be used by including Plasma/Weather/WeatherUtils) so that the applet can easily convert between the units by the user's preference. See plasma/weather/weatherutils.h for the enum of supported formats, which currently includes the following units:
* Celsius
* Celsius
* Fahrenheit
* Fahrenheit
Line 24: Line 24:
The updateIonSource(const QString& source) of the Ion should answer to two requests, ''validate'' and ''weather''. In case there is reasonable number of available sources, the ion can provide also ''list'' call.
The updateIonSource(const QString& source) of the Ion should answer to two requests, ''validate'' and ''weather''. In case there is reasonable number of available sources, the ion can provide also ''list'' call.


The format of the request is like this: <code>[name of the ion]|[request]|[parameters]</code>
The format of the request is like this: <syntaxhighlight lang="text">[name of the ion]|[request]|[parameters]</syntaxhighlight>


When adding the source in the settings dialog of the applet, it will request validation from the Ion. When the Ion has been added, the applet will request for weather information by issuing ''weather'' request when it wants to get weather data. See the following chapters for information regarding to these requests.
When adding the source in the settings dialog of the applet, it will request validation from the Ion. When the Ion has been added, the applet will request for weather information by issuing ''weather'' request when it wants to get weather data. See the following chapters for information regarding to these requests.
Line 33: Line 33:


Request looks always like this:
Request looks always like this:
<code>[name of the ion]|list</code>
<syntaxhighlight lang="text">[name of the ion]|list</syntaxhighlight>
 
The answer to that request should be in the same format as to the validation request (see the next chapter).


=== Answering to validation request ===
=== Answering to validation request ===


<ocde>[name of the ion]|validate|[place name]</code>
<syntaxhighlight lang="text">[name of the ion]|validate|[place name]</syntaxhighlight>


The answers for ''validate'' request differ depending the results of the query:
The answers for ''validate'' request differ depending the results of the query:
Line 43: Line 45:
When the validation is requested, the engine should validate the given place and set the data depending on what happened:
When the validation is requested, the engine should validate the given place and set the data depending on what happened:
* When only one valid place for the request is found, the ion should provide  
* When only one valid place for the request is found, the ion should provide  
<code>[ionname]|valid|single|place|[place name]</code>  
<syntaxhighlight lang="text">[ionname]|valid|single|place|[place name]</syntaxhighlight>  
set as the value of ''validate'' key of the source.
set as the value of ''validate'' key of the source.


* When multiple possible places are found, the ion should provide
* When multiple possible places are found, the ion should provide
<code>[ionname]|valid|multiple|place|[place name]|place|[place name]</code>
<syntaxhighlight lang="text">[ionname]|valid|multiple|place|[place name]|place|[place name]</syntaxhighlight>
set as the value  of ''validate'' key of the source. The places are separated with ''''|place|''''.
set as the value  of ''validate'' key of the source. The places are separated with ''''|place|''''.


* When no valid sources are found, the ion should provide  
* When no valid sources are found, the ion should provide  
<code>[ionname]|invalid|single|[place]</code>
<syntaxhighlight lang="text">[ionname]|invalid|single|[place]</syntaxhighlight>
set as the value of the ''validate'' key of the source.
set as the value of the ''validate'' key of the source.


Line 59: Line 61:


The request looks always like this:
The request looks always like this:
<code>[name of the ion]|weather|[place]</code>
<syntaxhighlight lang="text">[name of the ion]|weather|[place]</syntaxhighlight>
and the ion should provide the weather data in format which follows the naming scheme found below.
and the ion should provide the weather data in format which follows the naming scheme found below.


Line 95: Line 97:
! Key !! Value type !! Description
! Key !! Value type !! Description
|-
|-
| Temperature || WeatherFormula::Unit || Temperature observed
| Temperature || WeatherUtils::Unit || Temperature observed
|-
| Temperature Unit || C,F,K || The format of the temperature is in
|-
| Windchill || int || Wind chill || the "feels like" temperature when windy and cold, use Temperature Unit for conversion
|-
|-
| Temperature Unit || C,F || The format of the temperature is in
| Humidex || int || Humidex || the "feels like" temperature when humid,  use Temperature Unit for conversion
|}
|}


Line 109: Line 115:
| Wind Speed || int || Speed of the wind
| Wind Speed || int || Speed of the wind
|-
|-
| Wind Speed Unit || WeatherFormula::Unit || The format of the wind speed
| Wind Speed Unit || WeatherUtils::Unit || The format of the wind speed
|-
|-
| Wind Gust || int || Wind gust
| Wind Gust || int || Wind gust
|-
|-
| Wind Gust Unit || WeatherFormula::Unit || The format of the wind gust
| Wind Gust Unit || WeatherUtils::Unit || The format of the wind gust
|-
| Windchill || int || Wind chill
|-
| Windchill Unit || WeatherFormula::Unit || The format of the wind chill
|-
| Humidex || int || Humidex
|}
|}


Line 131: Line 131:
| Dewpoint || int || Dewpoint
| Dewpoint || int || Dewpoint
|-
|-
| Dewpoint Unit || WeatherFormula::Unit || The format of the dewpoint
| Dewpoint Unit || WeatherUtils::Unit || The format of the dewpoint
|-
|-
| Pressure || int || Air pressure
| Pressure || int || Air pressure
|-
|-
| Pressure Unit || WeatherFormula::Unit || The format of the air pressure
| Pressure Unit || WeatherUtils::Unit || The format of the air pressure
|-
|-
| Pressure Tendency || string || Tendency of the pressure
| Pressure Tendency || string || Tendency of the pressure
|-
|-
| Visibility || int || Visibility
| Visibility || int or string || Visibility (if string the unit is ignored)
|-
|-
| Visibility Unit || WeatherFormula::Unit || Visibility unit
| Visibility Unit || WeatherUtils::Unit || Visibility unit
|}
|}


Line 173: Line 173:
| Record Rainfall || int || The rainfall record for the day
| Record Rainfall || int || The rainfall record for the day
|-
|-
| Record Rainfall Unit || WeatherFormula::Unit || The format of rainfall
| Record Rainfall Unit || WeatherUtils::Unit || The format of rainfall
|-
|-
| Record Snowfall || int || The snowfall record for the day
| Record Snowfall || int || The snowfall record for the day
|-
|-
| Record Snowfall Unit || WeatherFormula::Unit|| The format of the snowfall
| Record Snowfall Unit || WeatherUtils::Unit|| The format of the snowfall
|}
|}


Line 185: Line 185:
! Key !! Value type !! Description
! Key !! Value type !! Description
|-
|-
| Long Forecast Day <something?> || ? || The forecast for up to eight days
| Total Weather Days || int || The total number of forecast days available
|-
| Long Forecast Day <#N> (not used) || string || The forecast for a specific day/period
|-
| Short Forecast Day <#N> || string || The forecast for a specific day/period.
 
Format: <syntaxhighlight lang="text">period|icon|weather summary|\
temp (high)|temp (low)|probability</syntaxhighlight>
Items that are not used should be set to "N/U".
|}
 
=== Weather warning related data ===
{| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
|- style="background: #ececec; white-space:nowrap;"
! Key !! Value type !! Description
|-
| Total Warnings Issued || int || The total number of warnings issued
|-
| Warning Priority <#N> (not used) || string || severity of the warning
|-
| Warning Description <#N> || string || Brief warning description
|-
| Warning Info <#N> || string || URL location for warning information
|-
| Warning Timestamp <#N> (not used) || date || Time when warning was issued
|}
 
=== Weather watch related data ===
{| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
|- style="background: #ececec; white-space:nowrap;"
! Key !! Value type !! Description
|-
| Total Watches Issued || int || The total number of watches issued
|-
| Watch Priority <#N> (not used) || string || severity of the watch
|-
| Watch Description <#N> || string || Brief watch description
|-
| Watch Info <#N> || string || URL location for watch information
|-
|-
| Short Forecast Day <something> || ? || The forecast for up to five days
| Watch Timestamp <#N> (not used) || date || Time when watch was issued
|}
|}

Latest revision as of 20:49, 29 June 2011

Introduction

This page describes the general naming specification and other information regarding to the Ions. All the data may not be used by the applet(s). If you are going to write an applet or an Ion you should follow this specification to make all parts compatible with each other.

For providing the weather units use WeatherUtils::Unit (which can be used by including Plasma/Weather/WeatherUtils) so that the applet can easily convert between the units by the user's preference. See plasma/weather/weatherutils.h for the enum of supported formats, which currently includes the following units:

  • Celsius
  • Fahrenheit
  • Kelvin
  • Kilometers
  • MetersPerSecond
  • Miles
  • Kilopascals
  • InchesHG
  • Millibars
  • Hectopascals
  • Centimeters
  • Millimeters
  • Inches
  • Knots
  • Beaufort

The conversions between related units can be done between them on the applet's side.

Applet requests

The updateIonSource(const QString& source) of the Ion should answer to two requests, validate and weather. In case there is reasonable number of available sources, the ion can provide also list call.

The format of the request is like this: 

[name of the ion]|[request]|[parameters]

When adding the source in the settings dialog of the applet, it will request validation from the Ion. When the Ion has been added, the applet will request for weather information by issuing weather request when it wants to get weather data. See the following chapters for information regarding to these requests.

Providing a source list

Ions with reasonable number of sources may want to provide a list of them directly to the user. This can be used in configure dialogs to provide an easy access for them afterwards.

Request looks always like this: 

[name of the ion]|list

The answer to that request should be in the same format as to the validation request (see the next chapter).

Answering to validation request

[name of the ion]|validate|[place name]

The answers for validate request differ depending the results of the query:

When the validation is requested, the engine should validate the given place and set the data depending on what happened:

  • When only one valid place for the request is found, the ion should provide
[ionname]|valid|single|place|[place name]

set as the value of validate key of the source.

  • When multiple possible places are found, the ion should provide
[ionname]|valid|multiple|place|[place name]|place|[place name]

set as the value of validate key of the source. The places are separated with '|place|'.

  • When no valid sources are found, the ion should provide
[ionname]|invalid|single|[place]

set as the value of the validate key of the source.

Answering to the weather information request

When the weather request is made the Ion should set the appropriate data for the requested source.

The request looks always like this: 

[name of the ion]|weather|[place]

and the ion should provide the weather data in format which follows the naming scheme found below.

Naming scheme

Location data

Key Value type Description
Credit string The credit for the data provider
Country string The country where the weather station is located
Place string City, territory and perhaps other information where the weather station is located
Region string Region where the weather station is located
Station string Name of the station

Observation data

Key Value type Description
Observation Period date How often the weather status is updated
Current Conditions conditions Current weather conditions

Temperature fields

Key Value type Description
Temperature WeatherUtils::Unit Temperature observed
Temperature Unit C,F,K The format of the temperature is in
Windchill int Wind chill the "feels like" temperature when windy and cold, use Temperature Unit for conversion
Humidex int Humidex the "feels like" temperature when humid, use Temperature Unit for conversion

Wind data

Key Value type Description
Wind Direction string Direction of the wind in degrees or as a cardinal
Wind Speed int Speed of the wind
Wind Speed Unit WeatherUtils::Unit The format of the wind speed
Wind Gust int Wind gust
Wind Gust Unit WeatherUtils::Unit The format of the wind gust

Air conditions

Key Value type Description
Humidity int Humidity in percents
Dewpoint int Dewpoint
Dewpoint Unit WeatherUtils::Unit The format of the dewpoint
Pressure int Air pressure
Pressure Unit WeatherUtils::Unit The format of the air pressure
Pressure Tendency string Tendency of the pressure
Visibility int or string Visibility (if string the unit is ignored)
Visibility Unit WeatherUtils::Unit Visibility unit

Sun/moon related data

Key Value type Description
Sunrise At time When the sun rises
Sunset At time When the sunset happens
Moonrise At time When the moon rises
Moonset At time When the moonset happens
UV Index int Ultraviolet index as integer
UV Rating string Ultraviolet rating in text

Records related data

Key Value type Description
Record High Temperature int The temperature record for the day
Record Low Temperature int The low temperature record for the day
Record Rainfall int The rainfall record for the day
Record Rainfall Unit WeatherUtils::Unit The format of rainfall
Record Snowfall int The snowfall record for the day
Record Snowfall Unit WeatherUtils::Unit The format of the snowfall

Forecast related data

Key Value type Description
Total Weather Days int The total number of forecast days available
Long Forecast Day <#N> (not used) string The forecast for a specific day/period
Short Forecast Day <#N> string The forecast for a specific day/period. Format: 
period|icon|weather summary|\ 
temp (high)|temp (low)|probability

Items that are not used should be set to "N/U".

Weather warning related data

Key Value type Description
Total Warnings Issued int The total number of warnings issued
Warning Priority <#N> (not used) string severity of the warning
Warning Description <#N> string Brief warning description
Warning Info <#N> string URL location for warning information
Warning Timestamp <#N> (not used) date Time when warning was issued

Weather watch related data

Key Value type Description
Total Watches Issued int The total number of watches issued
Watch Priority <#N> (not used) string severity of the watch
Watch Description <#N> string Brief watch description
Watch Info <#N> string URL location for watch information
Watch Timestamp <#N> (not used) date Time when watch was issued
Retrieved from "https://techbase.kde.org/index.php?title=Projects/Plasma/Weather/Ions&oldid=60409"