Browsing the Catalog

Before downloading anything you need to know two things: which source and type you want, and which date keys exist for it.

Sources and types

Three sources, each with sub-types that map to a different collection of files:

client.sources()          # ['era5', 'hrrr', 'noaa']
client.types("hrrr")      # ['archive', 'current', 'forecast', ...]

ERA5 — reanalysis

`type`	Coverage	Date key
`historical` (default)	North America	`YYYY-Qn`
`texas`	Texas only	`YYYY-Qn`

Aliases: na / north_america for the default, tx for Texas.

HRRR — high-resolution CONUS

`type`	Steps	Period per file	Date key
`current`	15-minute	one day	`YYYY-MM-DD`
`archive`	15-minute	one month	`YYYY-MM`
`hourly_current`	hourly	one day	`YYYY-MM-DD`
`hourly_archive`	hourly	one month	`YYYY-MM`
`forecast` (default)	hourly, 48 h out	one cycle	`YYYY-MM-DDTHHZ`

“Current” means the current calendar year, stored as individual days. “Archive” means previous years, bundled by month. The hourly archives reach back furthest — as of writing, to 2014.

NOAA / GFS — forecasts

`type`	Source folder	Date key
`recent` (default)	main folder	`YYYY-MM-DDTHHZ`
`archive`	archive folder	`YYYY-MM-DDTHHZ`

Extreme — curated historical events

`type`	Coverage	Key
`events` (default)	62 events, 1899–2023, by ISO zone	`YYYY-MM-DD_Title_Zone`

Named historical extremes — the three hottest and three coldest per ISO zone, plus notable scenarios — each with an animation. These are browsed rather than sliced by date; see Extreme Temperature Events.

Warning

recent and archive are separate folders, not a date split. A cycle in one will not appear in the other, and “recent” does not necessarily mean “chronologically newer”. Always list the type you intend to download from.

Listing dates

list() returns date keys newest first:

client.list("hrrr", "hourly_archive")

['2026-06', '2014-12', '2014-11', '2014-10', '2014-09', ...]

Feed those straight back into download(), so you never have to hand-format a date:

recent_days = client.list("hrrr", "current")[:5]
client.download("hrrr", type="current", dates=recent_days, region="TX", dest="./data")

Checking a specific date exists

"2026-07-21" in client.list("hrrr", "current")

Asking for a missing date raises WeatherAPIError with HTTP 404 rather than writing an empty file.

The raw catalog

catalog() returns everything at once, keyed by the internal API source name:

catalog = client.catalog()
print(catalog.keys())

dict_keys(['hrrr_forecast', 'hrrr_history', 'hrrr_history_current',
           'hrrr_history_archive', 'hrrr_history_hourly_current',
           'hrrr_history_hourly_archive', 'noaa_forecast',
           'noaa_forecast_recent', 'noaa_forecast_archive',
           'era5_na', 'era5_tx'])

Each entry holds a list of date keys plus the underlying file ids. You can pass these internal names directly to download() if you prefer them to the source/type pair:

client.download("hrrr_history_hourly_archive", dates="2014-11", region="TX")

Caching

The server caches its catalog for 30 minutes, and the client caches the response for the life of the WeatherClient object. If data was just uploaded and you do not see it:

client.catalog(refresh=True)

That forces a server-side rebuild and clears the local cache.