# Weather API
> Real-time weather: current conditions, multi-day forecast, historical weather, marine/wave forecast, astronomy (sun/UV), air quality, geocoding and timezone.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/weather-api/..."
```

## Pricing
- **Free** (Free) — 100 calls/Mo, 1 req/s
- **Basic** ($15/Mo) — 25,000 calls/Mo, 10 req/s
- **Pro** ($49/Mo) — 100,000 calls/Mo, 20 req/s
- **Mega** ($149/Mo) — 500,000 calls/Mo, 50 req/s

## Endpoints

### Forecast

#### `GET /v1/current` — Current weather

**Parameters:**
- `q` (query, required, string) — City name or 'lat,lon' Example: `Berlin`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/weather-api/v1/current?q=Berlin"
```

**Response:**
```json
{
    "data": {
        "units": {
            "rain": "mm",
            "time": "iso8601",
            "is_day": "",
            "showers": "mm",
            "interval": "seconds",
            "snowfall": "cm",
            "cloud_cover": "%",
            "pressure_msl": "hPa",
            "weather_code": "wmo code",
            "precipitation": "mm",
            "temperature_2m": "°C",
            "wind_gusts_10m": "km/h",
            "wind_speed_10m": "km/h",
            "surface_pressure": "hPa",
            "wind_direction_10m": "°",
            "apparent_temperature": "°C",
            "relative_humidity_2m": "%"
        },
        "current": {
            "time": "2026-05-29T20:15",
            "is_day": true,
            "temp_c": 25.7,
            "rain_mm": 0,
            "humidity": 24,
            "wind_kmh": 3.8,
            "condition": {
                "code": 3,
                "text": "Overcast"
            },
            "precip_mm": 0,
            "cloud_cover": 98,
            "snowfall_cm": 0,
            "feels_like_c": 23.6,
            "pressure_msl": 1019.6,
            "wind_dir_deg": 311,
            "wind_gust_kmh": 21.2
        },
        "location": {
            "name": "Berlin",
            "region": "State of Berlin",
            "country": "Germany",
            "latitude": 52.52437,
            "timezone": "Europe/Berlin",
            "elevation": 46,
            "longitude": 13.41053,
            "country_code": "DE",
            "utc_of
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/forecast` — Multi-day forecast

**Parameters:**
- `q` (query, required, string) — City name or 'lat,lon' Example: `Berlin`
- `days` (query, optional, string) — Number of days (1-16) Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/weather-api/v1/forecast?q=Berlin&days=5"
```

**Response:**
```json
{
    "data": {
        "units": {
            "daily": {
                "time": "iso8601",
                "sunset": "iso8601",
                "sunrise": "iso8601",
                "uv_index_max": "",
                "weather_code": "wmo code",
                "precipitation_sum": "mm",
                "temperature_2m_max": "°C",
                "temperature_2m_min": "°C",
                "wind_gusts_10m_max": "km/h",
                "wind_speed_10m_max": "km/h",
                "apparent_temperature_max": "°C",
                "apparent_temperature_min": "°C",
                "wind_direction_10m_dominant": "°",
                "precipitation_probability_max": "%"
            },
            "hourly": {
                "time": "iso8601",
                "weather_code": "wmo code",
                "precipitation": "mm",
                "temperature_2m": "°C",
                "wind_speed_10m": "km/h",
                "wind_direction_10m": "°",
                "relative_humidity_2m": "%",
                "precipitation_probability": "%"
            }
        },
        "hourly": {
            "time": [
                "2026-05-29T00:00",
                "2026-05-29T01:00",
                "2026-05-29T02:00",
                "2026-05-29T03:00",
                "2026-05-29T04:00",
                "2026-05-29T05:00",
                "2026-05-29T06:00",
                "2026-05-29T07:00",
                "2026-05-29T08:00",
                "2026-05-29T09:00",
              
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/history` — Historical weather

**Parameters:**
- `q` (query, required, string) — City name or 'lat,lon' Example: `Berlin`
- `dt` (query, required, string) — Start date YYYY-MM-DD Example: `2024-01-01`
- `end_dt` (query, optional, string) — End date YYYY-MM-DD Example: `2024-01-07`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/weather-api/v1/history?q=Berlin&dt=2024-01-01&end_dt=2024-01-07"
```

**Response:**
```json
{
    "data": {
        "days": [
            {
                "date": "2024-01-01",
                "sunset": "2024-01-01T17:02",
                "sunrise": "2024-01-01T09:17",
                "condition": {
                    "code": 53,
                    "text": "Moderate drizzle"
                },
                "avg_temp_c": 5.3,
                "max_temp_c": 7.3,
                "min_temp_c": 3.4,
                "rain_sum_mm": 1.8,
                "max_wind_kmh": 19.7,
                "precip_sum_mm": 1.8,
                "snowfall_sum_cm": 0
            },
            {
                "date": "2024-01-02",
                "sunset": "2024-01-02T17:03",
                "sunrise": "2024-01-02T09:17",
                "condition": {
                    "code": 73,
                    "text": "Moderate snow fall"
                },
                "avg_temp_c": 4.4,
                "max_temp_c": 6.9,
                "min_temp_c": 2.5,
                "rain_sum_mm": 6.8,
                "max_wind_kmh": 20.2,
                "precip_sum_mm": 7.2,
                "snowfall_sum_cm": 0.28
            },
            {
                "date": "2024-01-03",
                "sunset": "2024-01-03T17:04",
                "sunrise": "2024-01-03T09:16",
                "condition": {
                    "code": 63,
                    "text": "Moderate rain"
                },
                "avg_temp_c": 8.7,
                "max_temp_c": 10.6,
                "min_temp_c": 7.2
…(truncated, see openapi.json for full schema)
```

### Marine

#### `GET /v1/marine` — Marine / wave forecast

**Parameters:**
- `q` (query, required, string) — City name or 'lat,lon' Example: `Berlin`
- `days` (query, optional, string) — Number of days (1-8) Example: `3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/weather-api/v1/marine?q=Berlin&days=3"
```

**Response:**
```json
{
    "data": {
        "days": [
            {
                "date": "2026-05-29",
                "wave_height_max_m": null,
                "wave_period_max_s": null,
                "wind_wave_height_max_m": null,
                "swell_wave_height_max_m": null,
                "wave_direction_dominant_deg": null
            },
            {
                "date": "2026-05-30",
                "wave_height_max_m": null,
                "wave_period_max_s": null,
                "wind_wave_height_max_m": null,
                "swell_wave_height_max_m": null,
                "wave_direction_dominant_deg": null
            },
            {
                "date": "2026-05-31",
                "wave_height_max_m": null,
                "wave_period_max_s": null,
                "wind_wave_height_max_m": null,
                "swell_wave_height_max_m": null,
                "wave_direction_dominant_deg": null
            }
        ],
        "units": {
            "daily": {
                "time": "iso8601",
                "wave_height_max": "m",
                "wave_period_max": "s",
                "wind_wave_height_max": "m",
                "swell_wave_height_max": "m",
                "wave_direction_dominant": "°"
            },
            "current": {
                "time": "iso8601",
                "interval": "seconds",
                "wave_height": "m",
                "wave_period": "s",
                "wave_direction": "°",
                "wind_wave_h
…(truncated, see openapi.json for full schema)
```

### Astronomy

#### `GET /v1/astronomy` — Astronomy (sunrise/sunset/UV)

**Parameters:**
- `q` (query, required, string) — City name or 'lat,lon' Example: `Berlin`
- `dt` (query, optional, string) — Date YYYY-MM-DD (default today) Example: `2026-05-29`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/weather-api/v1/astronomy?q=Berlin&dt=2026-05-29"
```

**Response:**
```json
{
    "data": {
        "date": "2026-05-29",
        "location": {
            "name": "Berlin",
            "region": "State of Berlin",
            "country": "Germany",
            "latitude": 52.52437,
            "timezone": "Europe/Berlin",
            "longitude": 13.41053,
            "country_code": "DE"
        },
        "astronomy": {
            "sunset": "2026-05-29T21:15",
            "sunrise": "2026-05-29T04:52",
            "uv_index_max": 6.65,
            "daylight_duration_s": 58990.75,
            "sunshine_duration_s": 52577.04,
            "uv_index_clear_sky_max": 6.65
        }
    },
    "meta": {
        "timestamp": "2026-05-29T18:17:32.906Z",
        "request_id": "94d90a0a-d10d-4eb8-9c22-28487185fd26"
    },
    "status": "ok",
    "message": "Astronomy retrieved successfully",
    "success": true
}
```

### Air Quality

#### `GET /v1/air-quality` — Air quality (PM2.5/PM10/AQI)

**Parameters:**
- `q` (query, required, string) — City name or 'lat,lon' Example: `Berlin`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/weather-api/v1/air-quality?q=Berlin"
```

**Response:**
```json
{
    "data": {
        "units": {
            "dust": "μg/m³",
            "pm10": "μg/m³",
            "time": "iso8601",
            "ozone": "μg/m³",
            "pm2_5": "μg/m³",
            "us_aqi": "USAQI",
            "interval": "seconds",
            "uv_index": "",
            "european_aqi": "EAQI",
            "carbon_monoxide": "μg/m³",
            "sulphur_dioxide": "μg/m³",
            "nitrogen_dioxide": "μg/m³"
        },
        "location": {
            "name": "Berlin",
            "region": "State of Berlin",
            "country": "Germany",
            "latitude": 52.52437,
            "timezone": "Europe/Berlin",
            "longitude": 13.41053,
            "country_code": "DE"
        },
        "air_quality": {
            "dust": 1,
            "pm10": 9.2,
            "time": "2026-05-29T20:00",
            "ozone": 101,
            "pm2_5": 5.3,
            "us_aqi": 49,
            "uv_index": 0.1,
            "european_aqi": 41,
            "carbon_monoxide": 148,
            "sulphur_dioxide": 1.3,
            "nitrogen_dioxide": 9.2
        }
    },
    "meta": {
        "timestamp": "2026-05-29T18:17:33.994Z",
        "request_id": "7aaa50cd-1111-48b1-a3a3-0bd8c8be7cab"
    },
    "status": "ok",
    "message": "Air quality retrieved successfully",
    "success": true
}
```

### Location

#### `GET /v1/search` — Location search / geocoding

**Parameters:**
- `q` (query, required, string) — City name or 'lat,lon' Example: `Berlin`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/weather-api/v1/search?q=Berlin"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "query": "Berlin",
        "results": [
            {
                "id": 2950159,
                "name": "Berlin",
                "region": "State of Berlin",
                "country": "Germany",
                "latitude": 52.52437,
                "timezone": "Europe/Berlin",
                "elevation": 74,
                "longitude": 13.41053,
                "population": 3426354,
                "country_code": "DE"
            },
            {
                "id": 5083330,
                "name": "Berlin",
                "region": "New Hampshire",
                "country": "United States",
                "latitude": 44.46867,
                "timezone": "America/New_York",
                "elevation": 311,
                "longitude": -71.18508,
                "population": 9367,
                "country_code": "US"
            },
            {
                "id": 4500771,
                "name": "Berlin",
                "region": "New Jersey",
                "country": "United States",
                "latitude": 39.79123,
                "timezone": "America/New_York",
                "elevation": 50,
                "longitude": -74.92905,
                "population": 7590,
                "country_code": "US"
            },
            {
                "id": 4349706,
                "name": "Brunswick",
                "region": "Maryland",
                "country": "United States",
                "la
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/timezone` — Timezone & local time

**Parameters:**
- `q` (query, required, string) — City name or 'lat,lon' Example: `Berlin`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/weather-api/v1/timezone?q=Berlin"
```

**Response:**
```json
{
    "data": {
        "location": {
            "name": "Berlin",
            "region": "State of Berlin",
            "country": "Germany",
            "latitude": 52.52437,
            "elevation": 46,
            "longitude": 13.41053,
            "country_code": "DE"
        },
        "timezone": "Europe/Berlin",
        "localtime": "2026-05-29T20:15",
        "utc_offset_seconds": 7200,
        "timezone_abbreviation": "GMT+2"
    },
    "meta": {
        "timestamp": "2026-05-29T18:17:36.192Z",
        "request_id": "d251de2e-a645-49d9-9693-f7858708385e"
    },
    "status": "ok",
    "message": "Timezone retrieved successfully",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/weather-api
OpenAPI spec: https://www.oanor.com/api/weather-api/openapi.json