API Documentation

Authentication

All API requests require an API key. Pass it via header or query parameter:

# Header (recommended)
curl -H "X-API-Key: wl_live_your_key" https://weatherlens.dev/api/v1/forecast?lat=28.38&lon=-81.57

# Query parameter
curl "https://weatherlens.dev/api/v1/forecast?lat=28.38&lon=-81.57&key=wl_live_your_key"

Get your free API key at /dashboard.

Rate Limits

Daily limits reset at midnight UTC. When a limit is hit, the API returns 429 Too Many Requests with details about your usage and the reset time.

Base URL

https://weatherlens.dev/api/v1

All responses are JSON. Successful responses return HTTP 200. Errors include an error field.

GET /forecast

Get weather forecasts for a location.

Parameters

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://weatherlens.dev/api/v1/forecast?lat=28.3772&lon=-81.5707&days=7"

{
  "location": { "lat": 28.3772, "lon": -81.5707 },
  "forecast": [
    {
      "date": "2025-01-15",
      "temperature": { "highF": 78, "lowF": 56, "avgF": 67 },
      "precipitation": { "probabilityPct": 20, "amountIn": 0.02 },
      "wind": { "speedMph": "8-12", "description": "E winds 8 to 12 mph", "direction": "E" },
      "conditions": {
        "code": 2,
        "description": "Partly Cloudy",
        "emoji": "⛅",
        "forecast": "Partly cloudy with a 20% chance of showers"
      },
      "uvIndex": 6,
      "humidityPct": 62
    }
  ],
  "sources": ["nws", "open_meteo"],
  "usage": { "today": 42, "limit": 100 }
}

Data Sources

US locations (lat 24-50, lon -130 to -60) use the National Weather Service for days 1-7, blended with Open-Meteo for days 8-16. International locations use Open-Meteo exclusively.

GET /climate

Get Gaussian kernel climate normals for a location.

Parameters

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://weatherlens.dev/api/v1/climate?lat=28.38&lon=-81.57&date=2025-07-04"

{
  "location": { "lat": 28.38, "lon": -81.57 },
  "climate": [
    {
      "month": 7, "day": 4,
      "avgHighF": 92.3, "avgLowF": 74.1,
      "avgPrecipIn": 0.31, "avgPrecipHours": 2.4,
      "avgWindMph": 7.8, "avgHumidityPct": 73,
      "avgUvIndex": 11.2
    }
  ]
}

Climate normals are computed weekly using a Gaussian kernel (σ=3, ±7 day window) on 5 years of historical data with 15%/year recency weighting.

GET /accuracy

Get forecast accuracy scores broken down by source, month, and lead-time bucket.

Parameters

Scoring

Accuracy is measured by comparing archived forecast snapshots against observed actuals. Composite score: temperature 40% + precipitation 35% + condition match 25%. Lead-time buckets: 1day, 2-3day, 4-7day, 8-16day.

GET /historical

Get observed historical weather data. Pro only

Parameters

Example

curl -H "X-API-Key: YOUR_PRO_KEY" \
  "https://weatherlens.dev/api/v1/historical?lat=28.38&lon=-81.57&start=2024-01-01&end=2024-01-31"

Error Codes

Client Libraries

No SDK required — WeatherLens is a simple REST API that works with any HTTP client. Here are examples in popular languages:

JavaScript / Node.js

const res = await fetch(
  "https://weatherlens.dev/api/v1/forecast?lat=28.38&lon=-81.57",
  { headers: { "X-API-Key": process.env.WEATHERLENS_KEY } }
);
const data = await res.json();
console.log(data.forecast[0].temperature.highF); // 78

Python

import requests

resp = requests.get(
    "https://weatherlens.dev/api/v1/forecast",
    params={"lat": 28.38, "lon": -81.57, "days": 7},
    headers={"X-API-Key": "wl_live_your_key"},
)
data = resp.json()
print(data["forecast"][0]["temperature"]["highF"])  # 78

cURL

curl -s -H "X-API-Key: wl_live_your_key" \
  "https://weatherlens.dev/api/v1/forecast?lat=28.38&lon=-81.57" | jq .