GET /weather

Current conditions for the cities published for current data on the Weather Data page, with the fields and units published there. Weather, air-quality and pollen fields can be combined in one call.

curl 'https://www.skycaster.tv/api/public/v1/weather' \
-H 'Authorization: Bearer YOUR_API_KEY'

🔐 Authentication

Send your API key as Authorization: Bearer YOUR_API_KEY, x-api-key: YOUR_API_KEY, or ?apiKey=YOUR_API_KEY. See Authentication.

🧩 Query Parameters

Name	Type	Required	Description
`apiKey`	string	No*	API key, if not sent in a header
`format`	string	No	`json` or `xml`. Defaults to the format published on the Weather Data page, then `json`
`preset`	string	No	Name of a current preset saved on the Weather Data page (case-insensitive). Uses that preset’s cities, fields, units and format instead of the published settings
`lang`	string	No	Language id from Languages & wording; replaces weather descriptions and alert titles with your wording

* One of apiKey, Authorization or x-api-key is required.

📦 Response

A list of cities, in the order they were published. See Data Types → WeatherData.

✅ Example Successful Response

1{
2"message": [
3  {
4    "city": "Paris",
5    "data": {
6      "icon": "https://cdn.skycaster.tv/set-2/01d.gif",
7      "weather_description": "Clear sky",
8      "temp": 18.5,
9      "humidity": 62,
10      "dew": 11.2,
11      "uv": 5.1,
12      "eu_aqi": 24,
13      "ozone": 89.3,
14      "alerts": []
15    }
16  },
17  {
18    "city": "New York",
19    "data": {
20      "icon": "https://cdn.skycaster.tv/set-2/02n.gif",
21      "weather_description": "Mainly clear",
22      "temp": 23.4,
23      "humidity": 70,
24      "dew": 17.6,
25      "uv": 0,
26      "eu_aqi": 31,
27      "ozone": 64.0,
28      "alerts": []
29    }
30  }
31]
32}

❌ Possible Errors

All errors are returned as { "error": "..." }. The API key is checked first.

Status	`error`	Description
400	`No cities configured. Save cities on the Weather Data page first.`	Nothing published for current data
400	`No current fields configured. Select fields and save on the Weather Data page first.`	No current fields published
400	`format must be json or xml`	Unsupported `format`
400 / 404	`Preset "…" …`	Preset not found, saved for another mode, or empty
400 / 404	`lang must be …` / `Language "…" not found. …`	Malformed or unknown `lang`
401	`Missing API key` / `Invalid API key`	See Authentication
403	`No active subscription`	The account has no active subscription
429	`Rate limit exceeded`	Plan rate limit reached
500	`Error fetching data`	Upstream or internal error — retry shortly

⚙️ Notes

Data comes from Open-Meteo (forecast models) and the Open-Meteo Air Quality API (air quality and pollen).
Responses are cached for 60 seconds per API key and parameters. Publishing new settings clears the cache.
icon uses the night variant after dark where one exists. See Icons.

📞 Need Assistance?

If you have questions or need support, email us at support@skycaster.tv.