Windy API documentation (client v13.00+)


  • administrators

    Windy API ( client v13.00+ )

    Getting started

    Windy API enables you to create your own Windy App with minimum effort. You do not need any server, and you can have your Windy App running in less than 5 minutes with minimum knowledge of Javascript.

    Once you are logged in API console at https://api.windy.com, you can create one or more Windy Apps that will be accessible on https://mywindy.com/username/app-name.

    If you want to run your Windy App on your own domain, set up your own server somewhere, and embed your Windy App inside and iframe.

    Examples

    1. Hello world

    2. Leaflet, markers and pupups

    3. Playing with User Interface

    4. Recieving broadcasts

    5. Changing overlays, levels

    6. Display geoJSON

    7. Boat tracker

    8. Flight tracker

    9. Working with weather picker

    10. Hosting your JS and CSS on your own server

    How Windy App works

    Your Windy App consist of Javascript, CSS and HTML code, tha is inserted and executed inside simplified version of codes, that power Windy.com. Your HTML content is inserted as the last element of document's body, or head section. Your javascript is wrapped inside (function() { ... })() so you do not need to wrap it.

    Windy uses library Leaflet.

    Your Javascript code, will be launched when document is loaded, Leaflet map is initialized, and all is up and running.

    _center_shadow

    Why Windy App is not a library?

    Since Windy client is highlly optimized native JS code, using a lot of global browser features, and also CSS fixed positioning, we are unable to expose Windy client as a stand alone library. We also want all commercially licenced data (for example ECMWF model) to run on our domain.

    Version numbers

    Since Javascript code, that powers your mywindy.com app is just simplified code of main Windy client, it has same version numbers. You have ability to choose, which version of simplified Windy client will power your own mywindy.com app via drop down menu in Windy Console.

    Conditions to use Windy API

    Windy API is set of code and resources for displaying interactive animated map of weather forecast. Use of this version of Windy API is free for the time being as long as Windy logo and link to Windy website will be visible on a map, and will remain clickable majority of the times, including all the credits to data providers (ECMWF, OSM).

    We reserve rights to change these conditions or to discontinue Windy API at any time.

    Usage in mobile apps

    It is prohibited to use, bundle, or include Windy API client, data or any part of our intellectual property as a part of iOS or Android application without our prior written permission. This behavior will be treated as serious breach of our conditions and the app will be removed from Google Play or App Store as we have already done it few times before.

    Permission to use Windy API as a part of native mobile apps could be obtained, after consensual agreement.

    API description

    While Leaflet uses global object L, Windy javascript libraries use global object W.

    Windy codes consist of classes (for example W.EventCatcher), modules (for example W.metrics) and external plugins, that are loaded when necessary.

    W.map: working with Leaflet

    Instance of Leaflet map is available as W.map. Windy uses Leaflet version 0.7.7 that is well documented here and contains plenty of plugins that you can use.

    W.map has also some custom Windy methods and props attached to itself.

    Example of diplaying geoJSON on a map:

        var url = 'https://raw.githubusercontent.com/windyty/API/master/assets/capAlerts.json'
    
        // Centers the map to USA
        W.map.setView([47.443,-95.400])
    
        // Loads GeoJSON and displays it on Windy
        fetch(url)
            .then(response => response.json())
            .then(result => {
                
                L.geoJson( result ).addTo( W.map )
    
            }) 
    

    We do not plan to upgrade Leaflet version for now.

    W.map.myMarkers: Predefined Leaflet markers

    Windy defines small set of predefined markers (instances of L.divIcon) that you could potentionaly use. Those are:

    W.map.myMarkers.icon
    Pulsating icon, pulsating for short time

    W.map.myMarkers.pulsatingIcon
    Pulsating icon forever

    W.map.myMarkers.myLocationIcon
    Blue icon of user's location

    W.map.myMarkers.other
    Rounded circle

    Example:

        var marker = L.marker([ 50, 14 ], { icon: W.map.myMarkers.pulsatingIcon })
    
        marker.addTo( W.map );
    

    W.Evented: emitting and broadcasting messages

    Some of the Windy components are descendants of W.Evented and emit messages.

    Recieving and emmiting messages has usuall syntax and methods: on, off, once, fire. (You can use handy aliases emit or trigger to emit messages if you are used to). Each emitter has its own color producing nice output in browser's console.

    Just remember, that broadcasts emited by W.map are in fact Leaflet's brodcast, not Windy's ones.

    W.brodacast: main Windy's broadcaster

    W.broadcast (instance of W.Evented) is major Windy's emitter, used for most important events.

    Main broadcasted messages are:

    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 lazy loaded plug-ins (see later)

    pluginOpend, pluginClosed
    Lazy loaded plugin was sucessully loaded and opend/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:

        W.broadcast.on('redrawFinished', params => {
    
            // Wow Windy has finished rendering.
            console.log( params )
    
        })
    

    W.store: main data store

    All major parametrs and settings are stored inside W.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.

    Example:

        var overlay = W.store.get('overlay')
        // 'wind' ... actually used overlay
    
        var allowedOverlays = W.store.getAllowed('overlay')
        // ['wind', 'rain', ... ] ... list of allowed values
    
        W.store.set('overlay','rain')
        // true ... Metric was changed to rain
    
        W.store.on('overlay', ovr => {
            // Message will be emited only if value wa valid and actually changed
            console.log('Wow, overlay has been chnaged to', ovr)
        })
    

    W.store is event emitter (instance of W.Evented) and supports all the range of methods (on, off, once, fire).

    Main items stored in W.store

    To list all data inside store use W.store.getAll().

    Each stored item have some default value. Default metrics (imperial or metric) and time settings (12h or 24h) is determined by visitors country location, but you can override any of the value.

    Some of the major items you could be interested in are:

    overlay
    Color weather overlay. Use W.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 W.store.get('availLevels')

    availLevels
    List of levels, that are available for current combination of product and overlay.

    acTime
    Accumulated time. Use W.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
    
        W.store.set('timestamp', Date.now() + fiveHours )
    

    path
    Read only value! UTC string containing time of actually rendered data that are available for current overlay and weather model.

    isolines
    Isolines displayed over the map. Use W.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 W.store.getAllowed('product') to get list of allowed values.

    particlesAnim
    Animation of wind/waves particles over the map. Set value to on, or off if you wan to hide or show them.

    graticule
    Display graticule over the map. Set it to true or false.

    latlon
    Diplay lat/lon values on weather picker. Set it to true or false.

    englishLabels
    Show english map labels instead of localized labels. Set it to true or false.

    lang
    Desired language for Windy. By default is determined by user's browser setting and set to auto. Use W.store.getAllowed('lang') to get list of avail langs.

    hourFormat
    Time format, Set it to 12h or 24h.

    numDirection
    Display directions in Weather picker as number or as a string (for example NW). Set it to true or false..

    favOverlays
    List of overlays, that are displayed in overlays menu. Alway crete new array, when you want to modify this list (W.store is primitive and can't compare arrays)

    Example:

        W.store.set('favOverlays',['wind', 'gust', 'rain', 'rainAccu','snowAccu'])
    

    Note: Even though W.store contains all the metrics and units, we advise you to access and change metrics only through W.overlays module.

    Permanent storage and cloud synchronisation

    While Windy client is able to store some W.store items permanentlly (using browser's localStorage) and some of them even sync with othere devices via cloud, this feature is not supported in API.

    W.overlays: change and convert metrics

    W.overlays 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.

    You will use this module to read and modify these values and customize your app.

    Example:

    
        W.overlays.wind.metric
        // 'kt' .. actually selected metric for wind overlay
        // Read only value! Do not modify.
    
        W.overlays.wind.listMetrics()
        // ['kt', 'bft', 'm/s', 'km/h', 'mph'] .. available metrics
    
        W.overlays.wind.setMetric('bft')
        // Metric for wind was changed to bft
    
        W.broadcast.on('metricChanged', (overlay,newMetric) => {
            // Any changes of metric can be observed here
        })
    

    W.plugins: lazy loaded plugins

    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 W.broadcast. Some of the plugins require parameters for opening.

    Only few plugins can be safely exposed in Windy API like: distance, picker or settings.

    Example:

        W.broadcast.fire('rqstOpen','distance')
        // Open distance measurement plugin
    
        W.broadcast.fire('rqstClose','distance')
        // Closes distance measurement plugin
    

    W.picker: weather picker

    Weather picker can be opend programatically as any other plugin by emiting request message: W.broadcast.fire('rqstOpen','picker',{ lat: 50, lon: 14 }). If the picker is opened outside visible map, it is closed afterwards, and also paning so the picker gets outside map, leads to close of the picker. Picker emits message about its own state and supports all the range of methods (on, off, once, fire).

    Example:

    
        W.map.setView([50,14])
        // Change centre of the map
    
        W.broadcast.fire('rqstOpen','picker',{ lat: 50, lon: 14 })
        // Opens the picker
    
        W.broadcast.fire('rqstClose','picker')
        // Closes the picker
    

    Picker itself is event emitter (instance of W.Evented) firing pickerOpened, pickerClosed and pickerMoved, while picker moved provides raw meteorological values in the picker location.

    Example:

        W.picker.on('pickerOpened', latLon => {
            // picker has been opened at latLon coords
        })
    
        W.picker.on('pickerMoved', (latLon,result) => {
            // picker was dragged by user to latLon coords
    
            console.log( result )
            // { overlay: 'wind', values: [ 0.4, 0.75, 0] }
    
        })
    
        W.picker.on('pickerClosed', () => {
            // picker was closed
        })
    

    Converting raw meteorological values to readable numbers

    Raw meteorological units returned frpm weather picker are usually described in respective documentation for ECMWF, 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:

        W.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 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:

        W.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 = W.overlays[ store.get('overlay') ]
        // ovr now contains instance of actualy selected overlay
    
        ovr.convertNumber( 10 )
        // 19
    
        ovr.convertValue( 10 )
        // "19kt"
    

    W.colors: changing color of overlyas

    Each used color gradient is defined as instance of W.Color stored inside W.colors. Gradient is configured as array, that has respective metorologival value as first item, and [R, G, B, A ] array as second item.

    Example of wind gradient:

        [[0,[255,37,37,80]],
        [1,[0,100,254,80]],
        [3,[0,200,254,80]],
        [5,[37,193,146,80]],
        ...
        [24,[86,54,222,80]],
        [27,[42,132,222,80]],
        [29,[64,199,222,80]],
        [100,[150,0,254,80]]]
    

    To modify color gradient use main Windy Client Settings > Advanced settings > Configure colors. Color gradient can be exported or imported then.

    To change color programaticaly inside your app use methods changeColor or toDefault of respective color.

    Example:

        W.colors.wind.changeColor( [ .. new gradient ...] )
    
        W.broadcast.fire('redrawLayers')
        // Force renderer to reload new colors and render map
    
        W.colors.wind.toDefault()
        // Sets colors back to default
    

    TODO: Changing background map tiles

    Contributing guide

    W.Class: Windy classes

    Windy object model is powered by objects inspired by Leaflet's L.Class. But we have made it more simple, includind avoidance to use keyword new. W.Class has methods extend and instance. Constructor is method named _init and while extend just extends the class instance calls constructor afterwards.

    extends support multiple classes as parameters making nice mixins in just one line of code.

    Source code:

        W.Class = {
            extend() {
                var dest = Object.create(this),
                i, j, len, src
    
                for (j = 0, len = arguments.length; j < len; j++) {
                    src = arguments[j]
                    for (i in src) {
                        dest[i] = src[i]
                    }
                }
                return dest
            },
            
            instance() {    
                var dest = this.extend.apply(this,arguments)
                // Call the _init if is found
                if( typeof dest._init === 'function' ) dest._init.call(dest)     
                return dest;
            }
        }   
    

    Note: Used markdown-toc CLI to generate TOC


Log in to reply
 

Windyty, S.E. - all rights reserved. Powered by excellent NodeBB
NodeBB & contributors, OSM & contributors, HERE maps

Looks like your connection to Windy Community was lost, please wait while we try to reconnect.