Quick Example

This page walks through a complete session: find what data exists, download a slice of it, and check what you got. Every output shown here is real.

1. Connect

from TeamOverbyeWeather import WeatherClient

client = WeatherClient()

2. See what is available

Three sources, each with sub-types:

for source in client.sources():
    print(source, "->", client.types(source))

era5 -> ['historical', 'na', 'north_america', 'texas', 'tx']
hrrr -> ['archive', 'current', 'forecast', 'history', 'hourly_archive', 'hourly_current']
noaa -> ['archive', 'forecast', 'recent']

List the dates each one covers, newest first:

print(client.list("noaa"))                      # forecast cycles
print(client.list("hrrr", "hourly_current"))    # daily, hourly steps
print(client.list("hrrr", "hourly_archive"))    # monthly, hourly steps
print(client.list("era5"))                      # quarters

['2026-07-22T12Z', '2026-07-22T06Z', '2026-07-22T00Z', ...]
['2026-07-21', '2026-07-20', '2026-07-19', ...]
['2026-06', '2014-12', '2014-11', '2014-10', ...]
['2026-Q3', '2026-Q2', '2026-Q1', ...]

Date formats differ by source — quarters, months, days, or forecast cycles. Use whatever list() gives you and you cannot get it wrong.

3. Download a whole file

paths = client.download("noaa", dates="2026-07-22T12Z", dest="./data")
print(paths[0])

data/Forecast_NorthAmerica_Run2026-07-22T12Z.pww

4. Crop to a region

Pass region with a state postal code:

path = client.download("noaa", dates="2026-07-22T12Z",
                       region="TX", dest="./data")[0]

data/noaa_forecast_recent_2026-07-22T12Z_TX.pww

The grid shrinks from North America to a 44×53 box around Texas.

5. Crop in time as well

path = client.download(
    "noaa",
    dates="2026-07-22T12Z",
    region="TX",
    time_start="2026-07-22T12:00",
    time_end="2026-07-22T18:00",
    dest="./data",
)[0]

data/noaa_forecast_recent_2026-07-22T12Z_TX_T20260722H1200to20260722H1800.pww

The filename records both crops. What actually changed:

Request

Time steps

Grid

Size

Full file

385

North America

120 MB

region="TX"

385

44 × 53

7.3 MB

region="TX" + 6-hour window

7

44 × 53

240 KB

Both crops happen on the server, so the small number is what crosses the network — not the large one.

6. Check what you got

from TeamOverbyeWeather import pww_io

header, stations, arr = pww_io.read_pww(open(path, "rb").read())
print("time steps:", arr.shape[0])
print("grid:", arr.shape[2], "x", arr.shape[3])
print("step seconds:", header["sample_sec"])

time steps: 7
grid: 44 x 53
step seconds: 3600

Putting it together

A realistic request — every 15-minute HRRR step for one day over ERCOT, business hours only:

from TeamOverbyeWeather import WeatherClient

client = WeatherClient()

paths = client.download(
    "hrrr",
    type="current",                  # 15-minute steps, current year
    dates=client.list("hrrr", "current")[:3],   # three most recent days
    iso="ERCOT",
    time_start="2026-07-21T08:00",
    time_end="2026-07-21T20:00",
    dest="./data",
)

for p in paths:
    print(p.name)

One file per day, each already cropped to ERCOT and to the hours you asked for.

Where to go next