Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 30 additions & 11 deletions pvlib/iotools/solcast.py
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,8 @@ def get_solcast_tmy(
data : pandas.DataFrame
containing the values for the parameters requested. The times
in the DataFrame index indicate the midpoint of each interval.
The index is timezone-aware, using the UTC offset returned by
the API.
metadata: dict
latitude and longitude of the request.

Expand Down Expand Up @@ -115,8 +117,7 @@ def get_solcast_tmy(
params = dict(
latitude=latitude,
longitude=longitude,
format="json",
**kwargs
**{"format": "json", **kwargs}
)

data = _get_solcast(
Expand Down Expand Up @@ -179,6 +180,8 @@ def get_solcast_historic(
data : pandas.DataFrame
containing the values for the parameters requested. The times
in the DataFrame index indicate the midpoint of each interval.
The index is timezone-aware, using the UTC offset returned by
the API.
metadata: dict
latitude and longitude of the request.

Expand Down Expand Up @@ -221,8 +224,7 @@ def get_solcast_historic(
end=end,
duration=duration,
api_key=api_key,
format="json",
**kwargs
**{"format": "json", **kwargs}
)

data = _get_solcast(
Expand Down Expand Up @@ -256,13 +258,17 @@ def get_solcast_forecast(
from Solcast's "period end" convention.
kwargs:
Optional parameters passed to the API.
See [2]_ for full list of parameters.
See [2]_ for full list of parameters. ``format`` defaults to
``"json"``; use ``format="json;version=3"`` to opt in to the
Solcast response format version 3 before it becomes the default.

Returns
-------
data : pandas.DataFrame
Contains the values for the parameters requested. The times
in the DataFrame index indicate the midpoint of each interval.
The index is timezone-aware, using the UTC offset returned by
the API.
metadata: dict
latitude and longitude of the request.

Expand Down Expand Up @@ -299,8 +305,7 @@ def get_solcast_forecast(
params = dict(
latitude=latitude,
longitude=longitude,
format="json",
**kwargs
**{"format": "json", **kwargs}
)

data = _get_solcast(
Expand Down Expand Up @@ -334,13 +339,17 @@ def get_solcast_live(
from Solcast's "period end" convention.
kwargs:
Optional parameters passed to the API.
See [2]_ for full list of parameters.
See [2]_ for full list of parameters. ``format`` defaults to
``"json"``; use ``format="json;version=3"`` to opt in to the
Solcast response format version 3 before it becomes the default.

Returns
-------
data : pandas.DataFrame
containing the values for the parameters requested. The times
in the DataFrame index indicate the midpoint of each interval.
The index is timezone-aware, using the UTC offset returned by
the API.
metadata: dict
latitude and longitude of the request.

Expand Down Expand Up @@ -386,8 +395,7 @@ def get_solcast_live(
params = dict(
latitude=latitude,
longitude=longitude,
format="json",
**kwargs
**{"format": "json", **kwargs}
)

data = _get_solcast(
Expand All @@ -400,6 +408,17 @@ def get_solcast_live(
return data, {"latitude": latitude, "longitude": longitude}


def _parse_period_end(period_end):
"""Parse Solcast ``period_end`` timestamps to a tz-aware DatetimeIndex.

Supports both the legacy format (``2025-04-16T06:00:00.0000000Z``) and
the ISO 8601 UTC offset format (``2025-04-16T14:00:00+01:30``).
The API returns all timestamps with a single fixed UTC offset
(set by the ``time_zone`` parameter), which is kept.
"""
return pd.DatetimeIndex(pd.to_datetime(period_end))


def _solcast2pvlib(data):
"""Format the data from Solcast to pvlib's conventions.

Expand All @@ -414,7 +433,7 @@ def _solcast2pvlib(data):
"""
# move from period_end to period_middle as per pvlib convention

data["period_mid"] = pd.to_datetime(
data["period_mid"] = _parse_period_end(
data.period_end) - pd.to_timedelta(data.period.values) / 2
data = data.set_index("period_mid").drop(columns=["period_end", "period"])

Expand Down
73 changes: 72 additions & 1 deletion tests/iotools/test_solcast.py
Original file line number Diff line number Diff line change
Expand Up @@ -185,11 +185,55 @@
['2023-09-20 01:45:00+00:00', '2023-09-20 01:15:00+00:00'],
dtype='datetime64[ns, UTC]', name='period_mid', freq=None)
)
)
),
(
# new standard API format: float air_temp, ISO 8601 UTC offset
pd.DataFrame(
[[942, 843, 1017.4, 30.2, 7.8, 316, 1010, -2, 4.6, 16.4,
'2023-09-20T12:00:00+10:00', 'PT30M', 90],
[936, 832, 1017.9, 29.8, 7.9, 316, 996, -14, 4.5, 16.3,
'2023-09-20T11:30:00+10:00', 'PT30M', 0]],
columns=[
'dni', 'ghi', 'surface_pressure', 'air_temp', 'wind_speed_10m',
'wind_direction_10m', 'gti', 'azimuth', 'dewpoint_temp',
'precipitable_water', 'period_end', 'period', 'zenith'],
index=pd.RangeIndex(start=0, stop=2, step=1)
),
pd.DataFrame(
[[9.4200e+02, 8.4300e+02, 1.0174e+05, 3.0200e+01, 7.8000e+00,
3.1600e+02, 1.0100e+03, 2.0000e+00, 4.6000e+00, 1.6400e+00, 90],
[9.3600e+02, 8.3200e+02, 1.0179e+05, 2.9800e+01, 7.9000e+00,
3.1600e+02, 9.9600e+02, 1.4000e+01, 4.5000e+00, 1.6300e+00, 0]],
columns=[
'dni', 'ghi', 'pressure', 'temp_air', 'wind_speed',
'wind_direction', 'poa_global', 'solar_azimuth',
'temp_dew', 'precipitable_water', 'solar_zenith'],
index=pd.DatetimeIndex(
['2023-09-20 11:45:00+10:00', '2023-09-20 11:15:00+10:00'],
name='period_mid', freq=None)
)
),
])
def test_solcast2pvlib(in_df, out_df):
df = pvlib.iotools.solcast._solcast2pvlib(in_df)
pd.testing.assert_frame_equal(df.astype(float), out_df.astype(float))
assert df.index.tz is not None


@pytest.mark.parametrize("period_end,expected", [
# legacy format, 7 fractional-second digits and Z suffix
(['2025-04-16T06:00:00.0000000Z', '2025-04-16T06:30:00.0000000Z'],
['2025-04-16T06:00:00+00:00', '2025-04-16T06:30:00+00:00']),
# new standard format, explicit UTC offset
(['2025-04-16T14:00:00+01:30', '2025-04-16T14:30:00+01:30'],
['2025-04-16T14:00:00+01:30', '2025-04-16T14:30:00+01:30']),
(['2025-04-16T06:00:00+00:00'], ['2025-04-16T06:00:00+00:00']),
])
def test_parse_period_end(period_end, expected):
out = pvlib.iotools.solcast._parse_period_end(pd.Series(period_end))
expected = pd.DatetimeIndex(pd.to_datetime(expected))
assert out.equals(expected)
assert str(out.tz) == str(expected.tz)


@pytest.mark.parametrize("map_variables", [True, False])
Expand Down Expand Up @@ -302,6 +346,33 @@
)


@pytest.mark.parametrize("endpoint,function,key", [
("forecast/radiation_and_weather",
pvlib.iotools.get_solcast_forecast, "forecasts"),
("live/radiation_and_weather",
pvlib.iotools.get_solcast_live, "estimated_actuals"),
])
def test_get_solcast_format_version_3(requests_mock, endpoint, function, key):
# response format version 3: ISO 8601 UTC offset and float air_temp
requests_mock.get(
f"https://api.solcast.com.au/data/{endpoint}",

Check failure on line 358 in tests/iotools/test_solcast.py

View workflow job for this annotation

GitHub Actions / flake8-linter

E231 missing whitespace after ':'
json={key: [
{'air_temp': 20.1, 'period_end': '2025-04-16T14:00:00+01:30',
'period': 'PT30M'},
{'air_temp': 20.6, 'period_end': '2025-04-16T14:30:00+01:30',
'period': 'PT30M'},
]})
df, _ = function(latitude=0, longitude=0, api_key="1234",
format="json;version=3")
assert requests_mock.last_request.qs["format"] == ["json;version=3"]
expected_index = pd.DatetimeIndex(
['2025-04-16T13:45:00+01:30', '2025-04-16T14:15:00+01:30'],
name='period_mid')
assert df.index.equals(expected_index)
assert str(df.index.tz) == 'UTC+01:30'
assert df['temp_air'].tolist() == [20.1, 20.6]


@pytest.mark.parametrize(
"function",
[
Expand Down
Loading