eta_nexus.connections.forecastsolar_connection module

This module provides a read-only REST API connection to the forecast.solar API.

You can obtain an estimate of solar production for a specific location, defined by latitude and longitude, and a specific plane orientation, defined by declination and azimuth, based on the installed module power.

Supported endpoints include: “Estimate”, “Historic”, and “Clearsky”:

Estimate Solar Production The estimate endpoint provides the forecast for today and the upcoming days, depending on the account model.

Historic Solar Production The historic endpoint calculates the average solar production for a given day based on historical weather data, excluding current weather conditions.

Clear Sky Solar Production The clearsky endpoint calculates the theoretically possible solar production assuming no cloud cover.

For more information, visit the forecast.solar API documentation.

class eta_nexus.connections.forecastsolar_connection.ForecastsolarConnection(url: str = 'https://api.forecast.solar', *, url_params: dict[str, Any] | None = None, query_params: dict[str, Any] | None = None, nodes: Nodes[ForecastsolarNode] | None = None, retry_total: int = 3, retry_backoff_factor: float = 1.0)[source]

Bases: RESTConnection[ForecastsolarNode], Connection[ForecastsolarNode], StatusReadable[ForecastsolarNode], SeriesReadable[ForecastsolarNode]

ForecastsolarConnection is a class to download and upload multiple features from and to the ForecastSolar database as timeseries.

Parameters:

  • url – URL of the server with scheme (https://).

  • usr – Not needed for Forecast.Solar.

  • pwd – Not needed for Forecast.Solar.

  • nodes – Nodes to select in connection.

  • retry_total – Total number of retries for failed HTTP requests (default: 3).

  • retry_backoff_factor – Backoff factor for retries (default: 1s-> e.g. 1s, 2s, 4s for 3 retries).

logger: Logger = <Logger eta_nexus.connections.forecastsolar_connection (WARNING)>
url_params: dict[str, Any] | None

Url parameters for the forecast.Solar API

query_params: dict[str, Any] | None

Query parameters for the forecast.Solar API

read_node(node: ForecastsolarNode, from_time: datetime, to_time: datetime, interval: timedelta, **kwargs: Any) → pd.DataFrame[source]

Download data from the Forecast.Solar Database.

Note: The Forecast.Solar API returns full-day data regardless of time parameters. Time filtering and resampling are handled in read_series after data retrieval.

Parameters:

  • node – Node to read values from.

  • from_time – Start time (used for filtering in read_series, not in API call).

  • to_time – End time (used for filtering in read_series, not in API call).

  • interval – Interval for resampling (handled in read_series via df_interpolate).

Returns:

pandas.DataFrame containing the data read from the connection.

read(nodes: ForecastsolarNode | Nodes[ForecastsolarNode] | None = None) → pd.DataFrame[source]

Return solar forecast for the current time.

Parameters:

nodes – Single node or list/set of nodes to read values from.

Returns:

Pandas DataFrame containing the data read from the connection.

read_series(from_time: datetime, to_time: datetime, nodes: ForecastsolarNode | Nodes[ForecastsolarNode] | None = None, interval: TimeStep = 1, **kwargs: Any) → pd.DataFrame[source]

Return a time series of forecast data from the Forecast.Solar Database.

Parameters:

  • nodes – Single node or list/set of nodes to read values from.

  • from_time – Starting time to begin reading (included in output).

  • to_time – Time to stop reading at (not included in output).

  • interval – Interval between time steps. It is interpreted as seconds if given as integer.

  • kwargs – Other parameters (ignored by this connection).

Returns:

Pandas DataFrame containing the data read from the connection.

timestr_from_datetime(dt: datetime) → str[source]

Create an Forecast.Solar compatible time string.

Parameters:

dt – Datetime object to convert to string.

Returns:

Forecast.Solar compatible time string.

classmethod route_valid(nodes: Nodes, **kwargs: Any) → bool[source]

Check if node routes make up a valid route, by using the Forecast.Solar API’s check endpoint.

Parameters:

nodes – List of nodes to check.

Returns:

Boolean if the nodes are on the same route.

static calculate_watt_hours_period(watt_df: pandas.DataFrame) → pandas.DataFrame[source]

Calculates watt hours for each period based on the average watts between consecutive rows.

Parameters:

df – DataFrame with indices representing time intervals and columns representing node’s watt estimates

Returns:

DataFrame with the watt-hour-period estimates for each interval

static cumulative_watt_hours_per_day(watt_hours_df: pandas.DataFrame, from_unit: str = 'watthours/period') → pandas.DataFrame[source]

Calculates the cumulative watt-hours throughout each day for each panel.

Parameters:

  • watt_hours_df – df with indices representing time intervals and columns containing watt-hour estimates.

  • from_unit – Unit of the input DataFrame. Default is “watthours/period”.

Returns:

DataFrame with cumulative watt-hours per day for each panel, rounded to three decimal places.

static summarize_watt_hours_per_day(watt_hours_df: pandas.DataFrame, from_unit: str = 'watthours/period') → pandas.DataFrame[source]

Sums the watt-hours over each day for each panel.

Parameters:

  • watt_hours_df – df with indices representing time intervals and columns containing watt-hour estimates.

  • from_unit – Unit of the input DataFrame. Default is “watthours/period”.

Returns:

DataFrame with total watt-hours per day for each panel, rounded to three decimal places.