historical weather

2026-07-25 15:24:03 +02:00
parent f8d7c7699f
commit 61d84e4450
15 changed files with 1653 additions and 25 deletions
@@ -22,6 +22,7 @@ import type { VariablesWithTime } from '@openmeteo/sdk/variables-with-time';

 const FORECAST_URL = 'https://api.open-meteo.com/v1/forecast';
 const ENSEMBLE_URL = 'https://ensemble-api.open-meteo.com/v1/ensemble';
+const ARCHIVE_URL = 'https://archive-api.open-meteo.com/v1/archive';

 // ─── Core Helpers ───────────────────────────────────────────────────────────────

@@ -303,6 +304,40 @@ const WEEK_DAILY_VARS = [
 	'wind_direction_10m_dominant'
 ] as const;

+/**
+ * Assembles a WeekHourlyData structure from a name→values map, so variables that
+ * were not requested resolve to empty arrays. Shared by the week and historical
+ * fetchers (both return the same hourly shape, which the meteograms and hourly
+ * table consume).
+ */
+function weekHourlyFromByName(byName: Record<string, number[]>): WeekHourlyData {
+	const g = (name: string): number[] => byName[name] ?? [];
+	return {
+		temperature_2m: g('temperature_2m'),
+		precipitation: g('precipitation'),
+		precipitation_probability: g('precipitation_probability'),
+		weather_code: g('weather_code'),
+		windspeed_10m: g('wind_speed_10m'),
+		winddirection_10m: g('wind_direction_10m'),
+		cloud_cover: g('cloud_cover'),
+		relative_humidity_2m: g('relative_humidity_2m'),
+		apparent_temperature: g('apparent_temperature'),
+		dew_point_2m: g('dew_point_2m'),
+		wind_gusts_10m: g('wind_gusts_10m'),
+		pressure_msl: g('pressure_msl'),
+		surface_pressure: g('surface_pressure'),
+		rain: g('rain'),
+		showers: g('showers'),
+		snowfall: g('snowfall'),
+		cloud_cover_low: g('cloud_cover_low'),
+		cloud_cover_mid: g('cloud_cover_mid'),
+		cloud_cover_high: g('cloud_cover_high'),
+		uv_index: g('uv_index'),
+		visibility: g('visibility'),
+		cape: g('cape')
+	};
+}
+
 /**
 * Fetches the 7-day (week) weather forecast for a single location and model.
 * Returns typed hourly and daily data structures.
@@ -359,32 +394,8 @@ export async function fetchWeekForecast(params: WeekForecastParams): Promise<Wee
 		const variable = hourlyBlock.variables(i);
 		byName[name] = variable ? getValues(variable) : [];
 	});
-	const g = (name: string): number[] => byName[name] ?? [];

-	const hourly: WeekHourlyData = {
-		temperature_2m: g('temperature_2m'),
-		precipitation: g('precipitation'),
-		precipitation_probability: g('precipitation_probability'),
-		weather_code: g('weather_code'),
-		windspeed_10m: g('wind_speed_10m'),
-		winddirection_10m: g('wind_direction_10m'),
-		cloud_cover: g('cloud_cover'),
-		relative_humidity_2m: g('relative_humidity_2m'),
-		apparent_temperature: g('apparent_temperature'),
-		dew_point_2m: g('dew_point_2m'),
-		wind_gusts_10m: g('wind_gusts_10m'),
-		pressure_msl: g('pressure_msl'),
-		surface_pressure: g('surface_pressure'),
-		rain: g('rain'),
-		showers: g('showers'),
-		snowfall: g('snowfall'),
-		cloud_cover_low: g('cloud_cover_low'),
-		cloud_cover_mid: g('cloud_cover_mid'),
-		cloud_cover_high: g('cloud_cover_high'),
-		uv_index: g('uv_index'),
-		visibility: g('visibility'),
-		cape: g('cape')
-	};
+	const hourly = weekHourlyFromByName(byName);

 	// Daily: variables are in the same order as WEEK_DAILY_VARS
 	const dailyDates = getDates(dailyBlock);
@@ -803,3 +814,273 @@ function modelEnumToString(modelEnum: number): string {
 	};
 	return modelMap[modelEnum] ?? `model_${modelEnum}`;
 }
+
+// ─── Historical (Archive) Types ─────────────────────────────────────────────
+
+export interface HistoricalDailyData {
+	weather_code: number[];
+	temperature_2m_max: number[];
+	temperature_2m_min: number[];
+	temperature_2m_mean: number[];
+	apparent_temperature_max: number[];
+	apparent_temperature_min: number[];
+	sunrise: number[];
+	sunset: number[];
+	sunshine_duration: number[];
+	precipitation_sum: number[];
+	rain_sum: number[];
+	snowfall_sum: number[];
+	precipitation_hours: number[];
+	windspeed_10m_max: number[];
+	windgusts_10m_max: number[];
+	winddirection_10m_dominant: number[];
+}
+
+export interface HistoricalForecastParams extends WeatherLocation, WeatherUnitParams {
+	/** Inclusive range, YYYY-MM-DD (location-local dates). */
+	start_date: string;
+	end_date: string;
+	/** Hourly API variables to request; defaults to the core week set. */
+	hourlyVariables?: string[];
+}
+
+export interface HistoricalForecastResult {
+	hourly: WeekHourlyData;
+	daily: HistoricalDailyData;
+	utcOffsetSeconds: number;
+	timezone: string;
+	hourlyTimestamps: number[];
+	hourlyDates: Date[];
+	dailyDates: Date[];
+	daylightBands: DaylightBand[];
+}
+
+// Requested in this exact order; the daily block returns variables positionally.
+const HISTORICAL_DAILY_VARS = [
+	'weather_code',
+	'temperature_2m_max',
+	'temperature_2m_min',
+	'temperature_2m_mean',
+	'apparent_temperature_max',
+	'apparent_temperature_min',
+	'sunrise',
+	'sunset',
+	'sunshine_duration',
+	'precipitation_sum',
+	'rain_sum',
+	'snowfall_sum',
+	'precipitation_hours',
+	'wind_speed_10m_max',
+	'wind_gusts_10m_max',
+	'wind_direction_10m_dominant'
+] as const;
+
+// ─── Historical (Archive) Fetch ─────────────────────────────────────────────
+
+/**
+ * Fetches reanalysis (ERA5) weather for a past date range from the Open-Meteo
+ * archive API. Returns the same hourly shape as the week forecast (so the
+ * existing meteograms and hourly table render it unchanged) plus a richer daily
+ * block for the climate/statistics view.
+ */
+export async function fetchHistoricalWeather(
+	params: HistoricalForecastParams
+): Promise<HistoricalForecastResult> {
+	const hourlyVars =
+		params.hourlyVariables && params.hourlyVariables.length > 0
+			? [...new Set(params.hourlyVariables)]
+			: [...WEEK_HOURLY_VARS];
+
+	const apiParams: Record<string, string | number | undefined> = {
+		latitude: params.latitude,
+		longitude: params.longitude,
+		start_date: params.start_date,
+		end_date: params.end_date,
+		hourly: hourlyVars.join(','),
+		daily: HISTORICAL_DAILY_VARS.join(','),
+		temperature_unit: params.temperature_unit ?? 'celsius',
+		wind_speed_unit: params.wind_speed_unit ?? 'kmh',
+		precipitation_unit: params.precipitation_unit ?? 'mm',
+		timezone: params.timezone
+	};
+
+	const cleanParams: Record<string, string> = {};
+	for (const [key, value] of Object.entries(apiParams)) {
+		if (value !== undefined) cleanParams[key] = String(value);
+	}
+
+	const responses = await fetchWeatherApi(ARCHIVE_URL, cleanParams);
+	const response = responses[0];
+	const utcOffsetSeconds = response.utcOffsetSeconds();
+	const timezone = response.timezone() ?? params.timezone ?? 'UTC';
+
+	const hourlyBlock = response.hourly()!;
+	const dailyBlock = response.daily()!;
+
+	const hourlyTimestamps = getTimestamps(hourlyBlock);
+	const hourlyDates = hourlyTimestamps.map((t) => new Date(t));
+
+	const byName: Record<string, number[]> = {};
+	hourlyVars.forEach((name, i) => {
+		const variable = hourlyBlock.variables(i);
+		byName[name] = variable ? getValues(variable) : [];
+	});
+	const hourly = weekHourlyFromByName(byName);
+
+	// Daily variables come back in HISTORICAL_DAILY_VARS order.
+	const dailyDates = getDates(dailyBlock);
+	const d = (i: number): number[] => {
+		const v = dailyBlock.variables(i);
+		return v ? getValues(v) : [];
+	};
+	const sunrise = getInt64Values(dailyBlock.variables(6)!);
+	const sunset = getInt64Values(dailyBlock.variables(7)!);
+
+	const daily: HistoricalDailyData = {
+		weather_code: d(0),
+		temperature_2m_max: d(1),
+		temperature_2m_min: d(2),
+		temperature_2m_mean: d(3),
+		apparent_temperature_max: d(4),
+		apparent_temperature_min: d(5),
+		sunrise,
+		sunset,
+		sunshine_duration: d(8),
+		precipitation_sum: d(9),
+		rain_sum: d(10),
+		snowfall_sum: d(11),
+		precipitation_hours: d(12),
+		windspeed_10m_max: d(13),
+		windgusts_10m_max: d(14),
+		winddirection_10m_dominant: d(15)
+	};
+
+	const daylightBands = buildDaylightBands(sunrise, sunset);
+
+	return {
+		hourly,
+		daily,
+		utcOffsetSeconds,
+		timezone,
+		hourlyTimestamps,
+		hourlyDates,
+		dailyDates,
+		daylightBands
+	};
+}
+
+// ─── Climate Normals ────────────────────────────────────────────────────────
+
+export interface ClimateNormals {
+	/** Indexed by day-of-year ordinal 1..366 (index 0 unused); NaN where no data. */
+	tmax: number[];
+	tmin: number[];
+	tmean: number[];
+	/** Mean daily precipitation (per calendar day). */
+	precip: number[];
+	baseStart: string;
+	baseEnd: string;
+	temperature_unit: string;
+	precipitation_unit: string;
+}
+
+export interface ClimateNormalsParams extends WeatherLocation, WeatherUnitParams {
+	/** Baseline period; defaults to the 1991-2020 WMO normal period. */
+	baseStart?: string;
+	baseEnd?: string;
+}
+
+// Days before the first of each month in a leap reference year, so that a
+// (month, day) pair maps to a stable 1..366 ordinal regardless of leap years.
+const CUM_DAYS_LEAP = [0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335];
+
+/** Day-of-year ordinal (1..366) from month (1-12) and day-of-month (1-31). */
+export function monthDayToOrdinal(month: number, day: number): number {
+	const m = Math.min(12, Math.max(1, Math.round(month)));
+	return CUM_DAYS_LEAP[m - 1] + day;
+}
+
+/**
+ * Computes daily climate normals for a location by averaging a multi-decade
+ * archive across years, per day-of-year, with a ±7-day smoothing window so the
+ * curve is stable. One archive request; used for the "vs normal" comparison.
+ */
+export async function fetchClimateNormals(params: ClimateNormalsParams): Promise<ClimateNormals> {
+	const baseStart = params.baseStart ?? '1991-01-01';
+	const baseEnd = params.baseEnd ?? '2020-12-31';
+
+	// UTC keeps the day-of-year bucketing exact (no offset spill across midnight);
+	// timezone is irrelevant to a per-calendar-day normal.
+	const apiParams: Record<string, string> = {
+		latitude: String(params.latitude),
+		longitude: String(params.longitude),
+		start_date: baseStart,
+		end_date: baseEnd,
+		daily: 'temperature_2m_max,temperature_2m_min,temperature_2m_mean,precipitation_sum',
+		temperature_unit: params.temperature_unit ?? 'celsius',
+		precipitation_unit: params.precipitation_unit ?? 'mm',
+		timezone: 'UTC'
+	};
+
+	const responses = await fetchWeatherApi(ARCHIVE_URL, apiParams);
+	const response = responses[0];
+	const dailyBlock = response.daily()!;
+	const dates = getDates(dailyBlock);
+	const tmaxV = getValues(dailyBlock.variables(0)!);
+	const tminV = getValues(dailyBlock.variables(1)!);
+	const tmeanV = getValues(dailyBlock.variables(2)!);
+	const precipV = getValues(dailyBlock.variables(3)!);
+
+	const N = 367; // ordinals 1..366
+	const mk = () => ({ sum: new Array<number>(N).fill(0), cnt: new Array<number>(N).fill(0) });
+	const acc = { tmax: mk(), tmin: mk(), tmean: mk(), precip: mk() };
+
+	const add = (bucket: { sum: number[]; cnt: number[] }, ord: number, val: number) => {
+		if (Number.isFinite(val)) {
+			bucket.sum[ord] += val;
+			bucket.cnt[ord] += 1;
+		}
+	};
+
+	for (let i = 0; i < dates.length; i++) {
+		const dt = dates[i];
+		const ord = monthDayToOrdinal(dt.getUTCMonth() + 1, dt.getUTCDate());
+		add(acc.tmax, ord, tmaxV[i]);
+		add(acc.tmin, ord, tminV[i]);
+		add(acc.tmean, ord, tmeanV[i]);
+		add(acc.precip, ord, precipV[i]);
+	}
+
+	const mean = (bucket: { sum: number[]; cnt: number[] }): number[] =>
+		bucket.sum.map((s, i) => (bucket.cnt[i] > 0 ? s / bucket.cnt[i] : NaN));
+
+	// Circular ±window smoothing across the 366 ordinals (skips empty days).
+	const smooth = (arr: number[], window = 7): number[] => {
+		const out = new Array<number>(N).fill(NaN);
+		for (let o = 1; o <= 366; o++) {
+			let s = 0;
+			let c = 0;
+			for (let k = -window; k <= window; k++) {
+				const idx = ((o - 1 + k + 366) % 366) + 1;
+				const v = arr[idx];
+				if (Number.isFinite(v)) {
+					s += v;
+					c++;
+				}
+			}
+			out[o] = c > 0 ? s / c : NaN;
+		}
+		return out;
+	};
+
+	return {
+		tmax: smooth(mean(acc.tmax)),
+		tmin: smooth(mean(acc.tmin)),
+		tmean: smooth(mean(acc.tmean)),
+		precip: smooth(mean(acc.precip)),
+		baseStart,
+		baseEnd,
+		temperature_unit: params.temperature_unit ?? 'celsius',
+		precipitation_unit: params.precipitation_unit ?? 'mm'
+	};
+}