Environment Canada (env_canada)

This package provides access to various data sources published by Environment and Climate Change Canada.

[!IMPORTANT]
If you're using the library in a Jupyter notebook, replace asyncio.run(...) with await ... in the examples below. For example:

asyncio.run(ec_en.update())

becomes

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. For example:

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):

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:

Weather Radar

ECRadar provides Environment Canada meteorological radar imagery.

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())

# Use the 8-colour radar scale instead of the default 14-colour one
radar_coords_8 = ECRadar(coordinates=(50, -100), colors=8)

Weather Maps

ECMap provides Environment Canada WMS weather map imagery with support for various meteorological layers.

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")
• fps: Frame rate of the animated GIF loop (default: 5)
• loop_minutes: How far back the animated GIF loop goes, in minutes (default: 0, meaning the full available range)
• colors: Number of colours in the rain/snow radar scale, 8 or 14 (default: 14)
• interpolation: Smooth the WMS-rendered radar layer instead of leaving it pixelated (default: False)
• webp: Request the radar layer from Environment Canada's WMS as WebP instead of PNG, and return get_latest_frame()/get_loop() output as WebP instead of PNG/GIF. Reduces bandwidth at the cost of higher latency per frame (default: False)
• future_minutes: Extend get_loop() past "now" using Environment Canada's radar extrapolation (nowcast) layer, in minutes. Only has an effect for rain/snow (precip_type has no extrapolation layer, so it's silently ignored); frames are capped at whatever the extrapolation layer actually has available, which is normally on the order of an hour. Uses the same styles/colours as the observed layer. get_latest_frame() is unaffected and always returns the latest real observation (default: 0)

Note: Legends are rendered by the library itself, in the style of Environment Canada's weather map, rather than fetched from the WMS server. A change to the server's styles therefore needs a matching update to ec_legend.py.

Precipitation Forecast Series

ECPrecipForecast assembles the numeric precipitation series needed to draw a
precipitation histogram of the kind weather apps show. It gathers and structures
the data only; rendering is left to the caller.

Two independent tracks are produced:

• nowcast — precipitation rate at 6-minute resolution, from observed radar for
  the recent past and from Environment Canada's radar extrapolation (nowcast)
  layers for roughly the next hour.
• hourly — hourly precipitation amount, probability and type for up to the next
  48 hours, from the HRDPS model and its "Weather Elements on Grid" (WEonG)
  diagnostic suite.

import asyncio

from env_canada import ECPrecipForecast

precip = ECPrecipForecast(coordinates=(45.42, -75.70))
asyncio.run(precip.update())

# 6-minute rate series
for entry in precip.nowcast:
    print(entry)
# {'timestamp': datetime.datetime(2025, 2, 13, 16, 54, tzinfo=tzutc()),
#  'rate': 1.2391, 'unit': 'mm/h', 'label': '1.0 - 2.0 (mm/h)',
#  'precip_type': 'rain', 'forecast': False}

# hourly series
for entry in precip.hourly:
    print(entry)
# {'timestamp': datetime.datetime(2025, 2, 13, 17, 0, tzinfo=tzutc()),
#  'amount': 1.726, 'probability': 57, 'conditional_amount': 0.909,
#  'expected_amount': 0.518, 'precip_type': 'Rain', 'label': '0.5 - 1 mm'}

Configuration options:

• precip_type: "auto", "rain" or "snow" (default: "auto"). "auto" reads
  Environment Canada's radar surface precipitation type at the most recent
  observation, falling back to the season when radar detects nothing
• past_minutes: How far back the nowcast series reaches, 0-180 (default: 60)
• future_minutes: How far ahead the nowcast series reaches, 0-120 (default: 72).
  Capped at whatever the extrapolation layer actually has, normally around 72 minutes
• hourly_hours: Length of the hourly series, 0-48 (default: 24). 0 disables
  the hourly track entirely
• language: "english" or "french" (default: "english"), used for the attribution

nowcast entries carry:

• rate: The value exactly as served — mm/h for rain, cm/h for snow, per unit
• label: Environment Canada's own classification of that value, e.g.
  "1.0 - 2.0 (mm/h)" or "Undetected". The extrapolation layer reports a small
  non-zero floor below its detection threshold, which this label identifies
• forecast: False for observed radar, True for extrapolation

hourly entries describe the hour ending at timestamp, matching how the model
reports accumulation:

• amount: Precipitation for that hour in mm. The model publishes accumulation
  cumulatively from the start of its run, so this is a difference between
  successive steps, with every request pinned to a single model run
• probability: Probability of precipitation, 0-100%
• conditional_amount: Amount expected in mm if precipitation occurs
• expected_amount: probability / 100 * conditional_amount
• precip_type: Dominant precipitation type, e.g. "Rain", "Snow", "None"

metadata carries the attribution, the timestamp of the latest radar observation,
and the model run each forecast track is pinned to.

Note: Environment Canada's WMS server answers one point query per layer per
timestep, so a cold update() at the defaults issues roughly 120 requests
(taking a few seconds). Responses are cached — 5 minutes for radar, 3 hours for
the model, which runs every 6 hours — so subsequent updates only fetch newly
published radar frames. Pick a polling interval accordingly; every 5-10 minutes
is ample.

Air Quality Health Index (AQHI)

ECAirQuality provides Environment Canada air quality data.

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 data.

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:

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)

In the dictionary form, daily records are keyed by date ("2021-01-01") and hourly ones by date and time ("2021-05-01 13:00"). A station ID the service doesn't know raises env_canada.ec_exc.UnknownStationId from update().

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. The daterange is the last year or so up to today unless given, and may be given in either order.
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 :

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()  # from async code, use `await ec.update()` instead

# 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:

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). A date given as the end of the range covers that whole day.

License

The code is available under terms of MIT License