diff --git a/docs/forecast.md b/docs/forecast.md index 6c5535a..c163375 100644 --- a/docs/forecast.md +++ b/docs/forecast.md @@ -1,16 +1,18 @@ # Forecast -Get irradiance, weather and power forecasts from the present time up to 14 days ahead for -the requested location, derived from satellite (clouds and irradiance over non-polar continental areas, +Get irradiance, weather and power forecasts from the present time up to 14 days ahead for +requested locations or resources, including premium PV and wind power forecasts, derived from satellite (clouds and irradiance over non-polar continental areas, nowcasted for approx. four hours ahead) and numerical weather models (other data and longer horizons). More information in the [API docs](https://docs.solcast.com.au/#49090b36-66db-4d0f-89d5-87d19f00bec1). -The module `forecast` has 3 available methods: +The module `forecast` has 5 available methods: | Endpoint | API Docs | |-------------------------|-------------------------------------------------------------------------------------------| | `radiation_and_weather` | [details](https://docs.solcast.com.au/?#b78a2ee4-c8e5-4ae6-9fb3-c8bbefe91efc){.md-button} | | `rooftop_pv_power` | [details](https://docs.solcast.com.au/?#25ff8ad7-e2a8-44be-9d2e-62e0f73cefd6){.md-button} | | `advanced_pv_power` | [details](https://docs.solcast.com.au/?#0c9d3ccf-e2a4-4583-86a3-f89c8d658fde){.md-button} | +| `premium_pv_power` | [details](https://docs.solcast.com.au/docs/section/premium#getDataForecastPremiumPvPower){.md-button} | +| `premium_wind_power` | [details](https://docs.solcast.com.au/docs/section/premium#getDataForecastPremiumWindPower){.md-button} | ### Example diff --git a/solcast/__init__.py b/solcast/__init__.py index eee9373..4725aa3 100644 --- a/solcast/__init__.py +++ b/solcast/__init__.py @@ -15,7 +15,7 @@ "forecast", "historic", "live", + "pv_power_sites", "tmy", "unmetered_locations", - "pv_power_sites", ] diff --git a/solcast/aggregations.py b/solcast/aggregations.py index 631f013..f98049a 100644 --- a/solcast/aggregations.py +++ b/solcast/aggregations.py @@ -37,7 +37,7 @@ def forecast( collection_id: str, aggregation_id: Optional[str], **kwargs ) -> PandafiableResponse: """ - Get forecast aggregation data for up to 7 days of data at a time for a requested collection or aggregation. + Get forecast aggregation data for up to 14 days of data at a time for a requested collection or aggregation. Args: collection_id: a unique identifier for your collection. diff --git a/solcast/forecast.py b/solcast/forecast.py index abdedb6..05b08a4 100644 --- a/solcast/forecast.py +++ b/solcast/forecast.py @@ -4,6 +4,8 @@ from .urls import ( base_url, forecast_advanced_pv_power, + forecast_premium_pv_power, + forecast_premium_wind_power, forecast_radiation_and_weather, forecast_rooftop_pv_power, forecast_soiling_hsu, @@ -15,15 +17,17 @@ def radiation_and_weather( latitude: float, longitude: float, output_parameters: List[str], **kwargs ) -> PandafiableResponse: """ - Get irradiance and weather forecasts from the present time up to 14 days ahead - for the requested location, derived from satellite (clouds and irradiance - over non-polar continental areas, nowcasted for approx. four hours ahead) - and numerical weather models (other data and longer horizons). + Get irradiance and weather forecasts for the requested location from the present up + to 14 days ahead, derived from satellite (clouds and irradiance over non-polar + continental areas, nowcast for approx. four hours ahead) and numerical weather + models (other data and longer horizons). Args: - latitude: in decimal degrees, between -90 and 90, north is positive - longitude: in decimal degrees, between -180 and 180, east is positive - output_parameters: list of strings with the parameters to return + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. + output_parameters: The output parameters to include in the response. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. @@ -31,7 +35,7 @@ def radiation_and_weather( client = Client( base_url=base_url, endpoint=forecast_radiation_and_weather, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) return client.get( @@ -49,15 +53,20 @@ def rooftop_pv_power( latitude: float, longitude: float, output_parameters: List[str], **kwargs ) -> PandafiableResponse: """ - Get basic rooftop PV power forecasts from the present time up to 14 days ahead - for the requested location, derived from satellite (clouds and irradiance - over non-polar continental areas, nowcasted for approx. four hours ahead) - and numerical weather models (other data and longer horizons). + Get basic rooftop PV power forecasts from the present time up to 14 days ahead for + the requested location, derived from satellite (clouds and irradiance over non-polar + continental areas, nowcasted for approx. four hours ahead) and numerical weather + models (other data and longer horizons). + + The basic rooftop power simulation is only suitable for residential and smaller C&I + rooftop sites, not for grid-scale sites. Args: - latitude: in decimal degrees, between -90 and 90, north is positive - longitude: in decimal degrees, between -180 and 180, east is positive - output_parameters: list of strings with the parameters to return + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. + output_parameters: The output parameters to include in the response. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. @@ -65,7 +74,7 @@ def rooftop_pv_power( client = Client( base_url=base_url, endpoint=forecast_rooftop_pv_power, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) return client.get( @@ -81,13 +90,13 @@ def rooftop_pv_power( def advanced_pv_power(resource_id: int, **kwargs) -> PandafiableResponse: """ - Get high spec PV power forecasts from the present time up to 14 days ahead - for the requested site, derived from satellite (clouds and irradiance over - non-polar continental areas, nowcasted for approx. four hours ahead) and - numerical weather models (other data and longer horizons). + Get high-spec PV power forecasts for the requested site from the present up to 14 + days ahead, derived from satellite (clouds and irradiance over non-polar continental + areas, nowcasted for approx. four hours ahead) and numerical weather models (other + data and longer horizons). Args: - resource_id: a Solcast resource id + resource_id: The resource id of the resource. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. @@ -95,7 +104,7 @@ def advanced_pv_power(resource_id: int, **kwargs) -> PandafiableResponse: client = Client( base_url=base_url, endpoint=forecast_advanced_pv_power, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) return client.get({"resource_id": resource_id, "format": "json", **kwargs}) @@ -106,28 +115,29 @@ def soiling_kimber( longitude: float, **kwargs, ) -> PandafiableResponse: - """Get hourly soiling loss forecast using the Kimber model. - - Returns a time series of forecast cumulative soiling / cleanliness state for the - requested location based on Pvlib's Kimber model. + """ + Get soiling loss forecasts using the Kimber model for the requested location from + the present up to 14 days ahead. Args: - latitude: Decimal degrees, between -90 and 90 (north positive). - longitude: Decimal degrees, between -180 and 180 (east positive). - **kwargs: Additional query parameters accepted by the endpoint (e.g. depo_veloc_pm10, initial_soiling). + latitude: The latitude of the location (EPSG:4326). Must be between -90 and 90. + longitude: The longitude of the location (EPSG:4326). Must be between -180 and + 180. + **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API Returns: PandafiableResponse: Response object; call `.to_pandas()` for a DataFrame. - See https://docs.solcast.com.au/ for full parameter details. + See https://docs.solcast.com.au/ for full list of parameters. """ url = kwargs.pop("base_url", base_url) client = Client( base_url=url, endpoint=forecast_soiling_kimber, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) + return client.get( { "latitude": latitude, @@ -143,27 +153,30 @@ def soiling_hsu( longitude: float, **kwargs, ) -> PandafiableResponse: - """Get hourly soiling loss forecast using the HSU model. - - Returns a time series of forecast cumulative soiling / cleanliness state for the - requested location based on Solcast's HSU model. + """ + Get soiling loss forecasts using the HSU model for the requested location from the + present up to 14 days ahead. - Args: - latitude: Decimal degrees, between -90 and 90 (north positive). - longitude: Decimal degrees, between -180 and 180 (east positive). - **kwargs: Additional query parameters accepted by the endpoint (e.g. depo_veloc_pm10, initial_soiling). + Args: + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. + **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API - Returns: - PandafiableResponse: Response object; call `.to_pandas()` for a DataFrame. + Returns: + PandafiableResponse: Response object; call `.to_pandas()` for a DataFrame. - See https://docs.solcast.com.au/ for full parameter details. + See https://docs.solcast.com.au/ for full list of parameters. """ url = kwargs.pop("base_url", base_url) + client = Client( base_url=url, endpoint=forecast_soiling_hsu, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) + return client.get( { "latitude": latitude, @@ -172,3 +185,53 @@ def soiling_hsu( **kwargs, } ) + + +def premium_pv_power(resource_id: str, **kwargs) -> PandafiableResponse: + """ + Get Forecast Premium PV + + Args: + resource_id: The resource id of the resource. + **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API + + See https://docs.solcast.com.au/ for full list of parameters. + """ + client = Client( + base_url=base_url, + endpoint=forecast_premium_pv_power, + response_type=PandafiableResponse, + ) + + return client.get( + { + "resource_id": resource_id, + "format": "json", + **kwargs, + } + ) + + +def premium_wind_power(resource_id: str, **kwargs) -> PandafiableResponse: + """ + Get Forecast Premium Wind + + Args: + resource_id: The resource id of the resource. + **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API + + See https://docs.solcast.com.au/ for full list of parameters. + """ + client = Client( + base_url=base_url, + endpoint=forecast_premium_wind_power, + response_type=PandafiableResponse, + ) + + return client.get( + { + "resource_id": resource_id, + "format": "json", + **kwargs, + } + ) diff --git a/solcast/historic.py b/solcast/historic.py index f8f549a..05eee11 100644 --- a/solcast/historic.py +++ b/solcast/historic.py @@ -20,27 +20,38 @@ def radiation_and_weather( **kwargs, ) -> PandafiableResponse: """ - Get historical irradiance and weather estimated actuals for up to 31 days of data - at a time for a requested location, derived from satellite (clouds and irradiance - over non-polar continental areas) and numerical weather models (other data). - Data is available from 2007-01-01T00:00Z up to real time estimated actuals. + Get historical irradiance and weather estimated actuals for up to 31 days of data at + a time for a requested location, derived from satellite (clouds and irradiance over + non-polar continental areas) and numerical weather models (other data). Data is + available from 2007-01-01T00:00Z to 7 days ago. Args: - latitude: in decimal degrees, between -90 and 90, north is positive - longitude: in decimal degrees, between -180 and 180, east is positive - start: datetime-like, first day of the requested period - end: optional, datetime-like, last day of the requested period - duration: optional, ISO_8601 compliant duration for the historic data. - Must be within 31 days of the start_date. + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. + start: ISO_8601 compliant starting datetime for the historical data. If the + supplied value does not specify a timezone, the timezone will be inferred + from the time_zone parameter, if supplied. Otherwise UTC is assumed. + end: Must include one of end_date and duration. ISO_8601 compliant ending + datetime for the historical data. Must be within 31 days of the start_date. + If the supplied value does not specify a timezone, the timezone will be + inferred from the time_zone parameter, if supplied. Otherwise UTC is + assumed. + duration: Must include one of end_date and duration. ISO_8601 compliant duration + for the historical data. Must be within 31 days of the start_date. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. """ + assert (end is None and duration is not None) | ( + duration is None and end is not None + ), "only one of duration or end" client = Client( base_url=base_url, endpoint=historic_radiation_and_weather, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) params = { @@ -69,31 +80,39 @@ def rooftop_pv_power( ) -> PandafiableResponse: """ Get historical basic rooftop PV power estimated actuals for the requested location, - derived from satellite (clouds and irradiance over non-polar continental areas) - and numerical weather models (other data). + derived from satellite (clouds and irradiance over non-polar continental areas) and + numerical weather models (other data). Data is available from 2007-01-01T00:00Z to 7 + days ago. Args: - latitude: in decimal degrees, between -90 and 90, north is positive - longitude: in decimal degrees, between -180 and 180, east is positive - start: datetime-like, first day of the requested period - end: optional, datetime-like, last day of the requested period - duration: optional, ISO_8601 compliant duration for the historic data. - Must be within 31 days of the start_date. + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. + start: ISO_8601 compliant starting datetime for the historical data. If the + supplied value does not specify a timezone, the timezone will be inferred + from the time_zone parameter, if supplied. Otherwise UTC is assumed. + end: Must include one of end_date and duration. ISO_8601 compliant ending + datetime for the historical data. Must be within 31 days of the start_date. + If the supplied value does not specify a timezone, the timezone will be + inferred from the time_zone parameter, if supplied. Otherwise UTC is + assumed. + duration: Must include one of end_date and duration. ISO_8601 compliant duration + for the historical data. Must be within 31 days of the start_date. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. """ + assert (end is None and duration is not None) | ( + duration is None and end is not None + ), "only one of duration or end" client = Client( base_url=base_url, endpoint=historic_rooftop_pv_power, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) - assert (end is None and duration is not None) | ( - duration is None and end is not None - ), "only one of duration or end" - params = { "latitude": latitude, "longitude": longitude, @@ -118,35 +137,41 @@ def advanced_pv_power( **kwargs, ) -> PandafiableResponse: """ - Get historical high spec PV power estimated actuals for the requested site, - derived from satellite (clouds and irradiance over non-polar continental areas) - and numerical weather models (other data). + Get historical advanced PV power estimated actuals for the requested location, + derived from satellite (clouds and irradiance over non-polar continental areas) and + numerical weather models (other data). Data is available from 2007-01-01T00:00Z to 7 + days ago. Args: - resource_id: a Solcast resource id - start: datetime-like, first day of the requested period - end: optional, datetime-like, last day of the requested period - duration: optional, ISO_8601 compliant duration for the historic data. - Must be within 31 days of the start_date. + resource_id: The resource id of the resource. + start: ISO_8601 compliant starting datetime for the historical data. If the + supplied value does not specify a timezone, the timezone will be inferred + from the time_zone parameter, if supplied. Otherwise UTC is assumed. + end: Must include one of end_date and duration. ISO_8601 compliant ending + datetime for the historical data. Must be within 31 days of the start_date. + If the supplied value does not specify a timezone, the timezone will be + inferred from the time_zone parameter, if supplied. Otherwise UTC is + assumed. + duration: Must include one of end_date and duration. ISO_8601 compliant duration + for the historical data. Must be within 31 days of the start_date. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. """ + assert (end is None and duration is not None) | ( + duration is None and end is not None + ), "only one of duration or end" + client = Client( base_url=base_url, endpoint=historic_advanced_pv_power, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) - assert (end is None and duration is not None) | ( - duration is None and end is not None - ), "only one of duration or end" - params = { "resource_id": resource_id, "start": start, "format": "json", - "format": "json", **kwargs, } @@ -166,33 +191,43 @@ def soiling_kimber( duration: Optional[str] = None, **kwargs, ) -> PandafiableResponse: - """Get hourly historical soiling loss using the Kimber model. - - Returns a time series of estimated historical cumulative soiling / cleanliness state - for the requested location based on Pvlib's Kimber model. + """ + Get historical soiling loss using the Kimber model for up to 31 days of data at a + time for a requested location. Data is available from 2007-01-01T00:00Z to 7 days + ago. Args: - latitude: Decimal degrees, between -90 and 90 (north positive). - longitude: Decimal degrees, between -180 and 180 (east positive). - start: Datetime-like (YYYY-MM-DD or ISO8601) start of period. - end: Optional, end of requested period (mutually exclusive with duration). - duration: Optional, ISO8601 duration within 31 days of start (mutually exclusive with end). - **kwargs: Additional query parameters accepted by the endpoint (e.g. depo_veloc_pm10, initial_soiling). + latitude: The latitude of the location (EPSG:4326). Must be between -90 and 90. + longitude: The longitude of the location (EPSG:4326). Must be between -180 and + 180. + start: ISO_8601 compliant starting datetime for the historical data. If the + supplied value does not specify a timezone, the timezone will be inferred + from the time_zone parameter, if supplied. Otherwise UTC is assumed. + end: ISO_8601 compliant ending datetime for the historical data. Must be within + 31 days of the start_date. Only one of end or duration should be part of the + request. If the supplied value does not specify a timezone, the timezone + will be inferred from the time_zone parameter, if supplied. Otherwise UTC is + assumed. + duration: ISO_8601 compliant duration for the historical data. Must be within 31 + days of the start_date. Only one of end or duration should be part of the + request. + **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API Returns: PandafiableResponse: Response object; call `.to_pandas()` for a DataFrame. - See https://docs.solcast.com.au/ for full parameter details. + See https://docs.solcast.com.au/ for full list of parameters. """ assert (end is None and duration is not None) | ( duration is None and end is not None ), "only one of duration or end" url = kwargs.pop("base_url", base_url) + client = Client( base_url=url, endpoint=historic_soiling_kimber, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) params = { @@ -220,33 +255,43 @@ def soiling_hsu( base_url=base_url, **kwargs, ) -> PandafiableResponse: - """Get hourly historical soiling loss using the HSU model. - - Returns a time series of estimated historical cumulative soiling / cleanliness state - for the requested location based on Solcast's HSU model. + """ + Get historical soiling loss using the HSU model for up to 31 days of data at a time + for a requested location. Data is available from 2007-01-01T00:00Z to 7 days ago. Args: - latitude: Decimal degrees, between -90 and 90 (north positive). - longitude: Decimal degrees, between -180 and 180 (east positive). - start: Datetime-like (YYYY-MM-DD or ISO8601) start of period. - end: Optional, end of requested period (mutually exclusive with duration). - duration: Optional, ISO8601 duration within 31 days of start (mutually exclusive with end). - **kwargs: Additional query parameters accepted by the endpoint (e.g. depo_veloc_pm10, initial_soiling). + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. + start: ISO_8601 compliant starting datetime for the historical data. If the + supplied value does not specify a timezone, the timezone will be inferred + from the time_zone parameter, if supplied. Otherwise UTC is assumed. + end: ISO_8601 compliant ending datetime for the historical data. Must be within + 31 days of the start_date. Only one of end or duration should be part of the + request. If the supplied value does not specify a timezone, the timezone + will be inferred from the time_zone parameter, if supplied. Otherwise UTC is + assumed. + duration: ISO_8601 compliant duration for the historical data. Must be within 31 + days of the start_date. Only one of end or duration should be part of the + request. + **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API Returns: PandafiableResponse: Response object; call `.to_pandas()` for a DataFrame. - See https://docs.solcast.com.au/ for full parameter details. + See https://docs.solcast.com.au/ for full list of parameters. """ assert (end is None and duration is not None) | ( duration is None and end is not None ), "only one of duration or end" url = kwargs.pop("base_url", base_url) + client = Client( base_url=url, endpoint=historic_soiling_hsu, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) params = { diff --git a/solcast/live.py b/solcast/live.py index 3cbb478..db8505c 100644 --- a/solcast/live.py +++ b/solcast/live.py @@ -6,20 +6,25 @@ live_advanced_pv_power, live_radiation_and_weather, live_rooftop_pv_power, + live_soiling_hsu, + live_soiling_kimber, ) def radiation_and_weather( latitude: float, longitude: float, output_parameters: List[str], **kwargs ) -> PandafiableResponse: - """Get irradiance and weather estimated actuals for near real-time and past 7 days - for the requested location, derived from satellite (clouds and irradiance - over non-polar continental areas) and numerical weather models (other data). + """ + Get irradiance and weather estimated actuals for near real-time and past 7 days for + the requested location, derived from satellite (clouds and irradiance over non-polar + continental areas) and numerical weather models (other data). Args: - latitude: in decimal degrees, between -90 and 90, north is positive - longitude: in decimal degrees, between -180 and 180, east is positive - output_parameters: list of strings with the parameters to return + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. + output_parameters: The output parameters to include in the response. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. @@ -30,30 +35,33 @@ def radiation_and_weather( response_type=PandafiableResponse, ) - params = { - "latitude": latitude, - "longitude": longitude, - "output_parameters": output_parameters, - "format": "json", - **kwargs, - } - - res = client.get(params) - - return res + return client.get( + { + "latitude": latitude, + "longitude": longitude, + "output_parameters": output_parameters, + "format": "json", + **kwargs, + } + ) def rooftop_pv_power( latitude: float, longitude: float, **kwargs ) -> PandafiableResponse: - """Get basic rooftop PV power estimated actuals from the present time up to 14 days ahead - for the requested location, derived from satellite (clouds and irradiance over - non-polar continental areas, nowcasted for approx. four hours ahead) and numerical - weather models (other data and longer horizons). + """ + Get basic rooftop PV power estimated actuals for near real-time and past 7 days for + the requested location, derived from satellite (clouds and irradiance over non-polar + continental areas) and numerical weather models (other data). + + The basic rooftop power simulation is only suitable for residential and smaller C&I + rooftop sites, not for grid-scale sites. Args: - latitude: in decimal degrees, between -90 and 90, north is positive - longitude: in decimal degrees, between -180 and 180, east is positive + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. @@ -65,19 +73,23 @@ def rooftop_pv_power( ) return client.get( - {"latitude": latitude, "longitude": longitude, "format": "json", **kwargs} + { + "latitude": latitude, + "longitude": longitude, + "format": "json", + **kwargs, + } ) def advanced_pv_power(resource_id: int, **kwargs) -> PandafiableResponse: """ - Get high spec PV power estimated actuals from the present time up to 14 days ahead for - the requested site, derived from satellite (clouds and irradiance - over non-polar continental areas, nowcasted for approx. four hours ahead) - and numerical weather models (other data and longer horizons). + Get high spec PV power estimated actuals for near real-time and past 7 days for the + requested site, derived from satellite (clouds and irradiance over non-polar + continental areas) and numerical weather models (other data). Args: - resource_id: a Solcast resource id + resource_id: The resource id of the resource. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. @@ -96,29 +108,30 @@ def soiling_hsu( longitude: float, **kwargs, ) -> PandafiableResponse: - """Get hourly soiling loss using the HSU model. - - Returns a time series of estimated cumulative soiling / cleanliness state for the - requested location based on Solcast's HSU model. + """ + Get soiling loss estimated actuals using the HSU model for near real-time and past 7 + days for the requested location. Args: - latitude: Decimal degrees, between -90 and 90 (north positive). - longitude: Decimal degrees, between -180 and 180 (east positive). - **kwargs: Additional query parameters accepted by the endpoint (e.g. depo_veloc_pm10, initial_soiling). + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. + **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API Returns: PandafiableResponse: Response object; call `.to_pandas()` for a DataFrame. - See https://docs.solcast.com.au/ for full parameter details. + See https://docs.solcast.com.au/ for full list of parameters. """ - from solcast.urls import live_soiling_hsu - url = kwargs.pop("base_url", base_url) + client = Client( base_url=url, endpoint=live_soiling_hsu, response_type=PandafiableResponse, ) + return client.get( { "latitude": latitude, @@ -135,29 +148,29 @@ def soiling_kimber( base_url=base_url, **kwargs, ) -> PandafiableResponse: - """Get hourly soiling loss using the Kimber model. - - Returns a time series of estimated cumulative soiling / cleanliness state for the - requested location based on Pvlib's Kimber model. + """ + Get soiling loss estimated actuals using the Kimber model for near real-time and + past 7 days for the requested location. Args: - latitude: Decimal degrees, between -90 and 90 (north positive). - longitude: Decimal degrees, between -180 and 180 (east positive). - **kwargs: Additional query parameters accepted by the endpoint (e.g. depo_veloc_pm10, initial_soiling). + latitude: The latitude of the location (EPSG:4326). Must be between -90 and 90. + longitude: The longitude of the location (EPSG:4326). Must be between -180 and + 180. + **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API Returns: PandafiableResponse: Response object; call `.to_pandas()` for a DataFrame. - See https://docs.solcast.com.au/ for full parameter details. + See https://docs.solcast.com.au/ for full list of parameters. """ - from solcast.urls import live_soiling_kimber - url = kwargs.pop("base_url", base_url) + client = Client( base_url=url, endpoint=live_soiling_kimber, - response_type=PandafiableResponse, # type: ignore[arg-type] + response_type=PandafiableResponse, ) + return client.get( { "latitude": latitude, diff --git a/solcast/pv_power_sites.py b/solcast/pv_power_sites.py index 696c002..e4447af 100644 --- a/solcast/pv_power_sites.py +++ b/solcast/pv_power_sites.py @@ -4,7 +4,9 @@ def list_pv_power_sites(**kwargs) -> Response: """ - List available PV power sites. + Lists all PV power sites accessible to the authenticated user. Supports pagination + (skip/take), entitlement filtering (advanced/premium), and date range filtering + (start/end). Args: **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API @@ -13,30 +15,22 @@ def list_pv_power_sites(**kwargs) -> Response: """ client = Client(base_url=base_url, endpoint=pv_power_sites, response_type=Response) - params = {"format": "json", **kwargs} - - res = client.get(params) - - return res + return client.get({"format": "json", **kwargs}) def get_pv_power_site(resource_id: str, **kwargs) -> Response: """ - Get an existing PV power site's specifications. + Get Resource Args: - resource_id: unique string to identify the location that was generated when creating a site + resource_id: The unique identifier of the resource. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. """ client = Client(base_url=base_url, endpoint=pv_power_site, response_type=Response) - params = {"resource_id": resource_id, "format": "json", **kwargs} - - res = client.get(params) - - return res + return client.get({"resource_id": resource_id, "format": "json", **kwargs}) def create_pv_power_site( @@ -46,91 +40,71 @@ def create_pv_power_site( **kwargs, ) -> Response: """ - Create PV power site to be used with Solcast's advanced PV power model. + Create Resource Args: - name: arbitrary string to identify the location, unique not required - latitude: in decimal degrees, between -90 and 90, north is positive - longitude: in decimal degrees, between -180 and 180, east is positive + name: The name of the resource. + latitude: The latitude of the resource. Must be a decimal number between -90 and + 90. + longitude: The longitude of the resource. Must be a decimal number between -180 + and 180. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API - See https://docs.solcast.com.au/ for more information and full list of parameters. + See https://docs.solcast.com.au/ for full list of parameters. """ client = Client(base_url=base_url, endpoint=pv_power_site, response_type=Response) - params = { - "name": name, - "latitude": latitude, - "longitude": longitude, - "format": "json", - **kwargs, - } - - res = client.post(params) - - return res + return client.post( + { + "name": name, + "latitude": latitude, + "longitude": longitude, + "format": "json", + **kwargs, + } + ) def patch_pv_power_site(resource_id: str, **kwargs) -> Response: """ - Patch an existing PV power site to partially update the site's specifications. + Patch Resource Args: - resource_id: unique string to identify the location that is generated when creating a site + resource_id: The unique identifier of the resource. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. """ client = Client(base_url=base_url, endpoint=pv_power_site, response_type=Response) - params = { - "resource_id": resource_id, - "format": "json", - **kwargs, - } - - res = client.patch(params) - - return res + return client.patch({"resource_id": resource_id, "format": "json", **kwargs}) def update_pv_power_site(resource_id: str, **kwargs) -> Response: """ - Overwrite an existing PV power site's specifications. + Update Resource Args: - resource_id: unique string to identify the location that is generated when creating a site + resource_id: The unique identifier of the resource. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. """ client = Client(base_url=base_url, endpoint=pv_power_site, response_type=Response) - params = { - "resource_id": resource_id, - "format": "json", - **kwargs, - } - - res = client.put(params) - - return res + return client.put({"resource_id": resource_id, "format": "json", **kwargs}) def delete_pv_power_site(resource_id: str, **kwargs) -> Response: """ - Delete an existing PV power site. + Remove Resource Args: - resource_id: unique string to identify the location that is generated when creating a site + resource_id: The unique identifier of the resource. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. """ client = Client(base_url=base_url, endpoint=pv_power_site, response_type=Response) - params = {"resource_id": resource_id, "format": "json", **kwargs} - - res = client.delete(params) - - return res + return client.delete({"resource_id": resource_id, "format": "json", **kwargs}) diff --git a/solcast/tmy.py b/solcast/tmy.py index b98c86a..2da3141 100644 --- a/solcast/tmy.py +++ b/solcast/tmy.py @@ -6,18 +6,20 @@ def radiation_and_weather( latitude: float, longitude: float, **kwargs ) -> PandafiableResponse: """ - Get the irradiance and weather for a Typical Meteorological Year (TMY) at a requested location, - derived from satellite (clouds and irradiance over non-polar continental areas) and - numerical weather models (other data). The TMY is calculated with data from 2007 to 2023. + Get the irradiance and weather for a Typical Meteorological Year (TMY) at a + requested location, derived from satellite (clouds and irradiance over non-polar + continental areas) and numerical weather models (other data). The TMY is calculated + with data from 2007 to 2025. Args: - latitude: in decimal degrees, between -90 and 90, north is positive - longitude: in decimal degrees, between -180 and 180, east is positive + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. """ - client = Client( base_url=base_url, endpoint=tmy_radiation_and_weather, @@ -25,7 +27,12 @@ def radiation_and_weather( ) return client.get( - {"latitude": latitude, "longitude": longitude, "format": "json", **kwargs} + { + "latitude": latitude, + "longitude": longitude, + "format": "json", + **kwargs, + } ) @@ -33,18 +40,20 @@ def rooftop_pv_power( latitude: float, longitude: float, **kwargs ) -> PandafiableResponse: """ - Get the basic rooftop PV power estimated actuals for a Typical Meteorological Year (TMY) at a requested location, - derived from satellite (clouds and irradiance over non-polar continental areas) and - numerical weather models (other data). The TMY is calculated with data from 2007 to 2023. + Get the basic rooftop PV power estimated actuals for a Typical Meteorological Year + (TMY) at a requested location, derived from satellite (clouds and irradiance over + non-polar continental areas) and numerical weather models (other data). The TMY is + calculated with data from 2007 to 2025. Args: - latitude: in decimal degrees, between -90 and 90, north is positive - longitude: in decimal degrees, between -180 and 180, east is positive + latitude: The latitude of the location you request data for. Must be a decimal + number between -90 and 90. + longitude: The longitude of the location you request data for. Must be a decimal + number between -180 and 180. **kwargs: additional keyword arguments to be passed through as URL parameters to the Solcast API See https://docs.solcast.com.au/ for full list of parameters. """ - client = Client( base_url=base_url, endpoint=tmy_rooftop_pv_power, @@ -52,5 +61,10 @@ def rooftop_pv_power( ) return client.get( - {"latitude": latitude, "longitude": longitude, "format": "json", **kwargs} + { + "latitude": latitude, + "longitude": longitude, + "format": "json", + **kwargs, + } ) diff --git a/solcast/urls.py b/solcast/urls.py index ce7e236..e0bc78d 100644 --- a/solcast/urls.py +++ b/solcast/urls.py @@ -13,6 +13,8 @@ forecast_radiation_and_weather = "data/forecast/radiation_and_weather" forecast_rooftop_pv_power = "data/forecast/rooftop_pv_power" forecast_advanced_pv_power = "data/forecast/advanced_pv_power" +forecast_premium_pv_power = "data/forecast/premium_pv_power" +forecast_premium_wind_power = "data/forecast/premium_wind_power" forecast_grid_aggregations = "data/forecast/aggregations" forecast_soiling_kimber = "data/forecast/soiling/kimber" forecast_soiling_hsu = "data/forecast/soiling/hsu"