API documentation

One endpoint turns the weather into a decision for an activity at a place and date.

Quick start

1. Create a free account, verify your email and copy your API key from the dashboard.
2. Call https://api.weatherai.io/v1/decide with a location and an activity.

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.weatherai.io/v1/decide?location=London&activity=running&when=tomorrow"

const r = await fetch(
  "https://api.weatherai.io/v1/decide?location=London&activity=running&when=tomorrow",
  { headers: { "X-API-Key": process.env.WEATHERAI_KEY } });
const d = await r.json();
console.log(d.verdict, d.score, d.summary);

import os, requests

r = requests.get("https://api.weatherai.io/v1/decide",
    params={"location": "London", "activity": "running", "when": "tomorrow"},
    headers={"X-API-Key": os.environ["WEATHERAI_KEY"]}, timeout=10)
d = r.json()
print(d["verdict"], d["score"], d["summary"])

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("WEATHERAI_KEY"));
var json = await http.GetStringAsync(
    "https://api.weatherai.io/v1/decide?location=London&activity=running&when=tomorrow");
Console.WriteLine(json);

Authentication

Send your key in the X-API-Key header (Authorization: Bearer wai_… also works). ?key= works too, but headers keep keys out of logs and browser history. Keys start with wai_. You can create up to 5 keys and revoke any of them in the dashboard; a revoked key stops working at once. Keep keys on your server; never put them in public web pages or apps.

GET /v1/decide

Response

{
  "location": { "name": "London", "region": "City of London, Greater London", "country": "United Kingdom",
                "lat": 51.52, "lon": -0.11, "tz_id": "Europe/London", "localtime": "2026-10-17 21:04" },
  "activity": "running",
  "date": "2026-10-18",
  "verdict": "good",
  "score": 82,
  "best_windows": [ { "start": "2026-10-18 07:00", "end": "2026-10-18 10:00", "score": 91 } ],
  "risks": [ { "type": "rain", "severity": "high", "from": "2026-10-18 14:00", "to": "2026-10-18 18:00",
               "detail": "1.2 mm of rain" } ],
  "summary": "Good conditions for a run in London; best 07:00–10:00. Watch for rain from 14:00.",
  "data": { "temp_min": 8.1, "temp_max": 14.0, "feels_like_min": 6.0, "feels_like_max": 12.5,
            "rain_chance_max": 70, "precip_total_mm": 4.8, "wind_max_kph": 30, "gust_max_kph": 45,
            "uv_max": 3, "cloud_avg": 52, "humidity_avg": 78, "sunrise": "07:24", "sunset": "18:07",
            "units": "metric" },
  "billing": { "charged": "free", "cost_gbp": "0.0000", "free_remaining": 993, "balance_gbp": "4.2000" }
}

GET /v1/best-day

Which of the next days is best? One call compares up to 14 days for an activity and ranks them. It costs one call, however many days it compares.

GET https://api.weatherai.io/v1/best-day?location=London&activity=bbq&days=7

{
  "location": { "name": "London", "country": "United Kingdom", … },
  "activity": "outdoor-event",
  "days_checked": 7,
  "summary": "Best day for an outdoor event in London: Saturday 17 October (great, 92), 12:00–19:00.",
  "best": { "date": "2026-10-17", "weekday": "Saturday", "verdict": "great", "score": 92,
            "best_window": { "start": "2026-10-17 12:00", "end": "2026-10-17 19:00", "score": 92 },
            "top_risks": [], "summary": "Great conditions for an outdoor event in London; best 12:00–19:00." },
  "days": [ { "date": "2026-10-14", "weekday": "Wednesday", "verdict": "fair", "score": 61, … }, … ],
  "billing": { … }
}

Activities

The list is also available as JSON, free and without a key: GET https://api.weatherai.io/v1/activities.

How scoring works

Every forecast hour starts at 100 and loses points for each thing outside the activity's comfortable range: the "feels like" temperature, the chance and amount of rain, thunderstorms, snow, wind and gusts, UV, cloud, humidity, visibility, darkness (or daylight, for stargazing), moonlight, ice (near-freezing with rain or snow, for driving, roofing and walking) and a minimum air temperature for work that needs it (concrete, paint). Hours scoring 60 or more are good; runs of good hours at least as long as the activity needs become best_windows. The rules are deliberately simple and the same for every customer, so answers are explainable.

Hours that have already passed at the location are never recommended.

Errors

Errors return JSON {"error": {"code": "…", "message": "…"}}. Only a successful 200 answer is charged.

Billing and limits

• 1,000 free calls every calendar month (UTC), then £0.0012 per call from prepaid credit, VAT included. See pricing.
• /v1/decide and /v1/best-day cost one call each when they succeed, and so do the MCP tools decide and best_day. Everything else is free.
• Every answer carries headers X-Free-Calls-Remaining, X-Credit-Balance-GBP and X-Call-Cost-GBP.
• Up to 20 requests per second per account.
• Answers for the same place are cached for up to 10 minutes on our side; caching on yours for 10–30 minutes is fine and saves calls.

Other endpoints (free)

MCP server (AI agents)

weatherAI.io is also an MCP server, so assistants and agents can use it as tools without any code. Server URL:

https://api.weatherai.io/mcp

It speaks the Streamable HTTP transport. Authenticate with your API key as the X-API-Key header (or Authorization: Bearer wai_…). For apps that only take a URL, add it as ?key=wai_…, and treat that URL as a secret.

Claude Code

claude mcp add --transport http weatherai https://api.weatherai.io/mcp --header "X-API-Key: wai_YOUR_KEY"

Claude (claude.ai and the desktop app)

Settings → Connectors → Add custom connector, with the URL https://api.weatherai.io/mcp?key=wai_YOUR_KEY.

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "weatherai": {
      "url": "https://api.weatherai.io/mcp",
      "headers": { "X-API-Key": "wai_YOUR_KEY" }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "weatherai": {
      "type": "http",
      "url": "https://api.weatherai.io/mcp",
      "headers": { "X-API-Key": "wai_YOUR_KEY" }
    }
  }
}

Menus and file locations change between versions of these apps; if a step doesn't match, look for "MCP servers" or "connectors" in the app's settings.

Without MCP

Give your agent the OpenAPI spec or this function definition. The summary field is meant to be repeated to the user as it is.

{
  "name": "weather_decision",
  "description": "Decide whether and when to do an outdoor activity at a place and date. Returns verdict, score 0-100, best time windows, risks and a one-line summary.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City, 'lat,lon', postcode or zip code" },
      "activity": { "type": "string", "enum": ["running", "cycling", "outdoor-event", "beach", "laundry-drying", "stargazing", "hiking", "golf", "tennis", "dog-walking", "gardening", "fishing", "sailing", "drone-flying", "exterior-painting", "concrete-pour", "roofing", "crop-spraying", "outdoor-work", "driving"] },
      "when": { "type": "string", "description": "today, tomorrow or yyyy-MM-dd (up to 13 days ahead)" }
    },
    "required": ["location", "activity"]
  }
}