# Frequenz Weather API Client
[](https://github.com/frequenz-floss/frequenz-client-weather-python/actions/workflows/ci.yaml)
[](https://pypi.org/project/frequenz-client-weather/)
[](https://frequenz-floss.github.io/frequenz-client-weather-python/)
## Introduction
Weather API Client for Python providing access to historical and live weather forecast data.
## Supported Platforms
The following platforms are officially supported (tested):
- **Python:** 3.11
- **Operating System:** Ubuntu Linux 20.04
- **Architectures:** amd64, arm64
## Contributing
If you want to know how to build this project and contribute to it, please
check out the [Contributing Guide](CONTRIBUTING.md).
## Usage
### Installation
```bash
pip install frequenz-client-weather
```
### Available Features
The available features are listed [here](https://github.com/frequenz-floss/frequenz-api-weather/blob/v0.x.x/proto/frequenz/api/weather/weather.proto#L42).
### Initialize the client
The Client can optionally be initialized with keep alive.
```python
from frequenz.client.weather import Client
from frequenz.client.base.channel import ChannelOptions, KeepAliveOptions, SslOptions
from datetime import timedelta
client = Client(
service_address,
channel_defaults=ChannelOptions(
ssl=SslOptions(
enabled=False,
),
keep_alive=KeepAliveOptions(
enabled=True,
timeout=timedelta(minutes=5),
interval=timedelta(seconds=20),
),
),
)
```
### Get historical weather forecast
```python
from datetime import datetime
import pandas as pd
from frequenz.client.weather._types import ForecastFeature, Location
# Define a list of locations, features and a time range to request historical forecasts for
locations = [Location(latitude=46.2276, longitude=15.2137, country_code="DE")]
features = [ForecastFeature.TEMPERATURE_2_METRE, ForecastFeature.V_WIND_COMPONENT_10_METRE]
start = datetime(2024, 1, 1)
end = datetime(2024, 1, 31)
forecast_iterator = await client.stream_historical_forecast(
features=features, locations=locations, start=start, end=end
)
# Collect and flatten forecasts
flat_forecasts = [f.flatten() async for f in forecast_iterator]
forecast_records = [record for batch in flat_forecasts for record in batch]
# E.g. convert to DataFrame and sort
forecast_df = pd.DataFrame(forecast_records).sort_values(["create_time", "valid_time", "latitude", "longitude"])
print(forecast_df)
```
### Get live weather forecast
```python
import pandas as pd
from frequenz.client.weather._types import ForecastFeature, Location
# Define a list of locations and features to request live forecasts for
locations = [Location(latitude=46.2276, longitude=15.2137, country_code="DE")]
features = [ForecastFeature.TEMPERATURE_2_METRE, ForecastFeature.V_WIND_COMPONENT_10_METRE]
# Returns a Receiver object that can be iterated over asynchronously
stream = await client.stream_live_forecast(
locations=locations,
features=features,
)
# Process incoming forecasts as they arrive
async for forecast in stream:
# The to_ndarray_vlf method converts the forecast data to a 3D numpy array,
# where the dimensions correspond to validity_ts, location, feature
# The method can also take filters for validity_ts, locations and features
# E.g. filter the forecast for wind features
wind_forecast = forecast.to_ndarray_vlf(features=[ForecastFeature.V_WIND_COMPONENT_10_METRE])
print(wind_forecast)
```
## Command Line Interface
The package also provides a command line interface to get weather forecast data.
Use `-h` to see the available options.
### Get historical weather forecast
```bash
weather-cli \
--url <service-address> \
--location "40,15" \
--feature U_WIND_COMPONENT_100_METRE \
--start 2024-03-14 \
--end 2024-03-15 \
--mode historical
```
### Get live weather forecast
```bash
weather-cli \
--url <service-address> \
--location "40, 15" \
--feature TEMPERATURE_2_METRE \
--mode live
```
Raw data
{
"_id": null,
"home_page": null,
"name": "frequenz-client-weather",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.11",
"maintainer_email": null,
"keywords": "frequenz, python, lib, library, client-weather",
"author": null,
"author_email": "Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>",
"download_url": "https://files.pythonhosted.org/packages/7d/47/47a3f940afb197f55e639d8171c82dc8beaeddb1a07a0b702537ce2e071e/frequenz_client_weather-0.3.1.tar.gz",
"platform": null,
"description": "# Frequenz Weather API Client\n\n[](https://github.com/frequenz-floss/frequenz-client-weather-python/actions/workflows/ci.yaml)\n[](https://pypi.org/project/frequenz-client-weather/)\n[](https://frequenz-floss.github.io/frequenz-client-weather-python/)\n\n## Introduction\n\nWeather API Client for Python providing access to historical and live weather forecast data.\n\n## Supported Platforms\n\nThe following platforms are officially supported (tested):\n\n- **Python:** 3.11\n- **Operating System:** Ubuntu Linux 20.04\n- **Architectures:** amd64, arm64\n\n## Contributing\n\nIf you want to know how to build this project and contribute to it, please\ncheck out the [Contributing Guide](CONTRIBUTING.md).\n\n## Usage\n\n### Installation\n\n```bash\npip install frequenz-client-weather\n```\n\n### Available Features\n\nThe available features are listed [here](https://github.com/frequenz-floss/frequenz-api-weather/blob/v0.x.x/proto/frequenz/api/weather/weather.proto#L42).\n\n### Initialize the client\n\nThe Client can optionally be initialized with keep alive.\n\n```python\nfrom frequenz.client.weather import Client\nfrom frequenz.client.base.channel import ChannelOptions, KeepAliveOptions, SslOptions\nfrom datetime import timedelta\n\nclient = Client(\n service_address,\n channel_defaults=ChannelOptions(\n ssl=SslOptions(\n enabled=False,\n ),\n keep_alive=KeepAliveOptions(\n enabled=True,\n timeout=timedelta(minutes=5),\n interval=timedelta(seconds=20),\n ),\n ),\n)\n```\n\n### Get historical weather forecast\n\n```python\nfrom datetime import datetime\nimport pandas as pd\nfrom frequenz.client.weather._types import ForecastFeature, Location\n\n# Define a list of locations, features and a time range to request historical forecasts for\nlocations = [Location(latitude=46.2276, longitude=15.2137, country_code=\"DE\")]\nfeatures = [ForecastFeature.TEMPERATURE_2_METRE, ForecastFeature.V_WIND_COMPONENT_10_METRE]\nstart = datetime(2024, 1, 1)\nend = datetime(2024, 1, 31)\n\nforecast_iterator = await client.stream_historical_forecast(\n features=features, locations=locations, start=start, end=end\n)\n\n# Collect and flatten forecasts\nflat_forecasts = [f.flatten() async for f in forecast_iterator]\nforecast_records = [record for batch in flat_forecasts for record in batch]\n\n# E.g. convert to DataFrame and sort\nforecast_df = pd.DataFrame(forecast_records).sort_values([\"create_time\", \"valid_time\", \"latitude\", \"longitude\"])\nprint(forecast_df)\n```\n\n### Get live weather forecast\n\n```python\nimport pandas as pd\nfrom frequenz.client.weather._types import ForecastFeature, Location\n\n# Define a list of locations and features to request live forecasts for\nlocations = [Location(latitude=46.2276, longitude=15.2137, country_code=\"DE\")]\nfeatures = [ForecastFeature.TEMPERATURE_2_METRE, ForecastFeature.V_WIND_COMPONENT_10_METRE]\n\n# Returns a Receiver object that can be iterated over asynchronously\nstream = await client.stream_live_forecast(\n locations=locations,\n features=features,\n)\n\n# Process incoming forecasts as they arrive\nasync for forecast in stream:\n # The to_ndarray_vlf method converts the forecast data to a 3D numpy array,\n # where the dimensions correspond to validity_ts, location, feature\n # The method can also take filters for validity_ts, locations and features\n # E.g. filter the forecast for wind features\n wind_forecast = forecast.to_ndarray_vlf(features=[ForecastFeature.V_WIND_COMPONENT_10_METRE])\n print(wind_forecast)\n\n```\n## Command Line Interface\n\nThe package also provides a command line interface to get weather forecast data.\nUse `-h` to see the available options.\n\n### Get historical weather forecast\n\n```bash\nweather-cli \\\n --url <service-address> \\\n --location \"40,15\" \\\n --feature U_WIND_COMPONENT_100_METRE \\\n --start 2024-03-14 \\\n --end 2024-03-15 \\\n --mode historical\n```\n\n### Get live weather forecast\n\n```bash\nweather-cli \\\n --url <service-address> \\\n --location \"40, 15\" \\\n --feature TEMPERATURE_2_METRE \\\n --mode live\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Weather API Client for Python",
"version": "0.3.1",
"project_urls": {
"Changelog": "https://github.com/frequenz-floss/frequenz-client-weather-python/releases",
"Documentation": "https://frequenz-floss.github.io/frequenz-client-weather-python/",
"Issues": "https://github.com/frequenz-floss/frequenz-client-weather-python/issues",
"Repository": "https://github.com/frequenz-floss/frequenz-client-weather-python",
"Support": "https://github.com/frequenz-floss/frequenz-client-weather-python/discussions/categories/support"
},
"split_keywords": [
"frequenz",
" python",
" lib",
" library",
" client-weather"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "904ab2c8812269d000210ca123ea35cb987c28863a3858934619e729905d4934",
"md5": "c2beb7a466df5ae283d94b5a058bdd58",
"sha256": "965db0cd6f3f03bed8f039cd62add96b494b25935c91c180ae892095a7e6404e"
},
"downloads": -1,
"filename": "frequenz_client_weather-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2beb7a466df5ae283d94b5a058bdd58",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.11",
"size": 13737,
"upload_time": "2025-08-20T13:58:30",
"upload_time_iso_8601": "2025-08-20T13:58:30.551343Z",
"url": "https://files.pythonhosted.org/packages/90/4a/b2c8812269d000210ca123ea35cb987c28863a3858934619e729905d4934/frequenz_client_weather-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7d4747a3f940afb197f55e639d8171c82dc8beaeddb1a07a0b702537ce2e071e",
"md5": "27330d1fb2d85e9c384b3aca80a5a40e",
"sha256": "d81c16aebe25536cede6b85f5ddfa2bf6b40eac6226ad7866ccf99bc4ec57cf4"
},
"downloads": -1,
"filename": "frequenz_client_weather-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "27330d1fb2d85e9c384b3aca80a5a40e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.11",
"size": 15825,
"upload_time": "2025-08-20T13:58:31",
"upload_time_iso_8601": "2025-08-20T13:58:31.834726Z",
"url": "https://files.pythonhosted.org/packages/7d/47/47a3f940afb197f55e639d8171c82dc8beaeddb1a07a0b702537ce2e071e/frequenz_client_weather-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 13:58:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "frequenz-floss",
"github_project": "frequenz-client-weather-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "frequenz-client-weather"
}
JSON
