openmeteo-rs 1.0.0

use time::OffsetDateTime;

use super::{HourlyRowIter, Variable, VariableDescriptor};
use crate::query::AsApiStr;

/// Response from the general forecast endpoint.
#[derive(Debug, Clone, PartialEq, serde::Serialize)]
#[non_exhaustive]
pub struct ForecastResponse {
    /// Grid-cell latitude returned by Open-Meteo.
    pub latitude: f64,
    /// Grid-cell longitude returned by Open-Meteo.
    pub longitude: f64,
    /// Grid-cell elevation in metres, when returned.
    pub elevation: Option<f64>,
    /// Server-side generation time in milliseconds.
    pub generation_time_ms: Option<f32>,
    /// UTC offset for returned local timestamps.
    pub utc_offset_seconds: i32,
    /// Timezone name returned by Open-Meteo.
    pub timezone: Option<String>,
    /// Timezone abbreviation returned by Open-Meteo.
    pub timezone_abbreviation: Option<String>,
    /// Current-condition data, if requested.
    pub current: Option<CurrentData>,
    /// Hourly data, if requested.
    pub hourly: Option<HourlyData>,
    /// 15-minute data, if requested.
    pub minutely_15: Option<Minutely15Data>,
    /// Daily data, if requested.
    pub daily: Option<DailyData>,
    /// Monthly data, if requested.
    pub monthly: Option<MonthlyData>,
}

/// Current-condition columns.
#[derive(Debug, Clone, PartialEq, serde::Serialize)]
#[non_exhaustive]
pub struct CurrentData {
    /// Current timestamp, if returned.
    pub time: Option<OffsetDateTime>,
    /// Current-condition variables as single-value series.
    pub variables: Vec<VariableSeries>,
}

impl CurrentData {
    /// Returns a current-condition series by its exact Open-Meteo API name, if present.
    ///
    /// The lookup key is the flattened name returned by the API; aliases are
    /// not normalized.
    pub fn get(&self, api_name: &str) -> Option<&VariableSeries> {
        find_by_api_name(&self.variables, api_name)
    }

    /// Returns a current-condition series by typed request variable, if present.
    pub fn get_var(&self, var: crate::CurrentVar) -> Option<&VariableSeries> {
        let api_name = var.as_api_str();
        find_unique_by_descriptor(
            &self.variables,
            &VariableDescriptor::from_api_name(&api_name),
        )
    }

    /// Returns a current-condition series by typed request variable and model token.
    pub fn get_var_for_model(
        &self,
        var: crate::CurrentVar,
        model: &str,
    ) -> Option<&VariableSeries> {
        let api_name = var.as_api_str();
        find_by_descriptor_for_model(
            &self.variables,
            &VariableDescriptor::from_api_name(&api_name),
            model,
        )
    }

    /// Returns the 2 m temperature series, if present.
    pub fn temperature_2m(&self) -> Option<&VariableSeries> {
        self.get_var(crate::CurrentVar::Temperature2m)
    }

    /// Returns the current day/night flag as a boolean, if present.
    pub fn is_day(&self) -> Option<bool> {
        self.get_var(crate::CurrentVar::IsDay)
            .and_then(VariableSeries::values_f32)
            .and_then(|values| values.first().copied().flatten())
            .map(value_to_bool)
    }
}

/// Hourly time-series columns.
#[derive(Debug, Clone, PartialEq, serde::Serialize)]
#[non_exhaustive]
pub struct HourlyData {
    /// Timestamps for every row.
    pub time: Vec<OffsetDateTime>,
    /// Variable columns aligned to [`Self::time`].
    pub variables: Vec<VariableSeries>,
}

impl HourlyData {
    /// Returns an hourly series by its exact Open-Meteo API name, if present.
    ///
    /// The lookup key is the flattened name returned by the API; aliases are
    /// not normalized.
    pub fn get(&self, api_name: &str) -> Option<&VariableSeries> {
        find_by_api_name(&self.variables, api_name)
    }

    /// Returns an hourly series by typed request variable, if present.
    pub fn get_var(&self, var: crate::HourlyVar) -> Option<&VariableSeries> {
        let api_name = var.as_api_str();
        find_unique_by_descriptor(
            &self.variables,
            &VariableDescriptor::from_api_name(&api_name),
        )
    }

    /// Returns an hourly series by typed request variable and model token.
    pub fn get_var_for_model(&self, var: crate::HourlyVar, model: &str) -> Option<&VariableSeries> {
        let api_name = var.as_api_str();
        find_by_descriptor_for_model(
            &self.variables,
            &VariableDescriptor::from_api_name(&api_name),
            model,
        )
    }

    /// Returns the 2 m temperature series, if present.
    pub fn temperature_2m(&self) -> Option<&VariableSeries> {
        self.get_var(crate::HourlyVar::Temperature2m)
    }

    /// Returns the precipitation series, if present.
    pub fn precipitation(&self) -> Option<&VariableSeries> {
        self.get_var(crate::HourlyVar::Precipitation)
    }

    /// Returns the day/night flag at the requested row as a boolean, if present.
    pub fn is_day_at(&self, index: usize) -> Option<bool> {
        self.get_var(crate::HourlyVar::IsDay)
            .and_then(VariableSeries::values_f32)
            .and_then(|values| values.get(index).copied().flatten())
            .map(value_to_bool)
    }

    /// Returns the mean sea-level pressure series, if present.
    pub fn pressure_msl(&self) -> Option<&VariableSeries> {
        self.get_var(crate::HourlyVar::PressureMsl)
    }

    /// Returns the surface pressure series, if present.
    pub fn surface_pressure(&self) -> Option<&VariableSeries> {
        self.get_var(crate::HourlyVar::SurfacePressure)
    }

    /// Returns a wind-speed series at the requested altitude, if present.
    pub fn wind_speed_at(&self, level: crate::TowerLevel) -> Option<&VariableSeries> {
        self.variables.iter().find(|series| {
            series.descriptor.variable == Variable::WindSpeed
                && series.descriptor.altitude == Some(level.meters())
        })
    }

    /// Returns a wind-direction series at the requested altitude, if present.
    pub fn wind_direction_at(&self, level: crate::TowerLevel) -> Option<&VariableSeries> {
        self.variables.iter().find(|series| {
            series.descriptor.variable == Variable::WindDirection
                && series.descriptor.altitude == Some(level.meters())
        })
    }

    /// Returns a temperature series at the requested altitude, if present.
    pub fn temperature_at_tower(&self, level: crate::TowerLevel) -> Option<&VariableSeries> {
        self.variables.iter().find(|series| {
            series.descriptor.variable == Variable::Temperature
                && series.descriptor.altitude == Some(level.meters())
        })
    }

    /// Returns a temperature series at the requested pressure level, if present.
    pub fn temperature_at_pressure(&self, level: crate::PressureLevel) -> Option<&VariableSeries> {
        self.variables.iter().find(|series| {
            series.descriptor.variable == Variable::Temperature
                && series.descriptor.pressure_level == Some(level.hpa())
        })
    }

    /// Returns a relative-humidity series at the requested pressure level, if present.
    pub fn relative_humidity_at_pressure(
        &self,
        level: crate::PressureLevel,
    ) -> Option<&VariableSeries> {
        self.variables.iter().find(|series| {
            series.descriptor.variable == Variable::RelativeHumidity
                && series.descriptor.pressure_level == Some(level.hpa())
        })
    }

    /// Returns a dew-point series at the requested pressure level, if present.
    pub fn dew_point_at_pressure(&self, level: crate::PressureLevel) -> Option<&VariableSeries> {
        self.variables.iter().find(|series| {
            series.descriptor.variable == Variable::DewPoint
                && series.descriptor.pressure_level == Some(level.hpa())
        })
    }

    /// Returns a cloud-cover series at the requested pressure level, if present.
    pub fn cloud_cover_at_pressure(&self, level: crate::PressureLevel) -> Option<&VariableSeries> {
        self.variables.iter().find(|series| {
            series.descriptor.variable == Variable::CloudCover
                && series.descriptor.pressure_level == Some(level.hpa())
        })
    }

    /// Returns a wind-speed series at the requested pressure level, if present.
    pub fn wind_speed_at_pressure(&self, level: crate::PressureLevel) -> Option<&VariableSeries> {
        self.variables.iter().find(|series| {
            series.descriptor.variable == Variable::WindSpeed
                && series.descriptor.pressure_level == Some(level.hpa())
        })
    }

    /// Returns a wind-direction series at the requested pressure level, if present.
    pub fn wind_direction_at_pressure(
        &self,
        level: crate::PressureLevel,
    ) -> Option<&VariableSeries> {
        self.variables.iter().find(|series| {
            series.descriptor.variable == Variable::WindDirection
                && series.descriptor.pressure_level == Some(level.hpa())
        })
    }

    /// Returns a geopotential-height series at the requested pressure level, if present.
    pub fn geopotential_height_at_pressure(
        &self,
        level: crate::PressureLevel,
    ) -> Option<&VariableSeries> {
        self.variables.iter().find(|series| {
            series.descriptor.variable == Variable::GeopotentialHeight
                && series.descriptor.pressure_level == Some(level.hpa())
        })
    }

    /// Iterates rows lazily without transposing the column storage.
    pub fn iter_rows(&self) -> HourlyRowIter<'_> {
        HourlyRowIter {
            data: self,
            index: 0,
        }
    }
}

/// 15-minute time-series columns.
#[derive(Debug, Clone, PartialEq, serde::Serialize)]
#[non_exhaustive]
pub struct Minutely15Data {
    /// Timestamps in the response timezone offset.
    pub time: Vec<OffsetDateTime>,
    /// Variable columns aligned to [`Self::time`].
    pub variables: Vec<VariableSeries>,
}

impl Minutely15Data {
    /// Returns a 15-minute series by its exact Open-Meteo API name, if present.
    ///
    /// The lookup key is the flattened name returned by the API; aliases are
    /// not normalized.
    pub fn get(&self, api_name: &str) -> Option<&VariableSeries> {
        find_by_api_name(&self.variables, api_name)
    }

    /// Returns a 15-minute series by typed request variable, if present.
    pub fn get_var(&self, var: crate::Minutely15Var) -> Option<&VariableSeries> {
        let api_name = var.as_api_str();
        find_unique_by_descriptor(
            &self.variables,
            &VariableDescriptor::from_api_name(&api_name),
        )
    }

    /// Returns a 15-minute series by typed request variable and model token.
    pub fn get_var_for_model(
        &self,
        var: crate::Minutely15Var,
        model: &str,
    ) -> Option<&VariableSeries> {
        let api_name = var.as_api_str();
        find_by_descriptor_for_model(
            &self.variables,
            &VariableDescriptor::from_api_name(&api_name),
            model,
        )
    }
}

/// Daily time-series columns.
#[derive(Debug, Clone, PartialEq, serde::Serialize)]
#[non_exhaustive]
pub struct DailyData {
    /// Dates represented as midnight timestamps in the response timezone offset.
    pub time: Vec<OffsetDateTime>,
    /// Variable columns aligned to [`Self::time`].
    pub variables: Vec<VariableSeries>,
}

impl DailyData {
    /// Returns the maximum 2 m temperature series, if present.
    pub fn temperature_2m_max(&self) -> Option<&VariableSeries> {
        self.get_var(crate::DailyVar::Temperature2mMax)
    }

    /// Returns a daily series by its exact Open-Meteo API name, if present.
    ///
    /// The lookup key is the flattened name returned by the API; aliases are
    /// not normalized.
    pub fn get(&self, api_name: &str) -> Option<&VariableSeries> {
        find_by_api_name(&self.variables, api_name)
    }

    /// Returns a daily series by typed request variable, if present.
    pub fn get_var(&self, var: crate::DailyVar) -> Option<&VariableSeries> {
        let api_name = var.as_api_str();
        find_unique_by_descriptor(
            &self.variables,
            &VariableDescriptor::from_api_name(&api_name),
        )
    }

    /// Returns a daily series by typed request variable and model token.
    pub fn get_var_for_model(&self, var: crate::DailyVar, model: &str) -> Option<&VariableSeries> {
        let api_name = var.as_api_str();
        find_by_descriptor_for_model(
            &self.variables,
            &VariableDescriptor::from_api_name(&api_name),
            model,
        )
    }
}

/// Monthly time-series columns.
#[derive(Debug, Clone, PartialEq, serde::Serialize)]
#[non_exhaustive]
pub struct MonthlyData {
    /// Dates represented as midnight timestamps in the response timezone offset.
    pub time: Vec<OffsetDateTime>,
    /// Variable columns aligned to [`Self::time`].
    pub variables: Vec<VariableSeries>,
}

impl MonthlyData {
    /// Returns a monthly series by its exact Open-Meteo API name, if present.
    ///
    /// The lookup key is the flattened name returned by the API; aliases are
    /// not normalized.
    pub fn get(&self, api_name: &str) -> Option<&VariableSeries> {
        find_by_api_name(&self.variables, api_name)
    }
}

/// A decoded variable column.
#[derive(Debug, Clone, PartialEq, serde::Serialize)]
#[non_exhaustive]
pub struct VariableSeries {
    /// Parsed variable descriptor.
    pub descriptor: VariableDescriptor,
    /// Unit label returned by Open-Meteo, for example `degC` or `mm`.
    pub unit: Option<String>,
    /// Column values.
    pub values: SeriesValues,
}

impl VariableSeries {
    /// Returns numeric values when this series is numeric.
    ///
    /// Open-Meteo can return `null` for missing values. Missing values are
    /// represented as `None` at the matching timestamp index.
    pub fn values_f32(&self) -> Option<&[Option<f32>]> {
        match &self.values {
            SeriesValues::F32(values) => Some(values),
            SeriesValues::Strings(_) => None,
        }
    }

    /// Returns string values when this series is string-valued.
    ///
    /// Open-Meteo can return `null` for missing values. Missing values are
    /// represented as `None` at the matching timestamp index.
    pub fn values_str(&self) -> Option<&[Option<String>]> {
        match &self.values {
            SeriesValues::F32(_) => None,
            SeriesValues::Strings(values) => Some(values),
        }
    }
}

/// Series value storage.
#[derive(Debug, Clone, PartialEq, serde::Serialize)]
#[non_exhaustive]
pub enum SeriesValues {
    /// Numeric float values, with `None` for API `null`.
    F32(Vec<Option<f32>>),
    /// String values such as sunrise/sunset ISO timestamps, with `None` for API `null`.
    Strings(Vec<Option<String>>),
}

impl SeriesValues {
    pub(crate) fn len(&self) -> usize {
        match self {
            Self::F32(values) => values.len(),
            Self::Strings(values) => values.len(),
        }
    }
}

fn find_by_api_name<'a>(
    variables: &'a [VariableSeries],
    api_name: &str,
) -> Option<&'a VariableSeries> {
    variables
        .iter()
        .find(|series| series.descriptor.api_name == api_name)
}

fn find_unique_by_descriptor<'a>(
    variables: &'a [VariableSeries],
    descriptor: &VariableDescriptor,
) -> Option<&'a VariableSeries> {
    let mut matches = variables
        .iter()
        .filter(|series| descriptors_match_for_typed_lookup(&series.descriptor, descriptor));
    let first = matches.next()?;

    if matches.next().is_some() {
        None
    } else {
        Some(first)
    }
}

fn find_by_descriptor_for_model<'a>(
    variables: &'a [VariableSeries],
    descriptor: &VariableDescriptor,
    model: &str,
) -> Option<&'a VariableSeries> {
    variables.iter().find(|series| {
        series.descriptor.model.as_deref() == Some(model)
            && descriptors_match_for_typed_lookup(&series.descriptor, descriptor)
    })
}

fn descriptors_match_for_typed_lookup(
    actual: &VariableDescriptor,
    expected: &VariableDescriptor,
) -> bool {
    model_stripped_api_name(&actual.api_name) == expected.api_name
        && actual.variable == expected.variable
        && actual.altitude == expected.altitude
        && actual.pressure_level == expected.pressure_level
        && actual.depth == expected.depth
        && actual.depth_to == expected.depth_to
        && actual.aggregation == expected.aggregation
        && actual.previous_day == expected.previous_day
        && actual.ensemble_member == expected.ensemble_member
}

fn model_stripped_api_name(api_name: &str) -> &str {
    let descriptor = VariableDescriptor::from_api_name(api_name);
    if let Some(model) = descriptor.model.as_deref()
        && let Some(base) = api_name.strip_suffix(model)
        && let Some(base) = base.strip_suffix('_')
    {
        return base;
    }

    api_name
}

fn value_to_bool(value: f32) -> bool {
    value != 0.0
}