solcast 0.4.0__py3-none-any.whl

solcast/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.4.0"
+
+from . import api, forecast, historic, live, tmy, unmetered_locations, urls
+
+__all__ = ["forecast", "historic", "live", "tmy", "unmetered_locations"]

solcast/api.py

@@ -0,0 +1,148 @@
+import json
+import os
+from dataclasses import dataclass
+from urllib.request import urlopen, Request
+import urllib.parse
+import urllib.error
+
+try:
+    import pandas as pd
+except ImportError:
+    _PANDAS = False
+else:
+    _PANDAS = True
+
+
+@dataclass
+class Response:
+    """Class to handle API response from the Solcast API."""
+
+    code: int
+    url: str
+    data: bytes
+    success: bool
+    exception: str = None
+
+    def __repr__(self):
+        return f"status code={self.code}, url={self.url}"
+
+    def to_dict(self):
+        if self.code != 200:
+            raise Exception(self.exception)
+        return json.loads(self.data)
+
+    def to_pandas(self):
+        """returns the data as a Pandas DataFrame.
+        Some common processing is applied,
+        like casting the datetime columns and setting them as index.
+        """
+        # not ideal to run this for every Response
+        assert _PANDAS, ImportError(
+            "Pandas needs to be installed for this functionality."
+        )
+
+        if self.code != 200:
+            raise Exception(self.exception)
+
+        dfs = [
+            pd.DataFrame.from_records(self.to_dict()[k]) for k in self.to_dict().keys()
+        ]
+        dfs = pd.concat(dfs)
+        dfs.index = pd.DatetimeIndex(dfs["period_end"])
+
+        # to make it work with different Pandas versions
+        if dfs.index.tz is None:
+            dfs.index.tz = "UTC"
+
+        dfs.index.name = "period_end"
+        dfs = dfs.drop(columns=["period_end", "period"])
+
+        return dfs
+
+
+class Client:
+    """Handles all API get requests for the different endpoints."""
+
+    def __init__(self, base_url: str, endpoint: str):
+        """
+        Args:
+            base_url: the base URL to Solcast API
+            endpoint: one of Solcast API's endpoints
+        """
+        self.base_url = base_url
+        self.endpoint = endpoint
+        self.url = self.make_url()
+
+    @staticmethod
+    def check_params(params: dict) -> (dict, str):
+        """runs some basic checks on the parameters that will be passed in the
+        GET request."""
+        assert isinstance(params, dict), "parameters needs to be a dict"
+
+        if "api_key" not in params:
+            params.update({"api_key": os.getenv("SOLCAST_API_KEY")})
+
+        if params["api_key"] is None:
+            raise ValueError("np API key provided.")
+
+        if len(params["api_key"]) <= 1:
+            raise ValueError("API key is too short.")
+
+        if "output_parameters" in params.keys() and isinstance(
+            params["output_parameters"], list
+        ):
+            params["output_parameters"] = ",".join(params["output_parameters"])
+
+        # truncate coordinates to 6 decimal places
+        if "latitude" in params.keys():
+            params["latitude"] = round(params["latitude"], 6)
+        if "longitude" in params.keys():
+            params["longitude"] = round(params["longitude"], 6)
+
+        # only json supported
+        if "format" in params.keys():
+            assert (
+                params["format"] == "json"
+            ), "only json response format is currently supported."
+
+        # api key in the header for secrecy
+        key = params["api_key"]
+        del params["api_key"]
+
+        return params, key
+
+    def make_url(self) -> str:
+        """composes the full URL."""
+        return "/".join([self.base_url, self.endpoint])
+
+    def get(self, params: dict) -> Response:
+        """makes the GET request.
+
+        Args:
+            params: a dictionary of parameters that are passed in the get request
+
+        Returns:
+            a Response object.
+        """
+
+        params, key = self.check_params(params)
+        url = self.url + "?" + urllib.parse.urlencode(params)
+        req = Request(url, headers={"Authorization": f"Bearer {key}"})
+        try:
+            with urlopen(req) as response:
+                body = response.read()
+                return Response(
+                    code=response.code, url=url, data=body, success=True, exception=None
+                )
+        except urllib.error.HTTPError as e:
+            try:
+                exception_message = json.loads(e.read())["response_status"]["message"]
+            except:
+                exception_message = "Undefined Error"
+            return Response(
+                code=e.code,
+                url=e.url,
+                data=None,
+                exception=exception_message,
+                success=False,
+            )

solcast/forecast.py

@@ -0,0 +1,67 @@
+from .api import Client, Response
+from .urls import (
+    base_url,
+    forecast_rooftop_pv_power,
+    forecast_radiation_and_weather,
+    forecast_advanced_pv_power,
+)
+
+
+def radiation_and_weather(
+    latitude: float, longitude: float, output_parameters: str, **kwargs
+) -> Response:
+    """
+    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).
+    """
+    client = Client(base_url=base_url, endpoint=forecast_radiation_and_weather)
+
+    return client.get(
+        {
+            "latitude": latitude,
+            "longitude": longitude,
+            "output_parameters": output_parameters,
+            "format": "json",
+            **kwargs,
+        }
+    )
+
+
+def rooftop_pv_power(
+    latitude: float, longitude: float, output_parameters: str, **kwargs
+) -> Response:
+    """
+    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).
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+    client = Client(base_url=base_url, endpoint=forecast_rooftop_pv_power)
+
+    return client.get(
+        {
+            "latitude": latitude,
+            "longitude": longitude,
+            "output_parameters": output_parameters,
+            "format": "json",
+            **kwargs,
+        }
+    )
+
+
+def advanced_pv_power(resource_id: int, **kwargs) -> Response:
+    """
+    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).
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+    client = Client(base_url=base_url, endpoint=forecast_advanced_pv_power)
+
+    return client.get({"resource_id": resource_id, "format": "json", **kwargs})

solcast/historic.py

@@ -0,0 +1,51 @@
+from .api import Client, Response
+from .urls import base_url, historic_radiation_and_weather, historic_rooftop_pv_power
+
+
+def radiation_and_weather(
+    latitude: float, longitude: float, start: str, **kwargs
+) -> Response:
+    """
+    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.
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+
+    client = Client(base_url=base_url, endpoint=historic_radiation_and_weather)
+
+    return client.get(
+        {
+            "latitude": latitude,
+            "longitude": longitude,
+            "start": start,
+            "format": "json",
+            **kwargs,
+        }
+    )
+
+
+def rooftop_pv_power(
+    latitude: float, longitude: float, start: str, **kwargs
+) -> Response:
+    """
+    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).
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+
+    client = Client(base_url=base_url, endpoint=historic_rooftop_pv_power)
+
+    return client.get(
+        {
+            "latitude": latitude,
+            "longitude": longitude,
+            "start": start,
+            "format": "json",
+            **kwargs,
+        }
+    )

solcast/live.py

@@ -0,0 +1,62 @@
+from typing import List
+
+from .api import Client, Response
+from .urls import (
+    base_url,
+    live_radiation_and_weather,
+    live_rooftop_pv_power,
+    live_advanced_pv_power,
+)
+
+
+def radiation_and_weather(
+    latitude: float, longitude: float, output_parameters: List[str], **kwargs
+) -> Response:
+    """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).
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+    client = Client(base_url=base_url, endpoint=live_radiation_and_weather)
+
+    params = {
+        "latitude": latitude,
+        "longitude": longitude,
+        "output_parameters": output_parameters,
+        "format": "json",
+        **kwargs,
+    }
+
+    res = client.get(params)
+
+    return res
+
+
+def rooftop_pv_power(latitude: float, longitude: float, **kwargs) -> Response:
+    """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).
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+    client = Client(base_url=base_url, endpoint=live_rooftop_pv_power)
+
+    return client.get(
+        {"latitude": latitude, "longitude": longitude, "format": "json", **kwargs}
+    )
+
+
+def advanced_pv_power(resource_id: int, **kwargs) -> Response:
+    """
+    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).
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+    client = Client(base_url=base_url, endpoint=live_advanced_pv_power)
+
+    return client.get({"resource_id": resource_id, "format": "json", **kwargs})

solcast/tmy.py

@@ -0,0 +1,34 @@
+from .api import Client, Response
+from .urls import base_url, tmy_radiation_and_weather, tmy_rooftop_pv_power
+
+
+def radiation_and_weather(latitude: float, longitude: float, **kwargs) -> Response:
+    """
+    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.
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+
+    client = Client(base_url=base_url, endpoint=tmy_radiation_and_weather)
+
+    return client.get(
+        {"latitude": latitude, "longitude": longitude, "format": "json", **kwargs}
+    )
+
+
+def rooftop_pv_power(latitude: float, longitude: float, **kwargs) -> Response:
+    """
+    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.
+
+    See https://docs.solcast.com.au/ for full list of parameters.
+    """
+
+    client = Client(base_url=base_url, endpoint=tmy_rooftop_pv_power)
+
+    return client.get(
+        {"latitude": latitude, "longitude": longitude, "format": "json", **kwargs}
+    )

solcast/unmetered_locations.py

@@ -0,0 +1,44 @@
+UNMETERED_LOCATIONS = {
+    "Sydney Opera House": {
+        "latitude": -33.856784,
+        "longitude": 151.215297,
+        "resource_id": "5f86-4c8f-2cb3-0215",
+    },
+    "Grand Canyon": {
+        "latitude": 36.099763,
+        "longitude": -112.112485,
+        "resource_id": " 375f-eb3e-71c0-ef5e",
+    },
+    "Stonehenge": {
+        "latitude": 51.178882,
+        "longitude": -1.826215,
+        "resource_id": "1a57-6b1f-ec18-c5c8",
+    },
+    "The Colosseum": {
+        "latitude": 41.89021,
+        "longitude": 12.492231,
+        "resource_id": "5f86-4c8f-2cb3-0215",
+    },
+    "Giza Pyramid Complex": {
+        "latitude": 29.977296,
+        "longitude": 31.132496,
+        "resource_id": "8d10-f530-af85-5cbb",
+    },
+    "Taj Mahal": {
+        "latitude": 27.175145,
+        "longitude": 78.042142,
+        "resource_id": "b926-8fd2-ad3f-e4f5",
+    },
+}
+
+
+def load_test_locations_coordinates():
+    """returns longitude, latitude and resource_id for the unmetered locations"""
+    coords = [list(coords.values()) for coords in list(UNMETERED_LOCATIONS.values())]
+    latitudes, longitudes = [c[0] for c in coords], [c[1] for c in coords]
+    return latitudes, longitudes
+
+
+def load_test_locations_names():
+    """returns longitude, latitude and resource_id for the unmetered locations"""
+    return list(UNMETERED_LOCATIONS.keys())

solcast/urls.py

@@ -0,0 +1,11 @@
+base_url = "https://api.solcast.com.au/data"
+live_radiation_and_weather = "live/radiation_and_weather"
+live_rooftop_pv_power = "live/rooftop_pv_power"
+live_advanced_pv_power = "live/advanced_pv_power"
+historic_radiation_and_weather = "historic/radiation_and_weather"
+historic_rooftop_pv_power = "historic/rooftop_pv_power"
+forecast_radiation_and_weather = "forecast/radiation_and_weather"
+forecast_rooftop_pv_power = "forecast/rooftop_pv_power"
+forecast_advanced_pv_power = "forecast/advanced_pv_power"
+tmy_radiation_and_weather = "tmy/radiation_and_weather"
+tmy_rooftop_pv_power = "tmy/rooftop_pv_power"

solcast-0.4.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: solcast
+Version: 0.4.0
+Summary: a simple Python SDK for the Solcast API
+Project-URL: Homepage, https://pypi.org/project/solcast/
+Project-URL: Documentation, https://solcast.github.io/solcast-api-python-sdk
+Project-URL: Repository, https://github.com/Solcast/solcast-api-python-sdk
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.7
+Provides-Extra: all
+Requires-Dist: black; extra == 'all'
+Requires-Dist: matplotlib; extra == 'all'
+Requires-Dist: notebook; extra == 'all'
+Requires-Dist: pandas; extra == 'all'
+Requires-Dist: solcast[docs]; extra == 'all'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-jupyter; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Requires-Dist: pytest; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<img src="https://github.com/Solcast/solcast-api-python-sdk/blob/main/docs/img/logo.png?raw=true" width="100" align="right">
+
+# Solcast API Python SDK
+
+<em>simple Python SDK to access the Solcast API</em>
+
+[![Docs](https://github.com/Solcast/solcast-api-python-sdk/actions/workflows/docs.yml/badge.svg)](https://github.com/Solcast/solcast-api-python-sdk/actions/workflows/docs.yml) [![Tests](https://github.com/Solcast/solcast-api-python-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/Solcast/solcast-api-python-sdk/actions/workflows/test.yml) [![Publish 📦 to PyPI](https://github.com/Solcast/solcast-api-python-sdk/actions/workflows/publish-to-test-pypi.yml/badge.svg)](https://github.com/Solcast/solcast-api-python-sdk/actions/workflows/publish-to-test-pypi.yml)
+
+---
+
+**Documentation**: <a href="https://solcast.github.io/solcast-api-python-sdk/" target="_blank">https://solcast.github.io/solcast-api-python-sdk/ </a>
+
+## Install
+```commandline
+git clone https://github.com/Solcast/solcast-api-python-sdk.git
+cd solcast-api-python-sdk
+pip install .
+# also pip install .[all] for the dev libs
+```
+## Basic Usage
+
+```python
+from solcast import live
+
+df = live.radiation_and_weather(
+    latitude=-33.856784,
+    longitude=151.215297,
+    output_parameters=['air_temp', 'dni', 'ghi']
+).to_pandas()
+```
+---
+
+## Contributing
+```commandline
+pytest tests
+```

solcast-0.4.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+solcast/__init__.py,sha256=TkIXtkdYE9vpCC9GgRzmSXm_ocEs0f141KujcphvPYY,178
+solcast/api.py,sha256=lHgQM9kNlmJZnrgZjjuR6somZx_MRblt_FY2wplVFhg,4578
+solcast/forecast.py,sha256=epJBARPcp5VL4iPXqhSwcJEmQWioMjmGUdcu1o5_B9I,2380
+solcast/historic.py,sha256=ncti6T7jIODJFNcRg46WhKOBb-AHEiawgQgUzCKpqww,1649
+solcast/live.py,sha256=fY4iDVlYrK-4-B-CyofZzNP1PMnd9JwHimRhlnShwY0,2233
+solcast/tmy.py,sha256=vEc65Cqj51_idEGj94_T9rvCxlOcDm2rIpR-30nYmSE,1432
+solcast/unmetered_locations.py,sha256=GIJpokQMiT-P6CT7ba_7LzF3ORP4VQr0IJrN25HXumc,1390
+solcast/urls.py,sha256=-CpwsIuyWUHxMOYSguDoomubV4XifyZBQDnKnRkf71Y,616
+solcast-0.4.0.dist-info/METADATA,sha256=PG5AKcHP6u7oRjxU0WVL-gEEKL4Ak5hemHiZbrSX6lQ,3193
+solcast-0.4.0.dist-info/WHEEL,sha256=9QBuHhg6FNW7lppboF2vKVbCGTVzsFykgRQjjlajrhA,87
+solcast-0.4.0.dist-info/licenses/LICENSE,sha256=HOVcajFymlCFvzClhJHptoL1e7E2W5ibiFug0uaEtyo,563
+solcast-0.4.0.dist-info/RECORD,,

solcast-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.18.0
+Root-Is-Purelib: true
+Tag: py3-none-any

solcast-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,13 @@
+Copyright [2023] [Solcast]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.