Quickstart

1. Get an API key

Go to console.weather-ruse.com, create an account, and generate a key. Keys are prefixed wr-. Copy it — it is only shown once.

2. First request — single variable point forecast

export WR_KEY="wr-<your-key>"

curl -s -H "Authorization: Bearer $WR_KEY" \
  "https://api.weather-ruse.com/point?model=gfs&var=air_temperature_2m&lat=48.85&lon=2.35&init_time=2026-06-23T06:00:00Z&lead_from=0&lead_to=3"

Response

{
  "model": "gfs",
  "var": "air_temperature_2m",
  "units": "K",
  "lat": 48.85,
  "lon": 2.35,
  "init_time": "2026-06-23T06:00:00Z",
  "lead_hours": [0, 1, 2, 3],
  "values": [293.1, 292.8, 292.4, 291.9]
}

lead_hours is the forecast horizon in hours relative to init_time. values are in the native CF unit for the variable — air_temperature_2m is always Kelvin.

3. Multi-variable request

Use vars= (plural) to request several variables in one call. The response contains one key per variable.

curl -s -H "Authorization: Bearer $WR_KEY" \
  "https://api.weather-ruse.com/point?model=ecmwf-ifs&vars=air_temperature_2m,wind_u_10m,wind_v_10m,total_precipitation&lat=48.85&lon=2.35&init_time=2026-06-23T06:00:00Z&lead_from=0&lead_to=24"

Response

{
  "model": "ecmwf-ifs",
  "lat": 48.85,
  "lon": 2.35,
  "init_time": "2026-06-23T06:00:00Z",
  "lead_hours": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24],
  "vars": {
    "air_temperature_2m": {
      "units": "K",
      "values": [293.1, 292.8, 292.4, 291.9, 291.5, 291.2, 290.8, 290.5, 290.3, 290.1, 290.0, 290.2, 290.6, 291.1, 291.8, 292.5, 293.0, 293.4, 293.7, 293.9, 294.0, 293.8, 293.5, 293.1, 292.7]
    },
    "wind_u_10m": {
      "units": "m s-1",
      "values": [2.1, 2.3, 2.5, 2.4, 2.2, 1.9, 1.7, 1.5, 1.4, 1.3, 1.2, 1.4, 1.7, 2.0, 2.3, 2.6, 2.8, 2.9, 3.0, 2.9, 2.8, 2.6, 2.4, 2.2, 2.0]
    },
    "wind_v_10m": {
      "units": "m s-1",
      "values": [-0.5, -0.6, -0.7, -0.6, -0.5, -0.4, -0.3, -0.2, -0.1, 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.7, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2]
    },
    "total_precipitation": {
      "units": "kg m-2",
      "values": [0.0, 0.0, 0.1, 0.2, 0.3, 0.2, 0.1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.1, 0.2, 0.3, 0.4, 0.3, 0.2, 0.1, 0.0]
    }
  }
}

Single-variable requests use var= (singular) and return a flat values array. Multi-variable requests use vars= and return a nested object keyed by variable name.

4. Natural language query — /llm

The /llm endpoint accepts a plain-language weather question and returns both a structured parse and a human-readable answer. Useful for chatbots, voice interfaces, or rapid prototyping.

curl -s -H "Authorization: Bearer $WR_KEY" \
  "https://api.weather-ruse.com/llm?q=Will+it+rain+in+London+tomorrow%3F&model=gfs&lat=51.51&lon=-0.13"

Response

{
  "query": "Will it rain in London tomorrow?",
  "parsed": {
    "model": "gfs",
    "lat": 51.51,
    "lon": -0.13,
    "vars": ["total_precipitation"],
    "lead_from": 24,
    "lead_to": 48
  },
  "answer": "Light rain is expected in London tomorrow, with accumulated precipitation peaking around 1.4 kg m-2 in the afternoon.",
  "data": {
    "total_precipitation": {
      "units": "kg m-2",
      "lead_hours": [24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48],
      "values": [0.0, 0.1, 0.2, 0.4, 0.6, 0.8, 1.0, 1.2, 1.4, 1.3, 1.1, 0.9, 0.7, 0.5, 0.3, 0.2, 0.1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
    }
  }
}

The parsed field shows what the API resolved from your question. The data field contains the raw forecast used to generate the answer. You can suppress data with &include_data=false.

5. Python example

No Weather Ruse SDK is required. Use any HTTP client.

import httpx

WR_KEY = "wr-<your-key>"
BASE = "https://api.weather-ruse.com"

headers = {"Authorization": f"Bearer {WR_KEY}"}

params = {
    "model": "hrrr",
    "vars": "wind_u_80m,wind_v_80m",
    "lat": 41.88,
    "lon": -87.63,
    "init_time": "2026-06-23T12:00:00Z",
    "lead_from": 0,
    "lead_to": 18,
}

resp = httpx.get(f"{BASE}/point", headers=headers, params=params)
resp.raise_for_status()
data = resp.json()

lead_hours = data["lead_hours"]
u = data["vars"]["wind_u_80m"]["values"]
v = data["vars"]["wind_v_80m"]["values"]

for h, uu, vv in zip(lead_hours, u, v):
    speed = (uu**2 + vv**2) ** 0.5
    print(f"T+{h:02d}h  {speed:.1f} m/s")

Error codes

Code	Meaning	Common cause
401	Unauthorized	Missing or invalid Authorization header
422	Unprocessable entity	Bad parameter value — check detail field in the response body
429	Rate limit exceeded	Too many requests; back off and retry
500	Internal server error	Unexpected server-side failure
502	Bad gateway	Upstream model data temporarily unavailable
503	Service unavailable	API under maintenance or overloaded; retry with exponential backoff

Error responses always include a JSON body with a detail field describing the problem.

{
  "detail": "Unknown variable 'wind_speed_10m'. Did you mean 'wind_u_10m' or 'wind_v_10m'?"
}

Next steps

• /point reference — full parameter list and response schema
• /bbox reference — grid queries and NetCDF output
• /profile reference — vertical profile queries
• /llm reference — natural language endpoint details
• Models — per-model availability windows and variable support
• Variables — complete variable catalog with units