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. Receiving 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, that 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 the document is loaded, Leaflet map is initialized, and all is up and running.

    _center_shadow

    Why Windy App is not a library?

    Since the Windy client is highly 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 licensed 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 the ability to choose, which version of the 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 an interactive animated map of a 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 a serious breach of our conditions and the app will be removed from Google Play or App Store as we have already done it a few times before.

    Permission to use Windy API as a part of native mobile apps could be obtained, after a 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

    The 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 displaying 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 a small set of predefined markers (instances of L.divIcon) that you could potentially 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.

    Receiving and emitting messages has usually 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 emitted by W.map are in fact Leaflet's broadcast, not Windy's ones.

    W.brodacast: main Windy's broadcaster

    W.broadcast (an 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 a user changes some parameters (overlay, level, date etc...). Do not use this event to start any intensive action since Windy now must load and render all the data. We recommend using redrawFinished instead.

    redrawFinished
    Triggered when Windy has successfully 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 successfully 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 themselves to a new layout.

    Example:

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

    W.store: a main data store

    All major parameters and settings are stored inside W.store. It is sophisticated key, value store that checks your input for validity and maintains the integrity of all the parameters.

    Use methods get to read a value from the store, set to change a value in the store and on to observe a change of the value. Some of the items respond to method getAllowed to return an 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 emitted only if value was 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 actually displayed overlay or isolines. To get a list of available levels for a current combination of overlay and data provider type W.store.get('availLevels')

    availLevels
    List of levels, that are available for a 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 a 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
    The product is set of weather data, which have the same resolution, boundaries, time range and so on. For simplification, you can think of a 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 want to hide or show them.

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

    latlon
    Display 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 a number or as a string (for example NW). Set it to true or false...

    favOverlays
    List of overlays that are displayed in overlays menu. Always create a 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 synchronization

    While the Windy client can store some W.store items permanently (using browser's localStorage) and some of them even sync with other devices via the cloud, this feature is not supported in the 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, which are loaded whenever necessary, making core codes small and fast. The plugin can be for example javascript library, or some user feature (like menu sliding from the right side). We recommend accessing these plugins just by emitting messages rqstOpen and rqstClose on major W.broadcast. Some of the plugins require parameters for the opening.

    Only a 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 opened programmatically as any other plugin by emitting request message: W.broadcast.fire('rqstOpen','picker',{ lat: 50, lon: 14 }). If the picker is opened outside the visible map, it is closed afterward, and also panning so the picker gets outside the map, leads to close of the picker. Picker emits message about its 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 (an 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 the 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 from weather picker are usually described in the 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 using W.utils.wind2obj.

    Example:

        W.utils.wind2obj( [3.8534493726842562, 7.977292512444887, 0] )
        // { dir: 210.4334, wind: 10.2 }
    

    temperature, dewPoint
    Temperature in K

    rain, rain accumulation
    Rain for a 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. The 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 a 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 overlays

    Each used color gradient is defined as an instance of W.Color stored inside W.colors. The gradient is configured as an array, that has respective meteorological value as the first item, and [R, G, B, A ] array as the 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 programmatically inside your app use methods changeColor or toDefault of the 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, including avoidance to use keyword new. W.Class has methods extend and instance. The constructor is a method named _init and while extend just extends the class instance calls constructor afterward.

    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



  • I'm using the old API 2.3. How can I migrate it to the new one? Because I have many other libs being used with leaflet, to use custom markers, search on my data, and populate the markers. And I can not recreate what I have today using the api editor.



  • @ivo said in Windy API documentation (client v13.00+):

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

    IMHO, this sentence could be clarified a bit by saying:

    Invoke W.store.getAll() to print to the console all data present in the store.

    because that's what is happening. I was wondering why I did not get anything returned by invoking W.store.getAll() from within the Firefox Scratchpad REPL.

    (IMHO, ideally, the API function would rather be W.store.dumpToConsole(), but that's an entirely different story :))


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.