Documentation

Map Forecast 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 Map Forecast API lets you customize Windy map visualizations with your own content and imagery for display on web pages and mobile devices. The Map Forecast 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://api.windy.com/assets/map-forecast/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 Map Forecast 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 Map Forecast 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.

Other sources

Conditions of use

Trial

The Trial version is free. It offers only a limited subset of all models, layers and isolines. This version is for development only and is not allowed to be used in production.

Professional version

For serious work, your only option is the Professional version of API. See the homepage 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