Weather API

A REST API for current weather, forecasts, geocoding, and air quality — powered by OpenWeatherMap.

Live https://weather-api-rickbrown.vercel.app

🔒 Rate limited

⚡ 15-min cache

🛡 Helmet headers

📍 Coord-based

Endpoints

GET /health Liveness check

Returns server status and uptime. No parameters required.

Request

GET /health

Response

{
  "status": "ok",
  "uptime": 124.8
}

GET /api/weather Current weather by coordinates

Parameter	Required	Description
`lat`	yes	Latitude
`lon`	yes	Longitude
`units`	no	`metric`, `imperial`, or `standard` (default)

Request

GET /api/weather?lat=51.5074&lon=-0.1278&units=metric

Response

{
  "status": 200,
  "speed": "42ms",
  "time": 1625247600,
  "error": null,
  "location": {
    "lat": 51.5074,
    "lon": -0.1278,
    "name": "London",
    "country": "GB",
    "timezone": 3600,
    "sunrise": 1625214000,
    "sunset": 1625271600
  },
  "current": {
    "temp": 20.1,
    "feels_like": 18.4,
    "temp_min": 18.0,
    "temp_max": 22.3,
    "pressure": 1012,
    "humidity": 60,
    "wind_speed": 5.1,
    "wind_deg": 270,
    "clouds": 0
  }
}

GET /api/forecast 5-day / 3-hour forecast by coordinates

Parameter	Required	Description
`lat`	yes	Latitude
`lon`	yes	Longitude
`units`	no	`metric`, `imperial`, or `standard` (default)

Request

GET /api/forecast?lat=51.5074&lon=-0.1278&units=metric

Response

{
  "status": 200,
  "speed": "38ms",
  "error": null,
  "location": { "name": "London", "country": "GB", ... },
  "forecast": [
    {
      "time": 1625250000,
      "temp": 19.8,
      "feels_like": 18.1,
      "description": "scattered clouds",
      "icon": "03d",
      "wind_speed": 4.2,
      "clouds": 40,
      "rain": 0,
      "snow": 0
    },
    ...
  ]
}

GET /api/geocode Convert a city name to coordinates

Parameter	Required	Description
`q`	yes	City name, e.g. `London` or `London,GB`
`limit`	no	Max results, 1–10 (default 5)

Request

GET /api/geocode?q=London

Response

{
  "status": 200,
  "speed": "152ms",
  "error": null,
  "results": [
    {
      "name": "London",
      "lat": 51.5073,
      "lon": -0.1276,
      "country": "GB",
      "state": "England"
    },
    ...
  ]
}

GET /api/air-quality Air quality index and pollutants by coordinates

Parameter	Required	Description
`lat`	yes	Latitude
`lon`	yes	Longitude

AQI scale: 1 = Good · 2 = Fair · 3 = Moderate · 4 = Poor · 5 = Very Poor

Request

GET /api/air-quality?lat=51.5074&lon=-0.1278

Response

{
  "status": 200,
  "speed": "35ms",
  "error": null,
  "location": { "lat": 51.5074, "lon": -0.1278 },
  "air_quality": {
    "aqi": 2,
    "label": "Fair",
    "components": {
      "co": 139.34,
      "no2": 25.08,
      "o3": 63.73,
      "so2": 9.7,
      "pm2_5": 9.72,
      "pm10": 11.33,
      "nh3": 0.37
    }
  }
}

Usage Notes

🔒 Rate Limiting

10 requests per IP per 10 minutes. Exceeding this returns 429 Too Many Requests.

⚡ Caching

Responses are cached in memory for 15 minutes, keyed by coordinates and units.

⚠ Error Format

All errors return a JSON body with a descriptive error field and appropriate HTTP status code.

🌍 Units

metric = °C / m/s · imperial = °F / mph · standard = K / m/s