Source Clients

Each source has a namespace on the client — client.era5, client.hrrr, client.noaa. These predate the unified download() method and are kept so existing scripts keep working.

Note

New code should use client.download(). These wrappers just translate their arguments and call it. Everything they can do, it can do — usually with less ceremony.

All of them accept the same keyword arguments as download(), so time_start, time_end, show_progress, and local_crop work here too:

client.hrrr.download_region(
    days=["2026-07-21"],
    type="hourly_current",
    region_ids=["TX"],
    region_layer="states",
    time_start="2026-07-21T06:00",
    dest="./data",
)

Argument mapping

The wrappers use the older region_ids + region_layer pair; download() uses region and iso:

Wrapper	Unified equivalent
region_ids=["TX"], region_layer="states"	region=["TX"]
region_ids=["ERCOT"], region_layer="iso"	iso=["ERCOT"]
bbox=(...)	bbox=(...)

ERA5

class TeamOverbyeWeather.sources.era5.ERA5Client(client)

Bases: object

Access ERA5 quarterly reanalysis datasets via WeatherClient.era5.

Parameters:

client (WeatherClient)

list_quarters(region='north_america')

List available quarters like ["2026-Q3", "2026-Q2"], newest first.

Parameters:

region (str) – "north_america" or "texas".

Return type:

list[str]

download(quarters, region='north_america', dest='.', **kwargs)

Download ERA5 quarterly .pww files, one per quarter.

Parameters:

• quarters (list[str]) – Quarter strings like ["2026-Q1"].

• region (str) – "north_america" or "texas".

• dest (str) – Destination directory.

• **kwargs – Passed to WeatherClient.download() (time_start, time_end, show_progress, …).

Return type:

list[Path]

download_region(quarters, *, region='north_america', region_ids=None, region_layer=None, bbox=None, dest='.', **kwargs)

Download ERA5 quarters cropped to a region or bbox.

Parameters:

• quarters (list[str]) – Quarter strings.

• region (str) – Which ERA5 dataset — "north_america" or "texas".

• region_ids (list[str] | None) – State postal codes or ISO zone ids to crop to.

• region_layer (str | None) – "states" or "iso" (required with region_ids).

• bbox (tuple | None) – (lat_max, lon_min, lat_min, lon_max).

• dest (str) – Destination directory.

• **kwargs – Passed to WeatherClient.download().

Return type:

list[Path]

HRRR

class TeamOverbyeWeather.sources.hrrr.HRRRClient(client)

Bases: object

Access HRRR historical and forecast datasets via WeatherClient.hrrr.

HRRR history comes in four flavours; pass type to pick one:

type	date keys	contents
current	YYYY-MM-DD	this year, 15-minute steps
archive	YYYY-MM	past years, 15-minute steps
hourly_current	YYYY-MM-DD	this year, hourly steps
hourly_archive	YYYY-MM	past years, hourly steps

Parameters:

client (WeatherClient)

list_months(type='archive')

List available YYYY-MM archive months, newest first.

Parameters:

type (str) – "archive" (15-min) or "hourly_archive".

Return type:

list[str]

list_days(type='current')

List available YYYY-MM-DD days, newest first.

Parameters:

type (str) – "current" (15-min) or "hourly_current".

Return type:

list[str]

list_forecast_cycles()

List available forecast cycles like ["2026-07-22T12Z"], newest first.

Return type:

list[str]

download_history(months=None, dest='.', *, days=None, type=None, **kwargs)

Download HRRR history files, one per date key.

Parameters:

• months (list[str] | None) – YYYY-MM keys (archive).

• dest (str) – Destination directory.

• days (list[str] | None) – YYYY-MM-DD keys (current year) — use instead of months.

• type (str | None) – Explicit sub-type; inferred from months/days when omitted.

• **kwargs – Passed to WeatherClient.download().

Raises:

ValueError – If both or neither of months and days are given.

Return type:

list[Path]

download_forecast(cycles, dest='.', **kwargs)

Download HRRR forecast files, one ZIP per cycle.

Parameters:

• cycles (list[str])

• dest (str)

Return type:

list[Path]

download_region(*, months=None, days=None, cycles=None, type=None, region_ids=None, region_layer=None, bbox=None, dest='.', **kwargs)

Download HRRR data cropped to a region or bbox.

CONUS-scale archive requests are cropped locally, since the server refuses them to protect its memory budget.

Parameters:

• months (list[str] | None) – YYYY-MM archive keys.

• days (list[str] | None) – YYYY-MM-DD current-year keys.

• cycles (list[str] | None) – Forecast cycle keys.

• type (str | None) – Explicit sub-type; inferred from the date argument when omitted.

• region_ids (list[str] | None) – State postal codes or ISO zone ids.

• region_layer (str | None) – "states" or "iso".

• bbox (tuple | None) – (lat_max, lon_min, lat_min, lon_max).

• dest (str) – Destination directory.

• **kwargs – Passed to WeatherClient.download() (time_start, …).

Raises:

ValueError – If not exactly one of months/days/cycles is given.

Return type:

list[Path]

download_latest_forecast(dest='.', **kwargs)

Download the most recent HRRR forecast cycle.

Raises:

ValueError – If no forecast cycles are available.

Parameters:

dest (str)

Return type:

Path

NOAA / GFS

class TeamOverbyeWeather.sources.noaa.NOAAClient(client)

Bases: object

Access NOAA/GFS forecast datasets via WeatherClient.noaa.

recent and archive are separate Drive folders, not a date split — a cycle in one will not appear in the other.

Parameters:

client (WeatherClient)

list_forecast_cycles(type='recent')

List available cycles, newest first.

Parameters:

type (str) – "recent" or "archive".

Return type:

list[str]

download_forecast(cycles, dest='.', *, type='recent', **kwargs)

Download NOAA/GFS forecast .pww files, one per cycle.

Parameters:

• cycles (list[str]) – Cycle keys like ["2026-07-22T12Z"].

• dest (str) – Destination directory.

• type (str) – "recent" or "archive".

• **kwargs – Passed to WeatherClient.download().

Return type:

list[Path]

download_region(cycles, *, type='recent', region_ids=None, region_layer=None, bbox=None, dest='.', **kwargs)

Download NOAA/GFS cycles cropped to a region or bbox.

Parameters:

• cycles (list[str]) – Cycle keys.

• type (str) – "recent" or "archive".

• region_ids (list[str] | None) – State postal codes or ISO zone ids.

• region_layer (str | None) – "states" or "iso".

• bbox (tuple | None) – (lat_max, lon_min, lat_min, lon_max).

• dest (str) – Destination directory.

• **kwargs – Passed to WeatherClient.download() (time_start, …).

Return type:

list[Path]

download_latest(dest='.', **kwargs)

Download the most recent NOAA/GFS forecast cycle.

Raises:

ValueError – If no forecast cycles are available.

Parameters:

dest (str)

Return type:

Path

Extreme events

Unlike the others, this namespace is not a legacy wrapper — event browsing, animations and coverage maps have no equivalent on download(). See Extreme Temperature Events.

class TeamOverbyeWeather.sources.extreme.ExtremeClient(client)

Bases: object

Access curated extreme-weather events via WeatherClient.extreme.

62 historical events spanning 1899-2023, selected per ISO zone as the three hottest and three coldest on record, plus additional notable scenarios such as ERCOT’s February 2011 rolling outages. Each event has weather data and a matching animation.

Events are identified by a key that carries the date, title and zone:

2021-02-14_Winter_Storm_Uri_Texas

Parameters:

client (WeatherClient)

zones()

List the ISO zones that have events, e.g. ["CAISO", ..., "Texas"].

Return type:

list[str]

events(zone=None)

List events, newest first.

Parameters:

zone (str | None) – Restrict to one ISO zone; omit for every zone.

Returns:

Dicts with key, date, title, zone and has_video.

Raises:

ValueError – If zone is not a known zone.

Return type:

list[dict]

find(text)

Search events by title, case-insensitively.

client.extreme.find("uri") finds Winter Storm Uri.

Parameters:

text (str)

Return type:

list[dict]

download(keys, *, region_ids=None, region_layer=None, bbox=None, dest='.', **kwargs)

Download event weather data as .pww, one file per event.

Parameters:

• keys – One event key or a list of them.

• region_ids (list[str] | None) – State postal codes or ISO zone ids to crop to.

• region_layer (str | None) – "states" or "iso" (required with region_ids).

• bbox (tuple | None) – (lat_max, lon_min, lat_min, lon_max).

• dest (str) – Destination directory.

• **kwargs – Passed to WeatherClient.download() (time_start, …).

Return type:

list[Path]

video(key, dest='.', show_progress=None)

Download an event’s animation as .mp4.

Raises:

WeatherAPIError – If the event has no animation.

Parameters:

• key (str)

• dest (str)

• show_progress (bool | None)

Return type:

Path

coverage(zone, dest='.', show_progress=None)

Download a zone’s coverage map as .png.

Parameters:

• zone (str)

• dest (str)

• show_progress (bool | None)

Return type:

Path