Weathry API

Save your locations, then get hourly and daily weather forecasts for them. Everything is JSON over HTTPS, and the same features are available to AI assistants through MCP.

Base URL https://api.weathry.com   ·   Format application/json

Quick start

1. Get an API key: email info@weathry.com.
2. Save a location with your own numeric ID.
3. Ask for its forecast.

# 1. Save a location
curl -X POST https://api.weathry.com/location \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": 42, "location": "New York City", "latitude": 40.7128, "longitude": -74.0060}'

# 2. Get its daily forecast
curl https://api.weathry.com/forecast/daily/location/42 \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

Send your API key as a Bearer token on every request. Keep it secret: anyone with the key can use your account and your tokens.

Authorization: Bearer YOUR_API_KEY

A missing or wrong key returns 401 with "status": "unauthorized".

Locations

Forecasts are always for a saved location. You choose each location’s ID (a positive whole number), so you can use the same IDs as your own system. Managing locations is free and doesn’t use tokens.

Location body (create and update)

{
  "id": 42,
  "location": "New York City",
  "latitude": 40.7128,
  "longitude": -74.0060
}

CSV upload format

Send the file as the request body. One location per line, four values separated by a pipe |: ID, name, latitude, longitude. Up to 1,000 rows per upload. Existing IDs are updated and new IDs are added.

42|New York City|40.7128|-74.0060
43|Harbour Front|-33.8568|151.2153

curl -X POST https://api.weathry.com/location/upload_csv \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-binary @locations.csv

Forecasts

Each forecast request uses one token. Times are given in UTC and in the location’s local time zone.

Query parameters

All optional. Values are not case-sensitive.

curl "https://api.weathry.com/forecast/location/42?unit=I&tod=L" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

The location, its time zone and the model run, followed by a forecasts list with one entry per hour (or per day). Hourly forecasts cover about 8 days and daily forecasts 14 days. This example is a real hourly response, shortened to one hour.

{
  "location_id": 42,
  "location": "New York City",
  "tzid": "America/New_York",
  "modelrun": "29AUG202600Z",
  "latitude": 40.7128,
  "longitude": -74.006,
  "forecasts": [
    {
      "day": 7,
      "weekday": "Sat",
      "fcst_utc": "2026-08-29 17:00",
      "fcst_loc": "2026-08-29 13:00",
      "tmp_cel": 25,
      "tmp_fahr": 77,
      "rel_humidity": 28,
      "comf_cel": 25,
      "comf_fahr": 77,
      "ws_kmh": 9,
      "ws_mph": 5,
      "ws_kts": 5,
      "wind_dir": 344.27,
      "wind_dir_desc": "NNW",
      "gust_kmh": 12,
      "gust_mph": 7,
      "gust_kts": 6,
      "beaufort": "Light Breeze",
      "cloud_perc": 2,
      "precip_mm": 0,
      "precip_in": 0,
      "pop_perc": 0,
      "sunrise": "06:20",
      "sunset": "19:32",
      "light_dark": "L",
      "pmsl": 102275,
      "uv_idx": 7,
      "uv_desc": "high",
      "uv_col": "orange",
      "conditions": "Sunny. Mild",
      "icon": "sunny"
    }
  ]
}

Forecast fields

Daily forecasts give tmp_max_*, tmp_min_*, comf_max_* and comf_min_* instead of single temperatures, give the local date in fcst_loc, and leave out rel_humidity, light_dark and pmsl.

Activity ratings

Add activity to a forecast request to rate how suitable the weather is for that activity. Each hour (or day) then includes act_rat, a number from 0 to 5, and act_rat_desc, its label. The rating looks at wind, gusts, rain and temperature.

Supported today: golf. More activities will be added.

curl "https://api.weathry.com/forecast/location/42?activity=golf&tod=L" \
  -H "Authorization: Bearer YOUR_API_KEY"

Tokens and plans

Weathry is prepaid. Each forecast request, through the API or MCP, uses one token. Requests that fail with a server error don’t use a token. Subscriptions are paid on the 1st of each month, with the first month pro rata for the days left. Pay-as-you-go tokens cost USD 0.005 each (top-ups from USD 5) and expire 12 months after purchase. Subscribers top up at their plan’s rate. Subscription tokens, and top-ups bought on a subscription, expire at the end of the calendar month (UTC). Tokens that expire soonest are used first. Prices exclude tax. See pricing.

curl https://api.weathry.com/tokens \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "billing": "prepaid",
  "tokens_left": 762590,
  "grace_until": "",
  "debt": 0,
  "grants": [
    {
      "grant_id": 412,
      "source": "subscription",
      "tokens": 2000000,
      "remaining": 712590,
      "expires_at": "2026-12-01 00:00:00",
      ...
    }
  ]
}

tokens_left is live. Each purchase’s remaining can be a few seconds behind. All times are UTC.

Running out of tokens

Every forecast response tells you how many tokens you have left in the X-Tokens-Remaining header. When you have none, forecast requests return 402 until you buy more. There are no overage charges.

Subscription renewals. If your monthly payment is still going through in the first 3 days of a month, forecasts keep working: you can use up to 25% of your plan’s monthly tokens before the payment arrives. They are taken from the new month’s tokens once it does. If payment doesn’t arrive, requests are refused after the 3rd and the tokens used are taken from your next purchase.

X-Tokens-Remaining: 762590

HTTP/1.1 402 Payment Required
{
  "status": "no_tokens",
  "message": "You have no tokens left. Email info@weathry.com to buy more."
}

MCP for AI assistants

Weathry has a built-in MCP (Model Context Protocol) server, so any AI assistant or agent that supports MCP over HTTP can manage your locations and read forecasts. It uses the same API key and the same tokens.

Server URL https://api.weathry.com/mcp   ·   Transport Streamable HTTP   ·   Header Authorization: Bearer YOUR_API_KEY

{
  "mcpServers": {
    "weathry": {
      "type": "http",
      "url": "https://api.weathry.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Most MCP apps accept this format. Some use different field names; check your app’s MCP settings.

Tools

Errors

Errors return a status code and a JSON body with status and message.

{
  "status": "Not found",
  "message": "No location found for id 99"
}