Windy API

https://github.com/windycom/api
Admin
Map Forecast API is a simple-to-use library based on Leaflet that allows you to use Leaflet and...
Tokens:2,558
Snippets:14
Trust Score:8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Initialize Windy Map API with Leaflet

Source: https://github.com/windycom/api/blob/master/hello-world/README.md

This snippet outlines the process of loading the Leaflet and Windy API libraries, preparing the HTML container for the map, and calling the `windyInit` function. It details the mandatory `key` property within the options object and the structure of the callback function.

```APIDOC
windyInit(options, callback)
  options: Object (mandatory)
    key: String (mandatory) - Your API key.
    Other start-up values: Any (optional) - Highly recommended to include as many as possible.
  callback: Function (mandatory)
    parameter: Object - The Windy API object, received when Windy API is ready.
```

--------------------------------

### Windy API Broadcasts and Event Methods

Source: https://github.com/windycom/api/blob/master/bcast/README.md

Details the core methods for event handling (`on`, `off`, `once`, `fire`) and lists the main broadcast events emitted by `windyApi.broadcast` within the Windy API, including their triggers and recommended usage.

```APIDOC
windyApi.broadcast:
  Methods:
    - on(event: string, callback: function): Registers a callback for an event.
    - off(event: string, callback: function): Unregisters a callback for an event.
    - once(event: string, callback: function): Registers a callback that fires only once.
    - fire(event: string, data: any): Emits an event with optional data.

  Main Broadcasts:
    - mapChanged: Triggered after the Leaflet map has been panned or zoomed.
    - paramsChanged: Triggered when a user changes some parameters (overlay, level, date etc...). Do not use this event to start any intensive action since Windy must now load and render all the data. Use `redrawFinished` instead.
    - redrawFinished: Triggered when Windy has successfully loaded and rendered requested data. Use this for triggering your own tasks.
    - metricChanged: Triggered after some of the units (wind, temp, ...) have been changed.
    - rqstOpen, rqstClose, closeAll: Requests to load and open or close lazy loaded plugins.
    - pluginOpened, pluginClosed: Triggered when a 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: Triggered whenever the User Interface has been changed. Information for other UI components to recalculate their respective sizes and adapt themselves to the new layout.
```

--------------------------------

### Windy API Weather Picker (windyApi.picker) Reference

Source: https://github.com/windycom/api/blob/master/picker/README.md

Documentation for the `windyApi.picker` object, which provides functionality for a desktop-only weather picker. It includes methods for programmatic control and event observation, noting that the picker is sensitive to map visibility.

```APIDOC
windyApi.picker:
  .open({ lat: number, lon: number }): Opens the picker at the specified latitude and longitude.
  .close(): Closes the picker.
  .on(eventName: 'pickerOpened' | 'pickerClosed' | 'pickerMoved', callback: Function): Registers a callback function to be invoked when the picker's state changes (opened, closed, or moved).
  .off(eventName: 'pickerOpened' | 'pickerClosed' | 'pickerMoved', callback: Function): Removes a previously registered callback function.
  .once(eventName: 'pickerOpened' | 'pickerClosed' | 'pickerMoved', callback: Function): Registers a callback function that will be invoked only once when the specified picker event occurs.
  .getParams(): Returns an object containing the picker's current coordinates and raw meteorological values at that location.
```

--------------------------------

### Windy API Utilities (windApi.utils) for Meteorological Data Conversion

Source: https://github.com/windycom/api/blob/master/picker/README.md

Explains how to use `windApi.utils` to convert raw meteorological values obtained from forecast models (like ECMWF or GFS) into more human-readable formats. It also describes the common raw data structures for various overlays.

```APIDOC
windApi.utils:
  // Raw meteorological units returned from the weather picker and forecast models:
  // wind: Array [ U, V ], where U and V are wind vectors in m/s.
  // temperature, dewPoint: Temperature in Kelvin (K).
  // rain, rainAccumulation: Rain for a duration of 3 hours or the selected accumulation period in millimeters (mm).
  // waves, swell: Array [ U, V, size ] where U and V are direction vectors and wave size is in meters (m). Period in seconds is computed as Math.sqrt( U * U + V * V ).

  .wind2obj(values: [U: number, V: number]): Converts wind vectors [U, V] (m/s) into an object with magnitude and direction.
    Returns: { dir: number, wind: number } // dir in degrees, wind in m/s
  .wave2obj(values: [U: number, V: number, size: number]): Converts wave vectors [U, V] and size (m) into an object with direction, size, and period.
    Returns: { dir: number, size: number, period: number } // dir in degrees, size in m, period in seconds
```

--------------------------------

### Windy API Overlay Instance Value Conversion Methods

Source: https://github.com/windycom/api/blob/master/picker/README.md

Describes how to use `convertNumber` and `convertValue` methods available on respective `overlays` instances to convert meteorological values to the user's selected metrics, either as a raw number or a formatted string including the unit.

```APIDOC
overlays.overlayInstance:
  .convertNumber(num: number): Recalculates a numerical value to the user's selected metric and returns it as a number.
    Example: overlays.wind.convertNumber(10) // returns 19 (if user's unit is knots)
  .convertValue(num: number): Recalculates a numerical value to the user's selected metric and returns it as a formatted string, including the metric name.
    Example: overlays.wind.convertValue(10) // returns "19kt" (if user's unit is knots)
```

--------------------------------

### Windy API Overlays - Wind Metric Management

Source: https://github.com/windycom/api/blob/master/metrics/README.md

Describes the properties and methods available on the `windyApi.overlays.wind` object for managing its metric, including reading the current value, listing allowed values, and setting a new value.

```APIDOC
windyApi.overlays.wind:
  metric: string (read-only)
  listMetrics(): array<string>
  setMetric(metric: string): void
    metric: The new metric value to set.
```

--------------------------------

### Windy API Store Reference

Source: https://github.com/windycom/api/blob/master/parameters/README.md

Reference for `windyAPI.store` methods and available parameters for configuring the Windy map. `windyAPI.store` is a key-value store for map state and also an Event Emitter, allowing observation of parameter changes.

```APIDOC
windyAPI.store:
  Description: Key-value store for Windy map state, also an Event Emitter.
  Methods:
    get(key: string): any
      Description: Reads a value from the store.
    set(key: string, value: any): void
      Description: Modifies a value in the store.
    getAllowed(key: string): string[]
      Description: Returns an array of allowed values for a given key.
    on(event: string, listener: Function): void
      Description: Registers an event listener for changes.
    off(event: string, listener: Function): void
      Description: Removes an event listener.
    once(event: string, listener: Function): void
      Description: Registers a one-time event listener.
  Properties (Keys):
    overlay: string
      Description: Color weather overlay.
      Example values: "rainAccu"
    level: string
      Description: Level used for actual displayed overlay or isolines.
      Note: Use store.get('availLevels') to get available levels for current product/overlay.
      Example values: "850h"
    availLevels: string[]
      Description: List of levels available for the current combination of product and overlay.
    acTime: string
      Description: Accumulated time.
    timestamp: number
      Description: Timestamp of actual weather moments.
    isolines: boolean
      Description: Isolines displayed over the map.
    product: string
      Description: Set of weather data (e.g., weather model).
    particlesAnim: 'on' | 'off'
      Description: Animation of wind/waves particles.
    graticule: boolean
      Description: Display the graticule over the map.
    latlon: boolean
      Description: Display lat/lon values on the weather picker.
    englishLabels: boolean
      Description: Show English map labels instead of localized labels.
    lang: string
      Description: Desired language for Windy. Default is 'auto' (browser settings).
    hourFormat: '12h' | '24h'
      Description: Time format.
    numDirection: boolean
      Description: Display directions in Weather picker as a number or string (e.g., NW).
    favOverlays: string[]
      Description: List of overlays displayed in the overlays menu.
      Note: Always create a new array when modifying this list as the store cannot compare arrays directly.
```

--------------------------------

### CSS Styling for Windy Map Container

Source: https://github.com/windycom/api/blob/master/parameters/index.html

This CSS rule targets an HTML element with the ID 'windy' and sets its width to 100% and height to 300 pixels. This is typically used to define the display area for an embedded map or visualization, ensuring it takes full available width and a fixed height.

```css
#windy { width: 100%; height: 300px; }
```

--------------------------------

### Basic CSS for Windy Map Container

Source: https://github.com/windycom/api/blob/master/navigation/index.html

This CSS rule targets an HTML element with the ID 'windy' and sets its width to 100% of its parent container and its height to 300 pixels. This is essential for displaying the Windy map correctly within a defined area on a webpage.

```CSS
#windy { width: 100%; height: 300px; }
```

--------------------------------

### CSS Styling for #windy Container

Source: https://github.com/windycom/api/blob/master/metrics/index.html

This CSS rule targets an HTML element with the ID 'windy' and sets its width to fill 100% of its parent container and its height to a fixed 300 pixels. This is essential for properly displaying the Windy map or any other content within this specific container.

```CSS
#windy { width: 100%; height: 300px; }
```

--------------------------------

### CSS Styling for Windy Map Container

Source: https://github.com/windycom/api/blob/master/hello-world/index.html

This CSS rule targets an HTML element with the ID 'windy' and sets its width to 100% of its parent container and its height to a fixed 300 pixels. This is commonly used to ensure a map or interactive visualization fits well within a webpage layout.

```CSS
#windy { width: 100%; height: 300px; }
```

--------------------------------

### CSS Styling for #windy Container

Source: https://github.com/windycom/api/blob/master/picker/index.html

This CSS rule targets an HTML element with the ID 'windy' and sets its width to 100% of its parent container and its height to a fixed 300 pixels. This is a common pattern for embedding responsive map components or other visual elements that require specific dimensions.

```CSS
#windy { width: 100%; height: 300px; }
```

--------------------------------

### Style Windy Map Container with CSS

Source: https://github.com/windycom/api/blob/master/bcast/index.html

This CSS rule targets an HTML element with the ID 'windy' and sets its width to 100% and height to 300 pixels. This styling is essential for ensuring the map component has a defined area to render within the web page, preventing it from collapsing or not displaying properly.

```CSS
#windy { width: 100%; height: 300px; }
```

--------------------------------

### CSS Styling for #windy Element Dimensions

Source: https://github.com/windycom/api/blob/master/boat-tracker/index.html

This CSS rule targets an HTML element with the ID 'windy' and sets its width to 100% of its parent container and its height to a fixed 300 pixels. This is typically used to define the display area for embedded content like maps or charts.

```css
#windy { width: 100%; height: 300px; }
```
Tokens:
Raw