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