Observations¶
Everything observed lives on client.observations: point observations (METAR, mesonets,
your own sources), the stations behind them, and area observations (polygons).
Every call needs the read:observations scope on your key. Without it the API answers
403 and the client raises ForbiddenError; ask your organisation's admin for the scope. A
source you cannot read, or that does not exist, raises ObservationSourceNotFoundError.
from stormlore import Client
client = Client()
client.observations.catalog().to_dataframe() # the sources your key can read
Near a place¶
page = client.observations.near((41.26, -95.94), 25) # within 25 km, nearest first
page.to_dataframe()[["station_id", "observed_at", "distance_m"]]
The place is (lat, lon), a LatLon or a ZIP code, as for forecasts.
near returns one page and never a cursor: narrow it with limit=, start=, end=
or source=.
Inside a box: pages¶
box = (43, 40, -95, -100) # north, south, east, west
page = client.observations.points(box, source="madis_metar", start="2026-11-13T00Z")
page.to_dataframe()
page.next_cursor # None on the last page
page.has_more
A listing is paged. One call is one request for one page (500 features by default, at
most 2000 with limit=); nothing more is fetched unless you ask. For the next page, make
the same call with cursor=page.next_cursor:
nxt = client.observations.points(box, source="madis_metar", cursor=page.next_cursor)
Or let an iterator do it: iter_points, iter_timeseries and iter_areas take the same
arguments without cursor and yield pages, one request each, only as you advance them.
for page in client.observations.iter_points(box, source="madis_metar"):
handle(page.to_dataframe())
# AsyncClient
async for page in client.observations.iter_points(box, source="madis_metar"):
...
If a page fails part-way, the error comes from that page; the pages you already have stay
valid, and you can carry on later from the last next_cursor with points(..., cursor=...).
A box may not cross the antimeridian (east less than west) and its longitudes must lie in
-180..180: the observation routes refuse both, so the client raises ValueError before
sending. Split a box that crosses the dateline in two.
One station over time¶
client.observations.stations(source="madis_metar", bounds=box).to_dataframe()
client.observations.timeseries("KOMA", start="2026-11-13T00Z").to_dataframe()
stations is not paged (the list is clamped by limit=). timeseries is, like points.
Areas¶
client.observations.areas("nws_wwa", bounds=box).to_dataframe()
source is required (a source whose kind is polygons in the catalog). Each area keeps
its GeoJSON geometry as a mapping, also the last column of the frame; pass it to shapely
or geopandas if you need shapes.
The frame¶
ObservationPage.to_dataframe() gives one row per observation with the fixed columns
id, observed_at, lat, lon, source, station_id, station_name, station_state, station_country, distance_m
then one column per key of the observation's values, attributes and the rest of its
properties (whatever the source wrote: a METAR's temperature, a RAOB's levels). Only the
top level is spread out: a nested value stays an object in its cell. A key that would take
a name already in use is named values.<key>, attributes.<key> or properties.<key>;
the fixed columns always win. An empty page gives an empty frame with the fixed columns.
Units¶
Observations are served as written by their source. The SDK does not convert them:
to_dataframe(units="imperial") raises ValueError on any observation result, and the
client's units= default does not touch them. Where a source declares a value's unit
(your own sources do), frame.attrs["units"] names it.
Draw it¶
page.plot() # a map; one station over time draws a line per station
Every chart, drawn: charts and maps (pip install 'stormlore[viz]').