Metadata-Version: 2.4 Name: env_canada Version: 0.13.2 Summary: A package to access meteorological data from Environment Canada Author-email: Michael Davie Maintainer-email: Michael Davie License-Expression: MIT Project-URL: Homepage, https://github.com/michaeldavie/env_canada Project-URL: Documentation, https://github.com/michaeldavie/env_canada Project-URL: Repository, https://github.com/michaeldavie/env_canada Project-URL: Issues, https://github.com/michaeldavie/env_canada/issues Project-URL: Changelog, https://github.com/michaeldavie/env_canada/blob/main/CHANGELOG.md Classifier: Programming Language :: Python :: 3 Classifier: Operating System :: OS Independent Requires-Python: >=3.11 Description-Content-Type: text/markdown License-File: LICENSE Requires-Dist: aiohttp>=3.9.0 Requires-Dist: geopy>=2.3.0 Requires-Dist: lxml>=5.3.0 Requires-Dist: pandas>=2.2.3 Requires-Dist: Pillow>=10.0.1 Requires-Dist: python-dateutil>=2.9 Requires-Dist: voluptuous>=0.15.2 Dynamic: license-file # Environment Canada (env_canada) [![PyPI version](https://badge.fury.io/py/env-canada.svg)](https://badge.fury.io/py/env-canada) [![Snyk rating](https://snyk-widget.herokuapp.com/badge/pip/env-canada/badge.svg)](https://snyk.io/vuln/pip:env-canada@0.8.0?utm_source=badge) [![Python Lint and Test](../..//actions/workflows/python-app.yml/badge.svg)](../../actions/workflows/python-app.yml) This package provides access to various data sources published by [Environment and Climate Change Canada](https://www.canada.ca/en/environment-climate-change.html). > [!IMPORTANT] > If you're using the library in a Jupyter notebook, replace `asyncio.run(...)` with `await ...` in the examples below. For example: > > ```python > asyncio.run(ec_en.update()) > ``` > > becomes > > ```python > await ec_en.update() > ``` ## Weather Observations and Forecasts `ECWeather` provides current conditions and forecasts. It automatically determines which weather station to use based on latitude/longitude provided. It is also possible to specify a station code in multiple flexible formats: - **Full format**: `"AB/s0000123"` (province code and full station ID) - **Station ID only**: `"s0000123"` (station ID without province - province is resolved automatically) - **Numeric only**: `"123"` (just the station number - province is resolved automatically) Station codes are based on those listed in [this CSV file](https://dd.weather.gc.ca/today/citypage_weather/docs/site_list_towns_en.csv). For example: ```python import asyncio from env_canada import ECWeather # Using coordinates (automatic station selection) ec_coords = ECWeather(coordinates=(50, -100)) # Using station ID - multiple formats supported: ec_full = ECWeather(station_id="ON/s0000430", language="french") # Full format ec_station = ECWeather(station_id="s0000430") # Station ID only ec_numeric = ECWeather(station_id="430") # Numeric only asyncio.run(ec_coords.update()) # current conditions ec_coords.conditions # daily forecasts ec_coords.daily_forecasts # hourly forecasts ec_coords.hourly_forecasts # alerts (categorised dict with warnings, watches, advisories, statements, endings) ec_coords.alerts # raw WFS alert feature properties (includes text, area, confidence, impact, etc.) ec_coords.alert_features ``` > [!NOTE] > As of version 0.11.0, `ECWeather` automatically handles Environment Canada's new timestamped weather file URL structure (effective June 2025). The library dynamically discovers the most recent weather files, ensuring continued functionality during Environment Canada's infrastructure changes. ## Weather Alerts `ECAlerts` provides direct access to Environment Canada weather alerts via the GeoMet WFS `Current-Alerts` layer. It returns richer data than the alerts embedded in `ECWeather`, including full bilingual alert text, affected area names, risk colour, confidence, and impact. `ECWeather.update()` uses `ECAlerts` internally, so both `ECWeather.alerts` and `ECWeather.alert_features` are automatically populated. Use `ECAlerts` directly when you only need alerts (no weather conditions or forecasts): ```python import asyncio from env_canada import ECAlerts ec_alerts = ECAlerts(coordinates=(50, -100)) asyncio.run(ec_alerts.update()) # categorised alerts dict — same structure as ECWeather.alerts # keys: warnings, watches, advisories, statements, endings ec_alerts.alerts # list of raw WFS feature property dicts, one per alert polygon ec_alerts.alert_features ``` Each entry in `alerts[category]["value"]` is a dict with these keys: | Key | Description | | ------------------ | ----------------------------------------- | | `title` | Alert name (title-cased) | | `date` | Publication datetime (ISO 8601 UTC) | | `expiryTime` | Expiration datetime (ISO 8601 UTC) | | `alertColourLevel` | Risk colour (e.g. `"Yellow"`, `"Red"`) | | `text` | Full alert text | | `area` | Affected geographic area name | | `status` | Alert status (e.g. `"active"`, `"ended"`) | | `confidence` | Confidence level (e.g. `"Likely"`) | | `impact` | Impact level (e.g. `"High"`) | | `alert_code` | Short alert type code (e.g. `"WS"`) | ## Weather Radar `ECRadar` provides Environment Canada meteorological [radar imagery](https://weather.gc.ca/radar/index_e.html). ```python import asyncio from env_canada import ECRadar radar_coords = ECRadar(coordinates=(50, -100)) # Conditions Available animated_gif = asyncio.run(radar_coords.get_loop()) latest_png = asyncio.run(radar_coords.get_latest_frame()) ``` ## Weather Maps `ECMap` provides Environment Canada WMS weather map imagery with support for various meteorological layers. ```python import asyncio from env_canada import ECMap # Create a map with rain radar layer map_coords = ECMap(coordinates=(50, -100), layer="rain") # Get the latest image with the specified layer latest_png = asyncio.run(map_coords.get_latest_frame()) # Get an animated GIF with the specified layer animated_gif = asyncio.run(map_coords.get_loop()) # Customize the map appearance custom_map = ECMap( coordinates=(50, -100), layer="snow", width=1200, height=800, radius=300, layer_opacity=80, legend=True, timestamp=True, language="french", ) ``` Available layers include: - `rain`: Precipitation rain radar - `snow`: Precipitation snow radar - `precip_type`: Surface precipitation type Additional configuration options: - `width`/`height`: Image dimensions (default: 800x800) - `radius`: Map radius in km around coordinates (default: 200km) - `layer_opacity`: Layer transparency 0-100% (default: 65%) - `legend`: Show legend (default: True) - `timestamp`: Show timestamp (default: True) - `language`: "english" or "french" (default: "english") > **Note**: ECMap automatically discovers available legend styles from Environment Canada's WMS capabilities, ensuring compatibility with any future style changes. ## Air Quality Health Index (AQHI) `ECAirQuality` provides Environment Canada [air quality](https://weather.gc.ca/airquality/pages/index_e.html) data. ```python import asyncio from env_canada import ECAirQuality aqhi_coords = ECAirQuality(coordinates=(50, -100)) asyncio.run(aqhi_coords.update()) # Data available aqhi_coords.current aqhi_coords.forecasts ``` ## Water Level and Flow `ECHydro` provides Environment Canada [hydrometric](https://wateroffice.ec.gc.ca/mainmenu/real_time_data_index_e.html) data. ```python import asyncio from env_canada import ECHydro hydro_coords = ECHydro(coordinates=(50, -100)) asyncio.run(hydro_coords.update()) # Data available hydro_coords.measurements ``` ## Historical Weather Data `ECHistorical` provides historical daily weather data. The ECHistorical object is instantiated with a station ID, year, language, format (one of xml or csv) and granularity (hourly, daily data). Once updated asynchronously, historical weather data is contained with the `station_data` property. If `xml` is requested, `station_data` will appear in a dictionary form. If `csv` is requested, `station_data` will contain a CSV-readable buffer. For example: ```python import asyncio from env_canada import ECHistorical from env_canada.ec_historical import get_historical_stations # search for stations, response contains station_ids coordinates = [53.916944, -122.749444] # [lat, long] # coordinates: [lat, long] # radius: km # limit: response limit, value one of [10, 25, 50, 100] # The result contains station names and ID values. stations = asyncio.run(get_historical_stations(coordinates, radius=200, limit=100)) ec_en_xml = ECHistorical(station_id=31688, year=2020, language="english", format="xml") ec_fr_xml = ECHistorical(station_id=31688, year=2020, language="french", format="xml") ec_en_csv = ECHistorical(station_id=31688, year=2020, language="english", format="csv") ec_fr_csv = ECHistorical(station_id=31688, year=2020, language="french", format="csv") # timeframe argument can be passed to change the granularity # timeframe=1 hourly (need to create of for every month in that case, use ECHistoricalRange to handle it automatically) # timeframe=2 daily (default) ec_en_xml = ECHistorical( station_id=31688, year=2020, month=1, language="english", format="xml", timeframe=1 ) ec_en_csv = ECHistorical( station_id=31688, year=2020, month=1, language="english", format="csv", timeframe=1 ) asyncio.run(ec_en_xml.update()) asyncio.run(ec_en_csv.update()) # metadata describing the station ec_en_xml.metadata # historical weather data, in dictionary form ec_en_xml.station_data # csv-generated responses return csv-like station data import pandas as pd df = pd.read_csv(ec_en_csv.station_data) ``` `ECHistoricalRange` provides historical weather data within a specific range and handles the update by itself. The ECHistoricalRange object is instantiated with at least a station ID and a daterange. One could add language, and granularity (hourly, daily (default)). The data can then be used as pandas DataFrame, XML (requires pandas >=1.3.0) and csv For example : ```python import pandas as pd import asyncio from env_canada import ECHistoricalRange from env_canada.ec_historical import get_historical_stations from datetime import datetime coordinates = ["48.508333", "-68.467667"] stations = pd.DataFrame( asyncio.run( get_historical_stations( coordinates, start_year=2022, end_year=2022, radius=200, limit=100 ) ) ).T ec = ECHistoricalRange( station_id=int(stations.iloc[0, 2]), timeframe="daily", daterange=(datetime(2022, 7, 1, 12, 12), datetime(2022, 8, 1, 12, 12)), ) ec.get_data() # yield an XML formated str. # For more options, use ec.to_xml(*arg, **kwargs) with pandas options ec.xml # yield an CSV formated str. # For more options, use ec.to_csv(*arg, **kwargs) with pandas options ec.csv ``` In this example `ec.df` will be: | Date/Time | Longitude (x) | Latitude (y) | Station Name | Climate ID | Year | Month | Day | Data Quality | Max Temp (°C) | Max Temp Flag | Min Temp (°C) | Min Temp Flag | Mean Temp (°C) | Mean Temp Flag | Heat Deg Days (°C) | Heat Deg Days Flag | Cool Deg Days (°C) | Cool Deg Days Flag | Total Rain (mm) | Total Rain Flag | Total Snow (cm) | Total Snow Flag | Total Precip (mm) | Total Precip Flag | Snow on Grnd (cm) | Snow on Grnd Flag | Dir of Max Gust (10s deg) | Dir of Max Gust Flag | Spd of Max Gust (km/h) | Spd of Max Gust Flag | | | ---------- | ------------- | ------------ | --------------------- | ---------- | ---- | ----- | --- | ------------ | -------------- | ------------- | -------------- | ------------- | --------------- | -------------- | ------------------- | ------------------ | ------------------- | ------------------ | --------------- | --------------- | --------------- | --------------- | ----------------- | ----------------- | ----------------- | ----------------- | ------------------------- | -------------------- | ---------------------- | -------------------- | --- | | 2022-07-02 | -68,47 | 48,51 | POINTE-AU-PERE (INRS) | 7056068 | 2022 | 7 | 2 | | 22,8 | | 12,5 | | 17,7 | | 0,3 | | 0 | | | | | | 0 | | | | 26 | | 37 | | | | 2022-07-03 | -68,47 | 48,51 | POINTE-AU-PERE (INRS) | 7056068 | 2022 | 7 | 3 | | 21,7 | | 10,1 | | 15,9 | | 2,1 | | 0 | | | | | | 0,4 | | | | 28 | | 50 | | | | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | | 2022-07-31 | -68,47 | 48,51 | POINTE-AU-PERE (INRS) | 7056068 | 2022 | 7 | 31 | | 23,5 | | 14,1 | | 18,8 | | 0 | | 0,8 | | | | | | 0 | | | | 23 | | 31 | | | | 2022-08-01 | -68,47 | 48,51 | POINTE-AU-PERE (INRS) | 7056068 | 2022 | 8 | 1 | | 23 | | 15 | | 19 | | 0 | | 1 | | | | | | 0 | | | | 21 | | 35 | | | One should note that july 1st is excluded as the time provided contains specific hours, so it yields only data after or at exactly the time provided. To have all the july 1st data in that case, one can provide a datarange without time: `datetime(2022, 7, 7)` instead of `datetime(2022, 7, 1, 12, 12)` # License The code is available under terms of [MIT License](https://github.com/michaeldavie/env_canada/tree/main/LICENSE.md)