# Weather Module

This module is aimed to be the replacement for the current currentweather and weatherforcast modules. The module will be configurable to be used as a current weather view, or to show the forecast. This way the module can be used twice to fullfil both purposes.

The biggest change is the use of weather providers. This way we are not bound to one API source. And users can choose which API they want to use as their source.

The module is in a very early stage, and needs a lot of work. It's API isn't set in stone, so keep that in mind when you want to contribute.

# Example

Screenshot of current weather Screenshot of forecast

# Usage

To use this module, add it to the modules array in the config/config.js file:

modules: [
	{
		module: "weather",
		position: "top_right",
		config: {
			// See 'Configuration options' for more information.
			type: 'current'
		}
	}
]

# Configuration options

The following properties can be configured:

# General options

Option Description
weatherProvider Which weather provider should be used.

Possible values: openweathermap , darksky , weathergov or ukmetoffice
Default value: openweathermap
type Which type of weather data should be displayed.

Possible values: current or forecast
Default value: current
units What units to use. Specified by config.js

Possible values: config.units = Specified by config.js, default = Kelvin, metric = Celsius, imperial = Fahrenheit
Default value: config.units
tempUnits What units to use for temperature. If specified overrides units setting. Specified by config.js

Possible values: config.units = Specified by config.js, default = Kelvin, metric = Celsius, imperial = Fahrenheit
Default value: units
windUnits What units to use for wind speed. If specified overrides units setting. Specified by config.js

Possible values: config.units = Specified by config.js, default = Kelvin, metric = Celsius, imperial = Fahrenheit
Default value: units
roundTemp Round temperature value to nearest integer.

Possible values: true (round to integer) or false (display exact value with decimal point)
Default value: false
degreeLabel Show the degree label for your chosen units (Metric = C, Imperial = F, Kelvin = K).

Possible values: true or false
Default value: false
updateInterval How often does the content needs to be fetched? (Milliseconds)

Possible values: 1000 - 86400000
Default value: 600000 (10 minutes)
animationSpeed Speed of the update animation. (Milliseconds)

Possible values: 0 - 5000
Default value: 1000 (1 second)
timeFormat Use 12 or 24 hour format.

Possible values: 12 or 24
Default value: uses value of config.timeFormat
showPeriod Show the period (am/pm) with 12 hour format

Possible values: true or false
Default value: true
showPeriodUpper Show the period (AM/PM) with 12 hour format as uppercase

Possible values: true or false
Default value: false
lang The language of the days.

Possible values: en, nl, ru, etc ...
Default value: uses value of config.language
decimalSymbol The decimal symbol to use.

Possible values: ., , or any other symbol.
Default value: .
initialLoadDelay The initial delay before loading. If you have multiple modules that use the same API key, you might want to delay one of the requests. (Milliseconds)

Possible values: 1000 - 5000
Default value: 0
appendLocationNameToHeader If set to true, the returned location name will be appended to the header of the module, if the header is enabled. This is mainly interesting when using calender based weather.

Default value: true
calendarClass The class for the calender module to base the event based weather information on.

Default value: 'calendar'

# Current weather options

Option Description
onlyTemp Show only current Temperature and weather icon without windspeed, sunset, sunrise time and feels like.

Possible values: true or false
Default value: false
useBeaufort Pick between using the Beaufort scale for wind speed or using the default units.

Possible values: true or false
Default value: true
showWindDirection Show the wind direction next to the wind speed.

Possible values: true or false
Default value: true
showWindDirectionAsArrow Show the wind direction as an arrow instead of abbreviation

Possible values: true or false
Default value: false
showHumidity Show the current humidity

Possible values: true or false
Default value: false
showIndoorTemperature If you have another module that emits the INDOOR_TEMPERATURE notification, the indoor temperature will be displayed
Default value: false
showIndoorHumidity If you have another module that emits the INDOOR_HUMIDITY notification, the indoor humidity will be displayed
Default value: false
showFeelsLike Shows the Feels like temperature weather.

Possible values: true or false
Default value: true
showSun Shows Sunrise and Sunset time.

Possible values: true or false
Default value: true

# Weather forecast options

Option Description
tableClass The class for the forecast table.

Default value: 'small'
colored If set to true, the min and max temperature are color coded.

Default value: false
showPrecipitationAmount Show the amount of rain/snow in the forecast

Possible values: true or false
Default value: false
fade Fade the future events to black. (Gradient)

Possible values: true or false
Default value: true
fadePoint Where to start fade?

Possible values: 0 (top of the list) - 1 (bottom of list)
Default value: 0.25
maxNumberOfDays How many days of forecast to return. Specified by config.js

Possible values: 1 - 16
Default value: 5 (5 days)
This value is optional. By default the weatherforecast module will return 5 days.

# Openweathermap options

Option Description
apiVersion The OpenWeatherMap API version to use.

Default value: 2.5
apiBase The OpenWeatherMap base URL.

Default value: 'http://api.openweathermap.org/data/'
weatherEndpoint The OpenWeatherMap API endPoint.

Possible values: /weather, /forecast (free users) or /forecast/daily (paying users or old apiKey only)
Default value: '/weather'
locationID Location ID from OpenWeatherMap This will override anything you put in location.
Leave blank if you want to use location.
Example: 1234567
Default value: false

Note: When the location and locationID are both not set, the location will be based on the information provided by the calendar module. The first upcoming event with location data will be used.
location The location used for weather information.

Example: 'Amsterdam,Netherlands'
Default value: false

Note: When the location and locationID are both not set, the location will be based on the information provided by the calendar module. The first upcoming event with location data will be used.
apiKey The OpenWeatherMap API key, which can be obtained by creating an OpenWeatherMap account.

This value is REQUIRED

# Darksky options

Option Description
apiBase The DarkSky base URL. The darksky api has disabled cors, therefore a proxy is required.

Possible value: 'https://cors-anywhere.herokuapp.com/https://api.darksky.net'
This value is REQUIRED
weatherEndpoint The DarkSky API endPoint.

Possible values: /forecast
This value is REQUIRED
apiKey The DarkSky API key, which can be obtained by creating an DarkSky account.

This value is REQUIRED
lat The geo coordinate latitude.

This value is REQUIRED
lon The geo coordinate longitude.

This value is REQUIRED

# Weather.gov options

Option Description
apiBase The weather.gov base URL.

Possible value: 'https://api.weather.gov/points/'
This value is REQUIRED
weatherEndpoint The weather.gov API endPoint.

Possible values: /forecast for forecast and /forecast/hourly for current.
This value is REQUIRED
lat The geo coordinate latitude.

This value is REQUIRED
lon The geo coordinate longitude.

This value is REQUIRED

# UK Met Office options

Option Description
apiBase The UKMO base URL.

Possible value: 'http://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/json/'
This value is REQUIRED
locationID The UKMO API location code.

Possible values: 322942
This value is REQUIRED
apiKey The UK Met Office API key, which can be obtained by creating an UKMO Datapoint account.

This value is REQUIRED

# UK Met Office (DataHub) options

Option Description
apiBase The UKMO DataHub base URL.

Possible value: 'https://api-metoffice.apiconnect.ibmcloud.com/metoffice/production/v0/forecasts/point/'
This value is REQUIRED
apiKey Your API key. See the Getting Started guide on the Met Office website for creating a new account.
This value is REQUIRED
apiSecret Your API secret (see above).
This value is REQUIRED
lat The latitude coordinate for the desired location.

Possible value: 50.7271915
This value is REQUIRED
lon The longitude coordinate for the descired location.

Possible value: -3.4776089
This value is REQUIRED
windUnits Set the units for wind speed. If not specified, uses the units value from config.js. This option is useful for those in the UK, for example, where we use metric units but have wind speed in mph.

Possible values: mps = metres per second, kmh or metric = kilometres per hour, mph or imperial = miles per hour

# API Provider Development

If you want to add another API provider checkout the Guide.