📦 Data Types

This page describes the responses of the three data endpoints. Forecast, air-quality and pollen data come from Open-Meteo.

Which fields are returned? Only the fields you selected and published on the dashboard’s Weather Data page (separately for current, hourly and daily), or the fields of the preset named in ?preset=. Every entry also always contains icon and weather_description.

🌐 Common Response Wrapper

1type ApiResponse = {
2message: CityResult[];
3};
4
5type CityResult = {
6city: string;       // City name as saved on the Weather Data page
7locale?: string;    // Only on accounts whose cities were saved with a locale by an older dashboard
8data: WeatherData | HourlyForecastData | DailyForecastData;
9};

🌞 WeatherData

Returned by GET /weather. One key per selected field (see Available Fields), plus two that are always present.

1type WeatherData = {
2icon: string;                // Animated icon URL, e.g. https://cdn.skycaster.tv/set-2/01d.gif
3weather_description: string; // e.g. "Clear sky" — or your own wording with ?lang=
4[fieldId: string]: number | string | WeatherAlert[] | null;
5};

Example data object (°C and km/h):

{
"icon": "https://cdn.skycaster.tv/set-2/01d.gif",
"weather_description": "Clear sky",
"temp": 18.5,
"humidity": 62,
"dew": 11.2,
"wind": 14.8,
"wind_direction": 180,
"wind_direction_label": "S",
"eu_aqi": 28,
"alerts": []
}

🕐 HourlyForecastData

Returned by GET /forecast-hourly. forecast is keyed by the local date-time of each hour (the city’s own time zone).

1type HourlyForecastData = {
2forecast: {
3  [localDateTime: string]: HourlyEntry; // e.g. "2025-05-17T06:00"
4};
5type: "hourly";
6};
7
8type HourlyEntry = {
9time: string;                // Same as the key
10icon: string;
11weather_description: string;
12[fieldId: string]: number | string | WeatherAlert[] | null;
13};

📅 DailyForecastData

Returned by GET /forecast-daily. forecast is keyed by local date.

1type DailyForecastData = {
2forecast: {
3  [localDate: string]: DailyEntry; // e.g. "2025-05-17"
4};
5type: "daily";
6days: number;                // The count you requested
7};
8
9type DailyEntry = {
10time: string;                // Same as the key
11icon: string;                // Always the day icon
12weather_description: string;
13[fieldId: string]: number | string | WeatherAlert[] | null;
14};

🎨 Icons

icon points to an animated GIF from the icon pack selected on the Weather Data page (currently Skycaster Classic, set-2):

https://cdn.skycaster.tv/set-2/<code>.gif

Current and hourly entries use the night variant after dark where one exists; daily entries always use the day icon.

💬 Weather Descriptions

weather_description is one of: Clear sky, Mainly clear, Partly cloudy, Overcast, Foggy, Drizzle, Freezing drizzle, Rain, Freezing rain, Snow, Snow grains, Rain showers, Snow showers, Thunderstorm.

Add ?lang=<id> to any request to replace these (and alert titles) with your own wording — set it up under Languages & wording on the Weather Data page. Phrases you leave empty stay in English.

🚨 Weather Alerts

Select Weather Alerts (alerts for current/hourly, daily_alerts for daily) to get an array of alerts for each entry. Alerts are derived from the forecast data using the thresholds below — they are not official warnings from a national weather service.

type WeatherAlert = {
type: "thunderstorm" | "wind" | "heat" | "cold" | "rain" | "freezing_rain" | "snow" | "uv" | "fog";
severity: "minor" | "moderate" | "severe";
title: string; // English, or your own wording with ?lang=
};

"alerts": [
{ "type": "wind", "severity": "moderate", "title": "Strong wind gusts" },
{ "type": "uv",   "severity": "moderate", "title": "Very high UV" }
]

Thresholds are evaluated in metric units, whatever units you publish:

Current conditions have no rainfall amount, so current rain alerts come from the weather code only.

📋 Available Fields

The Field ID is what you select on the Weather Data page and is also the key in the response — the one exception is Wind Direction (10 m), which returns wind_direction in degrees plus a 16-point compass label wind_direction_label (e.g. "SW").

Units follow what you publish on the Weather Data page: temperature in °C or °F, wind in km/h, mph or m/s. Publishing °F also switches precipitation to inches and snow depth and visibility to feet.

Current & Hourly Fields

Available on /weather and /forecast-hourly. Air-quality and pollen fields are current-only. For amounts such as precipitation or sunshine, current values cover the preceding 15 minutes and hourly values the preceding hour.

Alerts

Temperature

Humidity & Precipitation

Wind

Sky & Clouds

Pressure & Radiation

Atmosphere

Soil

Air Quality

Daily Fields

Available on /forecast-daily. Sums and durations cover the whole local day.

Alerts

Temperature

Precipitation

Wind

Sky

Radiation & Energy

UV

Legacy Field Names

Accounts configured with an older dashboard may still have legacy field names published (for example temperature, feels_like, wind_speed, heat_index, air_quality, ozone_level, temperature_max, sunrise). These keep working and are returned under the same legacy name. Re-publish from the Weather Data page to switch to the current field IDs.

🧾 XML Format

With format=xml (or XML chosen as the API response format on the Weather Data page) the same structure is returned as XML: the root is <response>, each array element is an <item>, and keys that aren’t valid XML names (such as forecast dates) become <entry key="…">.

<?xml version="1.0"?>
<response>
<item>
  <city>Berlin</city>
  <data>
    <forecast>
      <entry key="2025-05-17">
        <time>2025-05-17</time>
        <icon>https://cdn.skycaster.tv/set-2/01d.gif</icon>
        <weather_description>Clear sky</weather_description>
        <daily_temp_max>24.9</daily_temp_max>
      </entry>
    </forecast>
    <type>daily</type>
    <days>1</days>
  </data>
</item>
</response>

📞 Need Assistance?

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