ol-owm/README.md

Weather layer for OpenLayers and Leaflet using OpenWeatherMap

# ☁️ OL-OWM

**OL-OWM** is a TypeScript library for displaying weather data on **[OpenLayers](https://openlayers.org/)** and **[Leaflet](https://leafletjs.com/)** maps using the **[OpenWeatherMap](https://openweathermap.org/)** API.

## Example
**[Open example](https://star-systems-company.github.io/ol-owm/docs/)**

---


## 📦 Installation

```bash
npm install ol-owm
```

---


## 📌 Features

- 🗺️ Support for **OpenLayers** and **Leaflet**
- 🌍 Automatic OpenWeather data loading by tile
- 🌡️ Display of temperature, wind, and city names
- 🖱️ Detailed weather info on double-click
- 💨 Wind animation with optional wind layer
- 🧩 Layer switching and legend rendering

---


## ⚙️ Options

| Parameter        | Type       | Description                                                               |
| ---------------- | ---------- | ------------------------------------------------------------------------- |
| `lang`           | `en \| ru` | Language of the weather data                                              |
| `legend`         | `boolean`  | Whether to show a legend when switching layers                            |
| `legendElement`  | `string`   | DOM selector or element for rendering legend                              |
| `windDataURL`    | `string`   | URL for wind data JSON                                                    |
| `windProperties` | `object`   | Wind layer style configuration (e.g., color, paths, velocity scale, etc.) |

---


## 🧪 Examples

### 🔹 OpenLayers Example

```ts
import Map from "ol/Map";
import View from "ol/View";
import TileLayer from "ol/layer/Tile";
import OSM from "ol/source/OSM";
import { fromLonLat } from "ol/proj";
import { OpenLayersWeather } from "ol-owm";

const map = new Map({
  target: "map-ol",
  layers: [new TileLayer({ source: new OSM() })],
  view: new View({
    center: fromLonLat([30.52, 50.45]), // Kyiv
    zoom: 6,
  }),
});

const weather = new OpenLayersWeather(map, "YOUR_OWM_API_KEY", {
  lang: "en",
  legend: true,
  legendElement: "#map-ol",
  windDataURL: "https://<example.com/.../wind.json>",
  windProperties: {
    color: "red",
  },
});

weather.show();

// Toggle wind layer
document.getElementById("toggle-wind")?.addEventListener("click", () => {
  weather.toggleWind();
});
```

### 🔸 Leaflet Example

```ts
import L from "leaflet";
import { LeafletWeather } from "ol-owm";

const map = L.map("map-leaflet").setView([50.4501, 30.5234], 7);

L.tileLayer("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", {
  maxZoom: 18,
  attribution: "&copy; OpenStreetMap contributors",
}).addTo(map);

const weather = new LeafletWeather(map, "YOUR_OWM_API_KEY", {
  lang: "en",
  legend: true,
  legendElement: "#map-leaflet",
  windDataURL: "https://<example.com/.../wind.json>",
  windProperties: {
    color: "blue",
  },
});

weather.show();

// Toggle wind layer
document.getElementById("toggle-wind")?.addEventListener("click", () => {
  weather.toggleWind();
});
```

---


## 🔧 Public API (OpenLayersWeather)

### Methods

| Method          | Description                                                          |
| --------------- | -------------------------------------------------------------------- |
| `show()`        | Initializes and displays weather data                                |
| `hide()`        | Removes weather layer, popup and event listeners                     |
| `toggleWind()`  | Toggles wind layer on/off using specified windDataURL                |
| `setLayer(key)` | Switches the weather tile layer by predefined key (`null` to remove) |
| `status()`      | Returns `true` if weather layer is currently active                  |
| `layers()`      | Returns an array of available weather tile layers                    |

### Properties

| Property     | Type             | Description                       |
| ------------ | ---------------- | --------------------------------- |
| `activeKey`  | `string \| null` | Currently active weather tile key |
| `activeWind` | `boolean`        | Whether wind layer is active      |

---


## 📄 License

MIT © [STAR Systems](https://github.com/STAR-Systems-Company)