📦 Data Types

This section describes the response structures returned by the Skycaster API. All data is sourced from the Open-Meteo API.

Note: The fields returned in each response depend on your dashboard settings (choosenInfo, choosenInfoHourly, choosenInfoDaily). Only the fields you have configured are included in the response. Two fields are always present in every entry: icon and weather_description.

🌐 Common Response Wrapper

All three public endpoints return responses with the same top-level shape:

1type ApiResponse = {
2message: CityResult[];
3};
4
5type CityResult = {
6city: string;       // Display name of the city
7locale?: string;    // BCP 47 locale tag, e.g. "de-CH", "en-US"
8data: WeatherData | ForecastData;
9};

☀️ WeatherData

Returned by GET /weather. The data object contains one key per configured field, plus two always-present fields.

1// Always present
2type WeatherDataBase = {
3icon: string;               // URL to animated weather icon gif
4weather_description: string; // Human-readable description, e.g. "Clear sky"
5};
6
7// Additional fields depend on user's choosenInfo settings.
8// Field names match the setting key (see Available Fields table below).
9type WeatherData = WeatherDataBase & {
10[fieldName: string]: number | string | null;
11};

Example data object:

{
"icon": "https://cdn.skycaster.tv/set-1-gif/01d.gif",
"weather_description": "Clear sky",
"temperature": 18.5,
"humidity": 62,
"dew_point": 11.2,
"wind_speed": 4.1,
"wind_direction": 180,
"wind_direction_label": "S",
"heat_index": 18.2
}

🕐 ForecastData (Hourly)

Returned by GET /forecast-hourly. The data object contains a forecast map keyed by ISO 8601 datetime strings.

1type HourlyForecastData = {
2forecast: {
3  [isoDatetime: string]: HourlyEntry; // e.g. "2025-05-17T06:00"
4};
5type: "hourly";
6};
7
8// Always present per entry
9type HourlyEntryBase = {
10time: string;               // ISO 8601 datetime, e.g. "2025-05-17T06:00"
11icon: string;               // URL to animated weather icon gif
12weather_description: string;
13};
14
15// Additional fields from choosenInfoHourly (or choosenInfo as fallback)
16type HourlyEntry = HourlyEntryBase & {
17[fieldName: string]: number | string | null;
18};

🌤️ ForecastData (Daily)

Returned by GET /forecast-daily. The data object contains a forecast map keyed by ISO 8601 date strings.

1type DailyForecastData = {
2forecast: {
3  [isoDate: string]: DailyEntry; // e.g. "2025-05-17"
4};
5type: "daily";
6days: number; // Number of days returned
7};
8
9// Always present per entry
10type DailyEntryBase = {
11time: string;               // ISO 8601 date, e.g. "2025-05-17"
12icon: string;               // URL to animated weather icon gif
13weather_description: string;
14};
15
16// Additional fields from choosenInfoDaily (or choosenInfo as fallback)
17type DailyEntry = DailyEntryBase & {
18[fieldName: string]: number | string | null;
19};

📋 Available Field Names

Configure these in your dashboard. Use the Field Name as the key when reading the response.

Current / Hourly Fields

Daily-Only Fields

Air Quality Fields

📞 Need Assistance?

If you have questions or need support:

• Contact Support: Reach out via our Support Page 
• Email Us: support@skycaster.tv