API Reference

The WeatherApex API answers a question raw forecast data cannot: is this a good day for what I am planning? We take hourly and daily forecasts from national weather models, weight them against the activity you care about, and return a score you can act on.

Conventions

• • All requests are GET; parameters go in the query string.
• • Responses are JSON, UTF-8. Successful calls return { "success": true, "data": { ... } }.
• • Errors return a non-2xx status and { "error": "...", "detail": "..." }.
• • Dates are YYYY-MM-DD. Times are local to the city, in 24-hour form.
• • Temperatures are Celsius, wind is km/h, rainfall is millimetres.

1. 1Create a free account and generate an API key below.
2. 2Send the key in the X-API-Key header on every request.
3. 3Call an endpoint and read response.data.

curl "https://api.weatherapex.com/api/v1/trips/plan/?city=barcelona&start=2026-08-03&end=2026-08-06" \
  -H "X-API-Key: wv_live_YOUR_KEY_HERE"

Keep the key on your server. Anyone who can read your front-end bundle can read a key you put in it.

Every v1 request needs an API key in the X-API-Key header. Keys look like wv_live_… and are shown once, at creation — we store only a hash, so we cannot recover a lost key. Generate a new one instead.

X-API-Key: wv_live_YOUR_KEY_HERE

Generate a key right here. Choose only the features you need — you can create another key later for anything else.

Two limits apply to every key: a request rate, and a call quota. The free plan's quota is a lifetime total, not a daily one — 100 calls to build and test an integration.

Response headers

Every authenticated response tells you where you stand:

X-RateLimit-Limit:      5000      # your plan's quota
X-RateLimit-Remaining:  4873      # calls left
X-RateLimit-Plan:       starter   # plan on this key

Exceeding either limit returns 429. Back off and retry rather than looping — repeated 429s do not reset the window.

Scores every day between two dates for one city, so you can tell a traveller which days are worth going out and what to do on each. Beyond the forecast window the API falls back to a seasonal estimate built from 20 years of records — data_source tells you which you received.

Query parameters

Example request

curl "https://api.weatherapex.com/api/v1/trips/plan/?city=barcelona&start=2026-08-03&end=2026-08-06" \
  -H "X-API-Key: wv_live_YOUR_KEY_HERE"

Example response

{
  "success": true,
  "data": {
    "city": "Barcelona",
    "country": "Spain",
    "start_date": "2026-08-03",
    "end_date": "2026-08-06",
    "data_source": "forecast",
    "overall_score": 7.8,
    "best_day": "2026-08-05",
    "worst_day": "2026-08-06",
    "days": [
      {
        "date": "2026-08-03",
        "score": 8.5,
        "weather_code": 0,
        "temp_max": 28.4,
        "temp_min": 19.1,
        "rain_probability": 5,
        "wind_kmh": 12.0,
        "recommended_activity": "beach_water",
        "day_parts": {
          "morning":   { "temp": 21.3, "rain_probability": 2,  "wind_kmh": 8.1 },
          "afternoon": { "temp": 28.4, "rain_probability": 5,  "wind_kmh": 12.0 },
          "evening":   { "temp": 24.0, "rain_probability": 3,  "wind_kmh": 9.4 }
        }
      }
    ],
    "packing_suggestions": [
      { "item": "SPF 50 Sunscreen", "reason": "Strong sun on 3 of 4 days" }
    ]
  }
}

Response fields

Rates how risky the weather is for an outdoor event. A wedding and a marathon are not troubled by the same conditions, sotypechanges how rain, wind, heat and humidity are weighted.

Query parameters

Example request

curl "https://api.weatherapex.com/api/v1/events/risk/?city=london&date=2026-08-15&type=wedding&time=18" \
  -H "X-API-Key: wv_live_YOUR_KEY_HERE"

Example response

{
  "success": true,
  "data": {
    "city": "London",
    "country": "United Kingdom",
    "event_type": "wedding",
    "event_date": "2026-08-15",
    "event_time": "18:00",
    "risk_score": 3.2,
    "risk_level": "low",
    "weather_code": 2,
    "rain_probability": 15,
    "wind_kmh": 12.0,
    "temperature_c": 21.5,
    "humidity_pct": 62,
    "recommendation": "Conditions look good — an outdoor ceremony should be fine.",
    "alternate_dates": [
      {
        "date": "2026-08-16",
        "risk_score": 2.1,
        "rain_probability": 8,
        "wind_kmh": 9.0,
        "temperature_c": 22.8,
        "weather_code": 0
      }
    ]
  }
}

Response fields

Errors carry a human-readable error and, where it helps, a detail you can show a user. Branch on the status code and oncode where present — never on message text, which may be reworded.

Country sent instead of a city

Weather is not uniform across a country, so a single score for one would be misleading. We refuse it and hand you cities to offer the user instead:

{
  "error": "Please enter a city, not a country",
  "detail": "Pakistan is a country, not a city — and weather is different in
             every city within it, so a single score would be misleading.",
  "kind": "country",
  "place": "Pakistan",
  "suggestions": [
    { "name": "Karachi",   "slug": "karachi",   "country": "Pakistan" },
    { "name": "Lahore",    "slug": "lahore",    "country": "Pakistan" },
    { "name": "Islamabad", "slug": "islamabad", "country": "Pakistan" }
  ]
}