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.

Obtain your Windy API key here
Add leaflet 1.4.0 library to your website: https://unpkg.com/leaflet@1.4.0/dist/leaflet.js
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

Testing

The Testing 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.

Need help?

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