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 |
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
|
|
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
|
|
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 |
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. |
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
|
|
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 ( |
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
|
|
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 |
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
|
|
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 |
None
|
end
|
TimeLike | None
|
Reported before this time. Default: now. |
None
|
report_type
|
str | None
|
One type, e.g. |
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
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
|
|
required |
parameters
|
str | Iterable[str]
|
One MRMS parameter name or several (see
|
required |
start
|
TimeLike | None
|
Window start. Default: one hour before |
None
|
end
|
TimeLike | None
|
Window end. Default: now, or one hour after |
None
|
Returns:
| Type | Description |
|---|---|
RadarSeries
|
The frames; |
RadarSeries
|
is one frame fewer, never an error. |