Projects/Plasma/Weather/Ions

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]</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.

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</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

[name of the ion]|validate|[place name]</syntaxhighlight>

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]</syntaxhighlight> 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]</syntaxhighlight> 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]</syntaxhighlight> 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]</syntaxhighlight> 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</syntaxhighlight> 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