GET /forecast-hourly

Hourly forecast for the cities published for hourly data on the Weather Data page (or, if none, the current-data cities), up to 16 days ahead. Use step to return every n-th hour.

curl 'https://www.skycaster.tv/api/public/v1/forecast-hourly?days=2&step=3' \
-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
`days`	integer	Yes	Number of days, `1`–`16`. Starts at 00:00 local time today
`step`	integer	Yes	Hours between entries, `1`–`24` (`3` → 00:00, 03:00, 06:00, …)
`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 an hourly preset saved on the Weather Data page (case-insensitive)
`lang`	string	No	Language id from Languages & wording

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

📦 Response

See Data Types → HourlyForecastData. Keys in forecast are local date-times in each city’s time zone.

✅ Example Successful Response

1{
2"message": [
3  {
4    "city": "Berlin",
5    "data": {
6      "forecast": {
7        "2025-05-17T06:00": {
8          "time": "2025-05-17T06:00",
9          "icon": "https://cdn.skycaster.tv/set-2/01d.gif",
10          "weather_description": "Clear sky",
11          "temp": 13.5,
12          "wind": 9.2,
13          "humidity": 78,
14          "pressure": 1011.4,
15          "cloud": 12,
16          "feels": 12.7
17        },
18        "2025-05-17T09:00": {
19          "time": "2025-05-17T09:00",
20          "icon": "https://cdn.skycaster.tv/set-2/03d.gif",
21          "weather_description": "Partly cloudy",
22          "temp": 18.1,
23          "wind": 12.8,
24          "humidity": 61,
25          "pressure": 1012.9,
26          "cloud": 45,
27          "feels": 17.4
28        }
29      },
30      "type": "hourly"
31    }
32  }
33]
34}

❌ Possible Errors

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

Status	`error`	Description
400	`days is required` / `step is required`	Missing parameter
400	`days must be a whole number from 1 to 16`	Out of range or not an integer
400	`step must be a whole number from 1 to 24`	Out of range or not an integer
400	`No cities configured. Save cities on the Weather Data page first.`	Nothing published
400	`No hourly fields configured. Select fields and save on the Weather Data page first.`	No hourly 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 hourly forecast`	Upstream or internal error — retry shortly

⚙️ Notes

Data comes from Open-Meteo. Air-quality and pollen fields are not available hourly.
Responses are cached for 5 minutes per API key and parameters. Publishing new settings clears the cache.
Hourly icon values use the night variant after dark where one exists.

📞 Need Assistance?

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