Skip to content

Observations, storm reports and radar

client.observations, client.storm_reports and client.radar. AsyncClient has the same methods, awaited; its iter_* methods are driven with async for.

Observations

Observations. Reach it as client.observations; needs the read:observations scope.

Times (start, end) are any accepted time; bounds are a Bounds, a mapping, or (north, south, east, west) that does not cross the antimeridian. Results are served as written by each source (to_dataframe(units=...) does not apply).

catalog

catalog() -> SourceCatalog

Every observation source your key can read, with the span of data it holds.

points

points(
    bounds: BoundsLike,
    *,
    source: str | None = None,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
    limit: int | None = None,
    cursor: str | None = None,
) -> ObservationPage

One page of point observations inside a box.

Parameters:

Name Type Description Default
bounds BoundsLike

The box.

required
source str | None

One source (see catalog()). Default: every source you can read.

None
start TimeLike | None

Observed at or after this time.

None
end TimeLike | None

Observed before this time.

None
limit int | None

Page size (the API's default 500, at most 2000).

None
cursor str | None

next_cursor from the previous page.

None

Raises:

Type Description
ValueError

The box crosses the antimeridian or leaves -180..180 (nothing is sent).

iter_points

iter_points(
    bounds: BoundsLike,
    *,
    source: str | None = None,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
    limit: int | None = None,
) -> Iterator[ObservationPage]

points() page after page, one request each, only as you advance it.

near

near(
    place: PlaceLike,
    radius_km: float,
    *,
    source: str | None = None,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
    limit: int | None = None,
) -> ObservationPage

Observations within radius_km of a place, nearest first (one page, no cursor).

Parameters:

Name Type Description Default
place PlaceLike

(lat, lon), a LatLon, or a ZIP code string.

required
radius_km float

Search radius, 0..500 km.

required
source str | None

One source. Default: every source you can read.

None
start TimeLike | None

Observed at or after this time.

None
end TimeLike | None

Observed before this time.

None
limit int | None

How many (the API's default 500, at most 2000).

None

Returns:

Type Description
ObservationPage

A page whose observations carry distance_m; next_cursor is always None.

stations

stations(
    *,
    source: str | None = None,
    bounds: BoundsLike | None = None,
    limit: int | None = None,
) -> StationList

Observing stations (not paged: limit clamps the list).

timeseries

timeseries(
    station_id: str,
    *,
    source: str | None = None,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
    limit: int | None = None,
    cursor: str | None = None,
) -> ObservationPage

One page of a station's observations over time.

Parameters:

Name Type Description Default
station_id str

The station's code, e.g. "KOMA".

required
source str | None

The source, when a code is used by more than one.

None
start TimeLike | None

Observed at or after this time.

None
end TimeLike | None

Observed before this time.

None
limit int | None

Page size (the API's default 500, at most 2000).

None
cursor str | None

next_cursor from the previous page.

None

iter_timeseries

iter_timeseries(
    station_id: str,
    *,
    source: str | None = None,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
    limit: int | None = None,
) -> Iterator[ObservationPage]

timeseries() page after page, one request each, only as you advance it.

areas

areas(
    source: str,
    *,
    bounds: BoundsLike | None = None,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
    limit: int | None = None,
    cursor: str | None = None,
) -> AreaPage

One page of a source's area observations (polygons).

Parameters:

Name Type Description Default
source str

The area source (kind polygons in catalog()).

required
bounds BoundsLike | None

Only areas touching this box.

None
start TimeLike | None

Areas in effect at or after this time.

None
end TimeLike | None

Areas in effect before this time.

None
limit int | None

Page size (the API's default 100, at most 1000).

None
cursor str | None

next_cursor from the previous page.

None

iter_areas

iter_areas(
    source: str,
    *,
    bounds: BoundsLike | None = None,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
    limit: int | None = None,
) -> Iterator[AreaPage]

areas() page after page, one request each, only as you advance it.

StormReports

Storm reports. Reach it as client.storm_reports; needs read:observations.

A report is an Observation: its properties hold what the source wrote (report_type, magnitude, county …), served as written.

list

list(
    bounds: BoundsLike,
    *,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
    report_type: str | None = None,
    state: str | None = None,
    source: str | None = None,
    limit: int | None = None,
    cursor: str | None = None,
) -> ObservationPage

One page of storm reports inside a box.

Parameters:

Name Type Description Default
bounds BoundsLike

The box (it may not cross the antimeridian).

required
start TimeLike | None

Reported at or after this time.

None
end TimeLike | None

Reported before this time.

None
report_type str | None

One type (see catalog().report_types), e.g. "hail".

None
state str | None

A two-letter state code.

None
source str | None

One source. Default: every storm report source.

None
limit int | None

Page size (the API's default 500, at most 2000).

None
cursor str | None

next_cursor from the previous page.

None

iter_list

iter_list(
    bounds: BoundsLike,
    *,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
    report_type: str | None = None,
    state: str | None = None,
    source: str | None = None,
    limit: int | None = None,
) -> Iterator[ObservationPage]

list() page after page, one request each, only as you advance it.

by_county

by_county(
    bounds: BoundsLike,
    *,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
    report_type: str | None = None,
    source: str | None = None,
) -> CountyRollups

Report counts per county inside a box, with a count per year.

Parameters:

Name Type Description Default
bounds BoundsLike

The box (it may not cross the antimeridian).

required
start TimeLike | None

Reported at or after this time. Default: 2 years before end.

None
end TimeLike | None

Reported before this time. Default: now.

None
report_type str | None

One type, e.g. "hail".

None
source str | None

One source. Default: every storm report source.

None

Raises:

Type Description
InvalidRequestError

The span exceeds the API's 5-year cap.

get

get(report_id: str) -> Observation

One report by its id.

Raises:

Type Description
ObservationNotFoundError

No report has that id.

catalog

catalog() -> StormReportCatalog

The storm report sources and the report types they carry.

Radar

MRMS radar. Reach it as client.radar.

point

point(
    place: PlaceLike,
    parameters: str | Iterable[str],
    *,
    start: TimeLike | None = None,
    end: TimeLike | None = None,
) -> RadarSeries

Every raw MRMS frame (2-minute cadence) at one place within [start, end).

Parameters:

Name Type Description Default
place PlaceLike

(lat, lon), a LatLon, or a ZIP code string.

required
parameters str | Iterable[str]

One MRMS parameter name or several (see client.forecast.parameters("mrms")).

required
start TimeLike | None

Window start. Default: one hour before end.

None
end TimeLike | None

Window end. Default: now, or one hour after start when only start is given. The API caps the window at 24 hours.

None

Returns:

Type Description
RadarSeries

The frames; to_dataframe() is indexed by UTC valid_time. A missed sweep

RadarSeries

is one frame fewer, never an error.