MagicMirror² DocsMagicMirror² Docs
Donate
Discord
Forum
GitHub
Donate
Discord
Forum
GitHub
  • Getting Started

    • Introduction
    • Requirements
    • Installation & Usage
    • Upgrade Guide
  • Configuration

    • Introduction
    • Autostart your MagicMirror²
    • Raspberry Specific
  • Modules

    • Introduction
    • Module Configuration
    • Default Modules

      • Alert
      • Calendar
      • Clock
      • Compliments
      • Hello World
      • News Feed
      • Update Notification
      • Weather Module
    • Animation Guide
  • Module Development

    • Introduction
    • The Core module file
    • The Node Helper
    • MagicMirror Helper Methods
    • Logger
    • Notifications
    • Weather Module Weather Provider Development
    • How to write good documentation
  • About

    • MagicMirror² Manifesto
    • Contributing Guidelines
    • Donate
    • Support
    • License

Weather Module

This 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 fulfill 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.

Screenshot

Current weather:

Screenshot of current weather

Forecast:

Screenshot of weather 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

OptionDescription
weatherProviderWhich weather provider should be used.

Possible values: openweathermap , pirateweather , weathergov, ukmetofficedatahub, ukmetoffice, weatherbit, envcanada, openmeteo, weatherflow, SMHI or yr
Default value: openweathermap
typeWhich type of weather data should be displayed.

Possible values: current , hourly , daily , or forecast
Default value: current

Note: The daily type is another name for the forecast type, and the two are interchangeable.

The hourly type is currently only implemented for these provider:
- Environment Canada (envcanada)
- Openmeteo
- OpenWeatherMap (openweathermap), and only when /onecall is used as the specified endpoint. Latitude and longitude (see below) are required for hourly. The locationID and location options are ignored when the OpenWeatherMap One Call API is used and you will get wrong weather information.
- Weather.gov (weathergov)
- Yr (yr)
unitsWhat units to use. Specified by config.js

Possible values: config.units = Specified by config.js, metric = Celsius, imperial = Fahrenheit
Default value: config.units
tempUnitsWhat units to use for temperature. If not specified, the module uses the units value from config.js.

Possible values: config.units = Specified by config.js, metric = Celsius, imperial = Fahrenheit
Default value: config.units
windUnitsWhat units to use for wind speed. If not specified, the module uses the units value from config.js.

Possible values: config.units = Specified by config.js, mps or metric = metres per second, kmh = kilometres per hour, mph or imperial = miles per hour, beaufort = use beaufort scale, knots = show wind in knots
Default value: units
roundTempRound temperature value to nearest integer.

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

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

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

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

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

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

Possible values: true or false
Default value: false
showPrecipitationAmountShow the amount of rain/snow.

Not supported by all providers, and some providers do not support all types. Supported providers are envcanada, openmeteo, openweathermap, smhi, weatherbit and yr.

Possible values: true or false
Default value: false
showPrecipitationProbabilityShow the probability of rain/snow.

Not supported by all providers, and some providers do not support all types. Supported providers are envcanada, openmeteo, openweathermap, ukmetoffice, ukmetofficedatahub, weatherbit, weatherflow, weathergov and yr.

Possible values: true or false
Default value: false
showUVIndexShow the UV Index.

Not supported by all providers. Implemented provider is openmeteo but others could have support.

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

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

Possible values: ., , or any other symbol.
Default value: .
initialLoadDelayThe 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
appendLocationNameToHeaderIf 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
calendarClassThe class for the calender module to base the event based weather information on.

Default value: 'calendar'
useCorsProxySome weather modules need a cors proxy to get their api running.

Possible values: true or false
Default value: false (except providers pirateweather and envcanada)

Current weather options

OptionDescription
onlyTempShow only current Temperature and weather icon without windspeed, sunset, sunrise time and feels like.

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

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

Possible values: true or false
Default value: false
showHumidityWhether and where to show the current humidity

Possible values: wind, temp, feelslike, below or none
Default value: none
showIndoorTemperatureIf you have another module that emits the INDOOR_TEMPERATURE notification, the indoor temperature will be displayed
Default value: false
showIndoorHumidityIf you have another module that emits the INDOOR_HUMIDITY notification, the indoor humidity will be displayed
Default value: false
showFeelsLikeShows the Feels like temperature weather.

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

Possible values: true or false
Default value: true
allowOverrideNotificationEnables the ability to provide a CURRENT_WEATHER_OVERRIDE notification containing a WeatherObject payload that will be combined with the existing current weather
Default value: false

Weather forecast options

OptionDescription
tableClassThe class for the forecast table.

Possible values: 'xsmall', 'small', 'medium', 'large', 'xlarge'
Default value: 'small'
coloredIf set to true, the min and max temperature are color coded.

Default value: false
fadeFade the future events to black. (Gradient)

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

Possible values: 0 (top of the list) - 1 (bottom of list)
Default value: 0.25
maxNumberOfDaysHow 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 weather module will return 5 days.
maxEntriesHow many entries of an OpenWeatherMap One Call hourly or daily forecast type to return. Specified by config.js

Possible values: 1 - 48 for 'hourly' , 1 - 7 for 'daily'
Default value: 5 (5 entries)
This value is optional and specifically meant to be used with the OpenWeatherMap provider and its '/onecall' endpoint. By default the weather module will return 5 entries. Intended to act as a more generalized of the maxNumberOfDays option.
ignoreTodayIf set to true, today's weather will not be displayed.

Possible values: true or false
Default value: false

Openweathermap options

Note: When using the type: "forecast" config, if you are using a free api key, the max forecast days you can retrieve is 5. Providing anything higher than 5 for the maxNumberOfDays option will still return the default of 5. To retrieve more than 5 days you must subscribe to the OpenWeatherMap API.

OptionDescription
apiVersionThe OpenWeatherMap API version to use.

Default value: '3.0'
apiBaseThe OpenWeatherMap base URL.

Default value: 'https://api.openweathermap.org/data/'
weatherEndpointThe OpenWeatherMap API endPoint.

Possible values: '/weather' , '/onecall' , '/forecast' (free users) or '/forecast/daily' (paying users or old apiKey only)
Default value: '/onecall'
locationIDLocation 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.
locationThe 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.
latLatitude of the location used for weather information.

Example: 40.7128
Default value: 0

Note: Latitude and longitude are REQUIRED if weatherEndpoint is set to '/onecall'. The locationID and location options are ignored when the OpenWeatherMap One Call API is used.
lonLongitude of the location used for weather information.

Example: -74.0060
Default value: 0

Note: Latitude and longitude are REQUIRED if weatherEndpoint is set to '/onecall'. The locationID and location options are ignored when the OpenWeatherMap One Call API is used.
apiKeyThe OpenWeatherMap API key, which can be obtained by creating an OpenWeatherMap account.

This value is REQUIRED

Pirate Weather options

OptionDescription
apiBaseThe Pirate Weather base URL.

Possible value: 'https://api.pirateweather.net'
This value is REQUIRED
weatherEndpointThe Pirate Weather API endPoint.

Possible values: /forecast
This value is REQUIRED
apiKeyThe Pirate Weather API key, which can be obtained by creating a Pirate Weather account.

This value is REQUIRED
latThe geo coordinate latitude.

This value is REQUIRED
lonThe geo coordinate longitude.

This value is REQUIRED

Weather.gov options

OptionDescription
apiBaseThe weather.gov base URL.

Possible value: 'https://api.weather.gov/points/'
This value is REQUIRED
latThe geo coordinate latitude.

This value is REQUIRED
lonThe geo coordinate longitude.

This value is REQUIRED

UK Met Office (ukmetoffice) options

OptionDescription
apiBaseThe UKMO base URL.

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

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

This value is REQUIRED

UK Met Office (ukmetofficedatahub) options

OptionDescription
apiBaseThe UKMO DataHub base URL.

Possible value: 'https://data.hub.api.metoffice.gov.uk/sitespecific/v0/point/'
This value is REQUIRED
apiKeyYour API key (MetOffice API ClientID). See the Getting Started guide on the Met Office website for creating a new account. Subscribe to the Site Specific Forecast service - Global Spot.
This value is REQUIRED
latThe latitude coordinate for the desired location.

Possible value: 50.7271915
This value is REQUIRED
lonThe longitude coordinate for the desired location.

Possible value: -3.4776089
This value is REQUIRED

Weatherbit options

OptionDescription
apiBaseThe Weather base URL.

Possible value: https://api.weatherbit.io/v2.0
This value is REQUIRED
weatherEndpointThe Weatherbit API endPoint.

Possible values: /current, /forecast/daily
This value is REQUIRED
apiKeyThe Weatherbit API key which can be obtained by creating an WeatherBit account

This value is REQUIRED
latThe geo coordinate latitude.

This value is REQUIRED
lonThe geo coordinate longitude.

This value is REQUIRED

SMHI options

OptionDescription
latThe latitude coordinate for the desired location.

Possible value: 59.322665
This value is REQUIRED
lonThe longitude coordinate for the desired location.

Possible value: 18.069666
This value is REQUIRED
precipitationValueThe type of precipitation to display (min, max, median, mean).

Possible values: 'pmin' , 'pmean' , 'pmedian', 'pmax'.
Default value: 'pmedian'
locationThe optional display name of the location, shown on top of the module.

Example: 'Stockholm'
Default value: false

Environment Canada (envcanada) options

Note that envcanada supports Canadian locations only.

When using the type: "forecast" config, the module can display a max of 6 days (Today + the next 5 days). The forecast for each day reflects the daytime forecast. The Today forecast is a special case that will reflect the daytime forecast until late afternoon, after which Today will be reflecting the nightime forecast for the current day.

When using the type: "hourly" config, the module can display a max of 24 hours.

OptionDescription
siteCodeThe city/town unique identifier for which weather is to be displayed.

Example: siteCode: 's0000458' is the value for Toronto, Ontario

To determine the siteCode value for a Canadian city/town, look at the Environment Canada document at https://dd.weather.gc.ca/citypage_weather/docs/site_list_en.csv (or site_list_fr.csv). There you will find a table with city/town names you can search under column B (English Names), with the corresponding siteCode under column A (Codes)

This value is REQUIRED
provCodeThe 2-character province code for the selected city/town siteCode.

Example: provCode: 'ON' is the value for Toronto, Ontario

To determine the provCode value for a Canadian city/town, look at the Environment Canada document at https://dd.weather.gc.ca/citypage_weather/docs/site_list_en.csv (or site_list_fr.csv). There you will find a table with city/town names you can search under column B (English Names), with the corresponding provCode under column C (Province) - and of course the siteCode under column A (Codes)

This value is REQUIRED
locationThe free-format text string intended to hold a location name (e.g. city) that should appear in the module header.

Example: location: 'Toronto, ON'

Weatherflow options

OptionDescription
apiBaseThe Weatherflow base URL.

Possible value: https://swd.weatherflow.com/swd/rest/
This value is REQUIRED
tokenThe Weatherflow token which can be obtained in the webapp of Weatherflow

This value is REQUIRED
stationidThe id of your weather station from wich you want to show the data. This also can be obtained in the webapp of Weatherflow

This value is REQUIRED

Open-Meteo (openmeteo) options

OptionDescription
apiBaseThe Weatherflow base URL.

Possible value: https://api.open-meteo.com/v1
This value is REQUIRED
latThe latitude coordinate for the desired location.

Possible value: 59.322665
This value is REQUIRED
lonThe longitude coordinate for the desired location.

Possible value: 18.069666
This value is REQUIRED
maxNumberOfDaysHow many days of forecast to return. Specified by config.js

Possible values: 1 - 8
Default value: 5 (5 days)
This value is optional. By default the weather module will return 5 days.
pastDaysHow many days should forecast should include from historic data. Specified by config.js

Possible values: 0 - 5
Default value: 0 (0 days)
This value is optional. By default the weather module will return 0 days from historical data.

Note: Since Open-Meteo returns 8 days of data at all, this setting could reduce the range of forecast data set on maxNumberOfDays. e.g. if maxNumberOFDays is set to 7 and pastDays is set to 5, data received will be from 5 days from the past to 2 days in the future (8 days)

Yr options

The Yr weather provider is quite simple to set up, and only requires the coordinates for the desired location. These can be obtained from for instance Google Maps by right-clicking the map.

If you use several instances of the Yr weather provider, please set the initialLoadDelay to have a minimum value of 500 between the instances. Yr.no wants as little traffic as possible to their servers, and a slight load delay is enough for the instances to cooperate better when fetching the data.

OptionDescription
latThe latitude coordinate used for weather information. This value can not have more than four decimals. Use ., not ,.

Example: 59.9171
This value is REQUIRED.
lonThe longitude coordinate used for weather information. This value can not have more than four decimals. Use ., not ,.

Example: 10.7276
This value is REQUIRED.
altitudeThe height/vertical distance above sea level used for weather information.

This value is optional.
Example: 30
Default value: 0.

Current weather options

Possible options when using the type: "current" config, the module displays the forecast for the specified time. If Yr predicts rain from 1 to 2, and sun from 2 to 3, the rain-symbol will display until 2 and then change on the next update.

OptionDescription
currentForecastHoursHow many hours the displayed weather should represent. Possible values are 1, 6 or 12.

This value is optional.
Example: 6
Default value: 1.

API Provider Development

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

Help us improve this page!
Last Updated:: 4/30/25, 8:00 PM
Prev
Update Notification