Documentation

Windy JavaScript API is a simple-to-use library based on Leaflet 1.4.x. It allows you to use everything Leaflet or JavaScript offers, along with the Windy map visualizations we use at Windy.com.

Overview

The Windy JavaScript API lets you customize Windy map visualizations with your own content and imagery for display on web pages and mobile devices. The Windy JavaScript API features layers, particles, legend, picker, and isolines, as well as basic controls and the map. You can choose what you want to display and modify everything using styles, controls and events, as well as various libraries.

Getting started

To get API working, just do these 3 simple steps. It will not take you more than a few minutes.

  1. Obtain your Windy API key here
  2. Add leaflet 1.4.0 library to your website: https://unpkg.com/leaflet@1.4.0/dist/leaflet.js
  3. Add Windy API library to your website: https://api4.windy.com/assets/libBoot.js
Do not use the leaflet CSS file as it has some bugs. Windy API lib downloads fixed styles on its own.

That's it! Now you are able to initialize Windy map at your website. See the Hello World example on how to do that.

How to work with the map

There is a big difference between the map itself and the Windy map visualizations:

  • the map provides basic interactivity and functionality, such as zooming, dragging, moving, click handling, etc...
  • the Windy map visualizations are just an extension of the map

The map is realized using the Leaflet library. Everything you can do with the Leaflet library you can also do with the Windy JavaScript API.

The Windy map visualizations enhance the map with layers, particles, and isolines. These visualizations can be controlled programmatically or using UI controls. To control visualizations programmatically you have to use JavaScript object windyAPI, which is returned after API initialization. To control visualizations using UI controls, use the menu on the right, progress bar, legend, or picker.

Reference

You can use all features provided by the Leaflet library. Only features provided by the JavaScript windyAPI object are described below.

Do not use features not listed here as we cannot guarantee that they will be available in other versions of Windy JavaScript API.

store

The most important class of the API - it holds the state of the map and visualizations. It also allows you to change the state. All values are stored in a key-value structure.

Check out this tutorial also to find out which keys are useful.

Methods

Method Returns Description
get (key) any Returns the value, which has been set for the key.
getAllowed (key) any[] | string Returns the array of all allowed values, which can be set for the key. String is returned when the array cannot be returned.
set (key, value, opts) - Set or change the value for the key. To skip all validations, use { forceChange: true } as opts.
on (key, callback) - Bind a function callback to run it every time the value for the key is changed.
once (key, callback) - Bind a function callback to run it only once when the value for the key is changed.
off (key, callback) - Unbind the callback function.

map

This is an instance of the Leaflet L.Map class. Check the Leaflet documentation for more info.

picker

Weather picker to get the value of the current layer at specific coordinates. The picker works only on desktop, but you can make it work even for mobile devices on your own.

Check out this tutorial for better understanding.

Methods

Method Returns Description
open ({ lat, lon }) - Open the picker at lat,lon coordinates.
close () - Close the picker.
getParams () { lat, lon, values, overlay } Get values from the open picker.
on (event, callback) - Bind a function callback to run it every time the event was emitted.
once (event, callback) - Bind a function callback to run it only once when the event was emitted.
off (event, callback) - Unbind the callback function from the event.

Events

Event Data Description
pickerOpened { lat, lon } Fired immediately after the picker is opened.
pickerMoved { lat, lon, values, overlay } Fired every time the picker is moved.
pickerClosed - Fired immediately after the picker is closed.

utils

Collection of some useful methods.

Methods

Method Returns Description
deg2rad (deg) number Converts degree to radian.
isNear ({ lat, lon }, { lat, lon }) boolean Check if two latLon objects are 0.01deg close to each other.
isValidLatLonObj ({ lat, lon }) boolean Check if object contains lat and lon properties. Values are not checked.
lonDegToXUnit (deg) number Converts longitude degree <-180.0; 180.0> to mercator <0.0, 1.0>.
latDegToYUnit (deg) number Converts latitude degree <-85.05; 85.05> to mercator <0.0, 1.0>.
unitXToLonDeg (x) number Converts mercator <0.0, 1.0> to longitude degree <-180.0; 180.0>.
unitYToLatDeg (y) number Converts mercator <0.0, 1.0> to latitude degree <-85.05; 85.05>.
latLon2str ({ lat, lon }) string Encodes latLon object into string.
str2latLon (hash) { lat, lon } Decodes latLon from string hash.
wave2obj (number[]) { period, dir, size } Converts wave vectors to user friendly object.
wind2obj (number[]) { wind, dir } Converts wind vectors to user friendly object.

broadcast

Main events broadcaster and emitter. Check out this tutorial to discover some useful events.

Methods

Method Returns Description
fire (event, ...args) - Emits the event with args for callbacks.
on (event, callback) - Bind a function callback to run it every time the event was emitted.
once (event, callback) - Bind a function callback to run it only once when the event was emitted.
off (event, callback) - Unbind the callback function from the event.

overlays

This object contains all instances of all layers. It comes in handy when you need to change the layer metric (check this tutorial for better understanding). Note that layers that are not part of the API are also part of the object, but they are totally useless.

The list below are methods of one particular layer from the whole collection (e.g. wind or temp).

Methods

Method Returns Description
convertNumber (value) number Converts default metric value to the value of currently selected metric.
convertValue (value) string Converts default metric value to the value of currently selected metric, label with units is included.
cycleMetric () - Switches to the next available metric.
listMetrics () string[] Returns the list of all available metrics.
setMetric (metric) - Set specific metric.

Attributes

Attribute Description
metric Label of the currently selected metric.

colors

This object contains all color definitions of all layers. It comes in handy when you need to change the color definition of any layer. Note that layers that are not part of the API are also part of the object, but they are totally useless.

The list below are methods of one particular color definition from the whole collection (e.g. wind or temp).

Methods

Method Returns Description
changeColor (colors) - Changes default colors. The method accepts the same format as the Customize color scale tool at Windy.com exports.
checkValidity (colors) boolean A basic check if the color scale is valid. It does not check values, just object structure.
color (value) string Returns color for the value in rgb(r,g,b) string format.
RGBA (value) number[] Returns color for the value in [R,G,B,A] array format.
toDefault () - Resets colors to the default.

Conditions of use

Essential version

The Essential version is free, but is limited to 5 000 sessions per day. It offers only a limited subset of all models, layers and isolines. The Windy logo MUST remain as it is, i.e. clickable and without modification. However, you can move the Windy logo wherever you want within the Windy map. For the Essential version, we reserve the right to:

  1. display advertisement inside the Windy map
  2. place "Download Windy App" message from time to time on mobile devices
  3. discontinue the free version of Windy API at any time without prior notice

Premium version

For serious work, we recommend using the Premium version of API. Contact us for more information.

Things to remember

  • While providing coordinates to Leaflet can be done via object { lat, lng } with lng property, Windy supports { lat, lon } with lon property.
  • There can be only one instance of the Windy Map on a page, but you can use multiple instances of the Leaflet map on the same page.
  • All classes of leaflet.css are nested inside the #windy selector (so as not to interfere with your own CSS), so if you want to use another instance of the Leaflet map on the same page, load leaflet.css yourself once more.
  • Windy uses a lot of global defined CSS classes and id selectors with nice names like #bottom, #logo etc. Windy also puts a lot of CSS classes to body tag dynamically. If the design of Windy Map is broken, check your CSS and rename your id and selectors please.
  • Windy API does not use cookies.
  • Windy API heavily uses localStorage. Unintentional or intentional modifications of our items can lead to instability of Windy API.
  • Using undocumented functions of the Windy engine can break your app when we decide to upgrade our codes. If you are missing something, rather let us know here and ask us to document and expose other features.

Technical support

Drop a line in our Windy API section of our Windy Community forum.

Windy community forum

Changelog

4.7
2019-04-29
  • Finally, the version with Leaflet 1.4.
4.5
2018-11-20
  • New lib codes based on the Windy client v16.17.0
  • Updated menu on the right side to contain all the available layers.
  • The map selector was renamed to #map-container so make sure it will be compatible with your code.
4.4
2018-10-05
  • New API conditions
4.0
2018-07-30
  • The Leaflet and Windy library are based on Leaflet v0.7.7 and based on Windy Client v15.15.1
3.0
2017-2018
  • Windy API is an easy to use console using iframe and requires all apps to run on mywindy.com domain.
2.3
2016-11-18
  • Fixed bug after changing URL from windyty.com to windytv.com.
2.2
2016-06-01
  • boot.js now runs on https
2.1
2016-06-01
  • Increased size of typed arrays storage to handle retina displays.
2.0
2016-04-15
  • Completely new version of API based on new Windyty 6.X.X codes.