## Wind API

This spec covers REST endpoint:

### GET

```text
/wind-heights/1.0/forecast
```

The **Wind API** provides wind speed and direction forecasts at specific altitudes above ground level. The API calculates atmospheric pressure levels corresponding to the requested altitude and returns detailed wind and temperature forecasts at 15-minute intervals.

<!-- block-id: overview -->

### Overview

- **Spatial coverage:** Global.
- **Temporal resolution:** 15 minutes.
- **Forecast horizon:** Up to 384 hours (16 days).
- **Level type:** up to 1,000 meters above ground.

<!-- block-id: authentication -->

### Authentication

- **appid** — Your OpenWeather API key (required) to be sent as a query parameter.

<!-- block-id: endpoints -->

### Endpoints

**Get Current Pollen**

**HTTP**

### GET

```text
http://demo.openweathermap.org/wind-heights/1.0/forecast?
```

### Example

```text
http://demo.openweathermap.org/wind-heights/1.0/forecast?lat=40.7128&lon=-74.006&altitude_meters=100&max_hours=2&appid=CLIENT_API_KEY
```

<!-- block-id: params -->

### Query parameters

| Name | Type | **Required** | **Description** |
| --- | --- | --- | --- |
| lat | number | ✓ | Latitude in decimal degrees (-90...90) |
| lon | number | ✓ | Longitude in decimal degrees (-180...180) |
| altitude_meters | number | ✓ | Target altitude above ground level in meters (0 to 1,000) |
| appid | string | ✓ | Open Weather API key |
| max_hours | number | - | Maximum number of hours for forecast data |

### Response (200) — JSON

```json
{
  "latitude": 40.7128,
  "longitude": -74.006,
  "altitude_meters": 100,
  "elevation_meters": 5,
  "target_pressure_hpa": 1001,
  "timestamp": "2025-08-28T11:04:21.528243",
  "step_minutes": 15,
  "forecast_data": [
    {
      "forecast_timestamp": "2025-08-28T00:00:00",
      "wind_1001hPa": {
        "speed": 6.6,
        "direction": 324.6,
        "units": {
          "speed": "m/s",
          "direction": "degrees"
        },
        "height": 1001
      },
      "temperature_1001hPa": {
        "value": 20.34,
        "units": "Celsius",
        "height": 1001
      }
    },
    {
      "forecast_timestamp": "2025-08-28T00:15:00",
      "wind_1001hPa": {
        "speed": 6.33,
        "direction": 324.9,
        "units": {
          "speed": "m/s",
          "direction": "degrees"
        },
        "height": 1001
      },
      "temperature_1001hPa": {
        "value": 20.25,
        "units": "Celsius",
        "height": 1001
      }
    },
    // …hourly steps up to requested/available horizon
}
```

<!-- block-id: descriptions -->

### Field descriptions

- latitude, longitude (number): Echo of the request coordinates.
- altitude_meters (number): Echo of the request altitude meters.
- elevation_meters (number): Ground elevation above sea level for the location
- target_pressure_hpa (number): Atmospheric pressure level corresponding to requested altitude
- timestamp (string): ISO-8601 timestamp, timestamp when the forecast was generated
- step_minutes (number): Time interval between forecast data points
- forecast_data (object of number):
- - forecast_timestamp (string): ISO-8601 timestamp, timestamp for the specific forecast data point
  - wind_[]hPa
  - - speed (float): Wind speed at the specified pressure level
    - direction (float): Wind direction in meteorological convention
    - units (object of number):
    - - speed (string): Unit of measurement for wind speed
      - direction (string): Unit of measurement for wind direction
  - height (number): Pressure level height identifier
  - temperature_[]hPa
  - - value (float): Temperature at the specified pressure level
    - units (string): Unit of measurement for temperature
    - height (number): Pressure level height identifier

<!-- block-id: error -->

### Error handling

| **HTTP** | **Meaning** | **Payload example** |
| --- | --- | --- |
| 400 | Validation error (e.g., missing/invalid required parameter lat, lon, altitude_meters) | {"error":"Missing lat/lon parameters in query"} |
| 401 | Unauthorized (bad appid) | {"cod":401,"message":"Invalid API key"} |
| 429 | Rate limited | {"cod":429,"message":"Too many requests"} |
| 500 | Internal server error | {"cod":500,"message":"Internal error"} |