- About Windy API
- Module: map
- Class: Evented
- Module: brodacast
- Module: store
- Module: overlays
- Module: utils
- Module: plugins
- Module: picker
- Module: interpolator
- Module: pluginDataLoader
Windy codes consist of classes (for example Evented
), modules (for example metrics
) and external plugins, that are loaded when necessary. The plugins are either internal (created by us) and external, created by Windy users.
Example of loading a module to your plugin:
import map from '@windy/map'
While plugin codes use
import
keyword, Windy client uses its own dependency injection system. If you plan to compile plugin on your own, useconst map = W.require('map')
Instance of Leaflet map is available as map
module. Windy uses Leaflet version 1.4.0
that is well documented here and contains plenty of plugins that you can use.
map
has also some custom Windy methods and props attached to itself.
Windy defines small set of predefined markers (instances of L.DivIcon
) that you could potentionaly use. Those are:
map.myMarkers.icon Pulsating icon, pulsating for short time
map.myMarkers.pulsatingIcon Pulsating icon forever
map.myMarkers.myLocationIcon Blue icon of user's location
map.myMarkers.other Rounded circle
Example:
L.marker([ 50, 14 ], {
icon: map.myMarkers.pulsatingIcon
}).addTo( map );
Some of the Windy components are descendants of Evented
and emit messages.
Recieving and emitting messages has a usual syntax and methods: on, off, once, emit
. (You can use handy aliases fire
or trigger
to emit messages if you are used to.)
Just remember that broadcasts emitted by map
are in fact Leaflet's brodcast, not Windy's ones.
Major Windy's emitter (instance of Evented
), used for most important events.
mapChanged After Leaflet map has been panned or zoomed.
paramsChanged
When user changes some paramters (overlay, level, date etc...). Do not not use this event to start any intensive action since Windy now must load and render all the data. We recommend to use redrawFinished
instead.
redrawFinished Triggered when Windy has succesfully loaded and rendered requested data. Use this for triggering your own tasks.
metricChanged After some of the units (wind, temp, ...) has been changed.
rqstOpen, rqstClose, closeAll Requests to load and open or close plug-ins (see later)
pluginOpened, pluginClosed Lazy loaded plugin was sucessully loaded and opened/closed
redrawLayers Forces various renderers to render layers, for example after reconfiguring color gradient, or changing particle animation settings.
uiChanged Whenever User Interface has been changed. Information for other UI components to recalculate their respective sizes and adapt themselfs to new layout.
Example:
broadcast.on('redrawFinished', params => {
// Wow Windy has finished rendering.
})
All major parametrs and settings are stored inside store
. It is sophisticated key, value store that checks your input for validity and maintains integrity of all the parameters.
Use methods get
to read value from store, set
to change value in the store and on
to observe change of the value. Some of the items respond to method getAllowed
to return array of allowed values.
Method set
returns true
if provided value was valid and was actually changed.
Store is instance of Evented
.
Example:
var overlay = store.get('overlay')
// 'wind' ... actually used overlay
var allowedOverlays = store.getAllowed('overlay')
// ['wind', 'rain', ... ] ... list of allowed values
store.set('overlay','rain')
// true ... Metric was changed to rain
store.on('overlay', ovr => {
// Message will be emitted only if value is valid and actually changed
console.log('Wow, overlay has been chnaged to', ovr)
})
Each stored item has some default value. The values that can be considered as users's own settings, are read only. It is strictlly prohibited to change user's settings without his action and permission.
Some of the major items you could be interested in are:
overlay
Color weather overlay. Use store.getAllowed('overlay')
to get list of allowed values.
level
Level used for actualy displayed overlay or isolines. To get list of available levels for current combination of overlay and data provider type store.get('availLevels')
availLevels List of levels, that are available for current combination of product and overlay.
acTime
Accumulated time. Use store.getAllowed('acTime')
to get list of allowed values.
timestamp Timestamp of actual weather moment. Use freely and without hesitation.
Example:
var fiveHours = 5 * 60 * 60 * 1000
store.set('timestamp', Date.now() + fiveHours )
path - read only UTC string containing time of actually rendered data that are available for current overlay and weather model.
isolines - read only
Isolines displayed over the map. Use store.getAllowed('isoline')
to get list of allowed values.
product
Product is set of weather data, that have same resolution, boundaries, time range and so on. For simplification, you can think of product as a weather model. Use store.getAllowed('product')
to get list of allowed values.
particlesAnim - read only Informs if animation of wind/waves particles is running over the map.
usedLang - read only ISO language code of language used.
hourFormat - read only
Time format, returns 12h
or 24h
.
numDirection - read only
Display directions in Weather picker as number or as a string (for example NW). returns true
or false
.
Defines main parameters required to render specific weather overlay. Each defined overlay contains all used overlays together with their colors
, settings for legend
and metrics
. Remember that it is prohibited to change the user's metric.
Converts value provided in default meteorological metric into user's selected metric as a string. Separator is an optional separator between number and unit.
Converts value provided in default meteorological metric into user's selected metric as a pure number.
Example:
overlays.wind.metric
// 'kt' .. actually selected metric for wind overlay
overlays.wind.listMetrics()
// ['kt', 'bft', 'm/s', 'km/h', 'mph'] .. available metrics
overlays.wind.convertValue(45, ' ')
// '87 m/s'
overlays.wind.convertNumber(45)
// 87
broadcast.on('metricChanged', (overlay, newMetric) => {
// Any changes of metric can be observed here
})
Handy utilities
Loads external JS file, returns Promise
Example:
utils.loadScript('https://unpkg.com/d3@5.7.0/dist/d3.min.js')
.then( initGraph )
Converts raw meterological values into wind Object.
Example:
utils.wind2obj( [3.8534493726842562, 7.977292512444887, 0] )
// { dir: 210.4334, wind: 10.2 }
Converts raw meterological values into wave Object.
Handy shortcut to document.querySelector
.
Usage:
const $ = {utils};
const el = $('.closing-x', parentEl ); // parentEl is optional
Windy can use plugins that are loaded whenever necessary, making core codes small and fast. Plugin can be for example JavaScript library, or some user feature (like menu sliding from the right side). We recommend to access these plugins just by emitting messages rqstOpen
and rqstClose
on major broadcast
. Some of the plugins require parameters for opening.
Only few plugins can be safely exposed in Windy API like: distance
, picker
, settings
or detail
.
Example:
broadcast.fire('rqstOpen', 'detail', { lat: 50, lon: 14 })
// Opens weather detail
broadcast.fire('rqstOpen', 'detail')
// Closes weather detail
Weather picker can be opened programatically as any other plugin by emiting request message: broadcast.fire('rqstOpen', 'picker', { lat: 50, lon: 14 })
.
If the picker is opened outside visible map, it is closed afterwards, and also panning so the picker gets outside map leads to close of the picker. Picker emits message about its own state.
Example:
broadcast.fire('rqstOpen', 'picker', { lat: 50, lon: 14 })
// Opens the picker
broadcast.fire('rqstClose', 'picker')
// Closes the picker
Picker emits messages pickerOpened
, pickerClosed
and pickerMoved
, while picker moved provides raw meteorological values in the picker location.
Example:
picker.on('pickerOpened', latLon => {
// picker has been opened at latLon coords
})
picker.on('pickerMoved', latLon => {
// picker was dragged by user to latLon coords
let { lat, lon, values, overlay } = picker.getParams()
// -> 50.4, 14.3, [ U,V, ], 'wind'
let windObject = utils.wind2obj( values )
// { dir: 210, wind: 10.2 }
})
picker.on('pickerClosed', () => {
// picker was closed
})
Raw meteorological units returned from weather picker are usually described in respective documentation for GFS
or other used forecast models.
Most popular overlays have these values:
wind
Array [ U, V ]
, where U and V are wind vectors in m/s
. To compute wind magnitude and direction use W.utils.wind2obj
.
Example:
utils.wind2obj( [3.8534493726842562, 7.977292512444887, 0] )
// { dir: 210.4334, wind: 10.2 }
temperature, dewPoint
Temperature in K
rain, rainAccumulation
Rain for duration of 3 hours or selected accumulation period in mm
waves, swell
Array [ U, V, size]
where U and V are direction vectors and wave size is in m
. Period in seconds is computed as Math.sqrt( U * U + V * V )
. Use W.utils.wave2obj
to compute respective values
Example:
utils.wave2obj( [4.36770334, -6.40998, 2.426323] )
// { dir: 325.9878, size: 2.4, period: 8 }
To convert values to user's selected metrics use convertNumber
or convertValue
methods of respective W.overlays
instance. While converNumber
just recalculates value and return a number, convertValue
adds name of a metric and returns a string.
Example:
var ovr = overlays[ store.get('overlay') ]
// ovr now contains instance of actualy selected overlay
ovr.convertNumber( 10 )
// 19
ovr.convertValue( 10 )
// "19kt"
Return interpolator funtion for a given active layer. Returned function can interpolate coordinates into the raw meterological values
Example:
interpolator( interpolatorFun => {
// now I can interpolate coords or
// screen X,Y
const values = interpolatorFun( { lat: 50, lon: 14 })
// --> [ 15.090, 45, 0 ]
})
Interpolates coordinates to raw meteorological values (same used by picker) or some falsy values:
null .. out of map,
NaN .. no data value
-1 .. not suitable renderer
[number,number,number] .. success, interpolated values
To communicate with our backend API get your own API key here. Ignore "Allowed domains" fields it this case.
Module plugin-data-loader
returns a function, that creates instance of reusable backend data loader.
Once you create your loading instance, you use it like this: load( type, options )
, where type
describes type of data you want to load and options depend on the type you want to load.
So far only forecast
and airData
types are supported. Let us know if we should add more data types
to API.
Data loader function returns a Promise, that resolves into { status, data }
object.
forecast
and airData
types require object { lat, lon, model }
. Following models are supported:
gfs, gfsWaves, namConus, namHawaii, namAlaska, iconEu
.
Example:
import pluginDataLoader from '@windy/plugins/plugin-data-loader'
// Create new dataLoder instance
const load = pluginDataLoader({
key: 'Your-backend-API-key',
plugin: 'windy-plugin-name-of-your-plugin'
})
// dataLoader accepts object with all required parameters
const dataOptions = {
model: 'gfs',
lat: 50,
lon: 14
}
// Loads point forecast for lat, lon
load('forecast', dataOptions ).then( result => {
// Returned object contains http status and data
const { status, data } = result
console.log( data )
})