GET /forecast-hourly

This endpoint provides a multi-day hourly weather forecast for a list of cities, grouped by your chosen settings. Forecast data includes temperature, wind, humidity, pressure, and other values for selected hours per day. Supports up to 16 days ahead.

🔐 Authentication

You must provide an API key either as a query parameter or in the headers:

Query: ?apiKey=YOUR_API_KEY
Header: Authorization: Bearer YOUR_API_KEY
Header: x-api-key: YOUR_API_KEY

🧩 Query Parameters

Name	Type	Required	Description
apiKey	string	No*	API key (alternative to headers)
step	number	Yes	Hourly interval between data points (1–24)
days	number	Yes	Number of forecasted days (1–16)
format	string	No	Response format: `json` (default) or `xml`

🧾 Headers

Header	Value	Required
Authorization	`Bearer YOUR_API_KEY`	No*
x-api-key	`YOUR_API_KEY`	No*

📦 Response

Returns a list of cities with their hourly weather forecast data.

✅ Example Successful Response

1{
2"message": [
3  {
4    "city": "Berlin",
5    "locale": "de",
6    "data": {
7      "forecast": {
8        "2025-05-17T06:00": {
9          "time": "2025-05-17T06:00",
10          "icon": "https://cdn.skycaster.tv/set-1-gif/01d.gif",
11          "weather_description": "Clear sky",
12          "temperature": 23.5,
13          "wind_speed": 5.2,
14          "humidity": 48,
15          "pressure": 1011,
16          "cloud_cover": 12,
17          "feels_like": 22.7,
18          "dew_point": 11.4,
19          "heat_index": 23.1
20        },
21        "2025-05-17T09:00": {
22          "time": "2025-05-17T09:00",
23          "icon": "https://cdn.skycaster.tv/set-1-gif/02d.gif",
24          "weather_description": "Partly cloudy",
25          "temperature": 21.1,
26          "wind_speed": 4.8,
27          "humidity": 52,
28          "pressure": 1013,
29          "cloud_cover": 15,
30          "feels_like": 20.4,
31          "dew_point": 10.1,
32          "heat_index": 20.8
33        }
34      },
35      "type": "hourly"
36    }
37  }
38]
39}

❌ Possible Errors

Status Code	Error Message	Description
400	`days is required`	Missing required `days` query parameter
400	`step is required`	Missing required `step` query parameter
400	`days must be 1–16`	The `days` parameter is outside the allowed range
400	`step must be 1–24`	The `step` parameter is outside the allowed range
400	`No cities configured`	No cities saved on the Weather Data page
400	`No hourly fields configured`	No hourly fields selected on the Weather Data page
401	`Unauthorized`	No valid API key provided or user not found
429	`Rate limit exceeded`	The user has exceeded their rate limit
500	`Error fetching hourly forecast`	An internal server error occurred

⚙️ Internal Notes

Forecast data is sourced from the Open-Meteo API.
Keys in forecast are ISO 8601 datetime strings (e.g. "2025-05-17T06:00").
Forecasts are returned per city, based on each user’s saved city list and enabled data types.
Units (temperature, wind speed, etc.) depend on user preferences set in the dashboard.

See Data Types → ForecastData (Hourly) for the full response structure and available field names.

📞 Need Assistance?

If you have questions or need support:

Contact Support: Reach out via our Support Page .
Email Us: Send inquiries to support@skycaster.tv.