repository·master·Indexed 21 days ago
https://github.com/windycom/apiA library built on Leaflet 1.4.x that allows developers to embed Windy.com's weather visualizations into web applications. The API provides tools for managing map parameters via windyAPI.store, handling weather data through a broadcast system, customizing the UI with CSS, and utilizing a weather picker to retrieve and convert raw meteorological data.
on, off, once, and fire methods provided by windyApi.broadcast.You can control the initial state of the Windy map in two ways:
options object during initialization. This is recommended for performance as it can lead to faster loading times.windyAPI.store.set(key, value) to change parameters while the map is already running.Parameters are identified by string identifiers (e.g., overlay can be set to rainAccu, or level can be set to 850h).
To see detailed, color-coded broadcast information in the browser's console, include verbose: true in your startup options object when initializing the Windy API.
// Example startup configuration
const windyApi = new WindyApi({
// ... other options
verbose: true
});The repository provides several practical examples to help you get started with different features:
redrawFinished broadcast is triggered once Windy has successfully loaded and rendered the requested data. This is the recommended event to use for triggering your own custom tasks or UI updates to ensure the data is ready.You can customize the appearance of the Windy map user interface by applying custom CSS. All UI elements are contained within the #windy selector.
Important Constraint: When applying styles, ensure that the Windy logo remains:
1./* Example of targeting the Windy UI container */
#windy {
/* your custom styles here */
}
/* Ensure the logo is not broken by your styles */
#windy .windy-logo {
transform: none !important;
pointer-events: auto !important;
opacity: 1 !important;
}To load the Windy Map, you must first include the Leaflet library and then the Windy API library via the following URL: https://api.windy.com/assets/map-forecast/libBoot.js.
Your HTML must include a <div id="windy"></div> element to serve as the map container. You can use CSS to control the size and position of this container.
In your JavaScript, call windyInit(options, callback) to start the API. The options object requires a key property containing your API key. The callback function is executed once the API is ready, receiving the Windy API instance as its argument.
<!-- 1. HTML Container -->
<div id="windy"></div>
<!-- 2. Load Libraries -->
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
<script src="https://api.windy.com/assets/map-forecast/libBoot.js"></script>
<!-- 3. Initialize -->
<script>
windyInit({
key: 'YOUR_API_KEY'
}, function(windy) {
console.log('Windy API is ready:', windy);
// Use the 'windy' object to interact with the map
});
</script>Each Windy overlay is accessible via the windyApi.overlays module. To manage the units (metrics) of a specific overlay, use the corresponding overlay object.
For example, when working with the wind overlay:
overlays.wind.metric (read-only) to retrieve the current metric.overlays.wind.listMetrics() to retrieve a list of all allowed metrics for that overlay.overlays.wind.setMetric(metric) to update the overlay to a new metric.// Get the current metric for wind
const currentMetric = windyApi.overlays.wind.metric;
// Get all available metrics for wind
const availableMetrics = windyApi.overlays.wind.listMetrics();
// Set the wind metric to a new value
windyApi.overlays.wind.setMetric('new_metric_value');When modifying the favOverlays parameter, you must always provide a new array instance. Because windyAPI.store uses primitive comparison to detect changes, passing the same array reference will not trigger an update.
// Correct way to add an overlay to favorites
const currentFavs = windyAPI.store.get('favOverlays');
windyAPI.store.set('favOverlays', [...currentFavs, 'newOverlayId']);