Skip to content

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]').