WeatherClient

The main entry point. One object gives you catalog browsing, region lookup, and downloads.

from TeamOverbyeWeather import WeatherClient
client = WeatherClient()
class TeamOverbyeWeather.WeatherClient(base_url='https://weather-data-gui.up.railway.app', show_progress=True)[source]

Bases: object

Client for the Team Overbye Weather Data API.

One call does download, region crop, and time crop:

c = WeatherClient()
c.download("hrrr", type="hourly_current", dates="2026-07-21",
           region="TX", time_start="2026-07-21T06:00",
           time_end="2026-07-21T18:00", dest="./data")
Parameters:

  • base_url (str) – Base URL of the weather data API.

  • show_progress (bool) – Default for per-call progress bars.

status()[source]

Return pipeline health for each source (ok/error/unknown).

Return type:

dict

catalog(refresh=False)[source]

Return the full catalog of available files.

Parameters:

refresh (bool) – Force the server to rebuild its 30-minute cache, and drop this client’s in-process cache.

Return type:

dict

sources()[source]

List the source names accepted by download().

Return type:

list[str]

types(source)[source]

List the sub-types available for source.

Parameters:

source (str)

Return type:

list[str]

list(source, type=None)[source]

List available date keys for a source, newest first.

Parameters:

  • source (str) – "era5", "hrrr", "noaa", or a full API key.

  • type (str | None) – Sub-type — see types().

Returns:

YYYY-Qn (ERA5), YYYY-MM (monthly archives), YYYY-MM-DD (daily), or YYYY-MM-DDTHHZ (forecast cycles).

Return type:

Date keys in the format that source uses

regions()[source]

Return the region catalog: {"states": [...], "iso": [...]}.

Each entry has id, name, and bbox.

Return type:

dict

region_ids(layer='states')[source]

List valid region ids for "states" or "iso".

Parameters:

layer (str)

Return type:

list[str]

download(source, dates, type=None, *, region=None, iso=None, bbox=None, time_start=None, time_end=None, dest='.', show_progress=None, local_crop=True, keep_raw=False)[source]

Download data, optionally cropped to a region and/or time window.

One file is written per date key, so results are ready to open directly rather than bundled into a ZIP.

Cropping happens server-side, which keeps the transfer small (a Texas 6-hour NOAA crop is ~240 KB instead of hundreds of MB). When the server refuses a CONUS-scale HRRR archive request (HTTP 413), the SDK falls back to downloading the full file and cropping locally, unless local_crop is False.

Parameters:

  • source (str) – "era5", "hrrr", "noaa", or a full API key.

  • dates – One date key or a list of them — see list().

  • type (str | None) – Sub-type — see types().

  • region – State postal code(s), e.g. "TX" or ["TX", "OK"]. Multiple states crop to their union bounding box.

  • iso – ISO zone id(s) — see regions()["iso"].

  • bbox (tuple | None) – (lat_max, lon_min, lat_min, lon_max). Note the ordering: north, west, south, east.

  • time_start – Start of the time window (ISO string or datetime). May be given without time_end to run to the end of the file.

  • time_end – End of the time window, inclusive.

  • dest (str | Path) – Destination directory (created if absent).

  • show_progress (bool | None) – Show progress bars; defaults to the client setting.

  • local_crop (bool) – Fall back to a local crop when the server returns 413.

  • keep_raw (bool) – Keep the uncropped download after a local crop.

Returns:

Paths to the saved files, one per date key.

Raises:
Return type:

list[Path]