Forecasts¶
Everything forecast lives on client.forecast.
from stormlore import Client
client = Client()
models = client.forecast.models() # what your key can use
models.to_dataframe()
client.forecast.parameters("gfs").names
A place¶
A place is any of:
(lat, lon)— latitude first, in degrees. A latitude outside ±90 raisesValueErrorbefore any request (the usual sign of a swapped pair).- a
LatLon(lat=..., lon=...); - a 5-digit US ZIP code string,
"68102". The client looks up a point inside the ZIP once and remembers it for the life of the client. This needs theread:observationsscope on your key; without it you getZipLookupForbiddenError— pass(lat, lon)instead. A ZIP that does not exist raisesUnknownZipError.
client.forecast.point("gfs", (41.26, -95.94), "temperature_2m")
client.forecast.point("gfs", "68102", "temperature_2m")
A time¶
Every query takes at=, which is any of:
- a timezone-aware
datetime(converted to UTC); - a naive
datetime, taken as UTC; - a
numpy.datetime64orpandas.Timestamp; - an ISO 8601 string,
"2026-11-13T18:00Z".
With no at, the client picks the forecast valid nearest to now from the newest run:
it reads the model's timeline (one extra request per model per minute, cached) and
chooses the step closest to the current time. For an analysis model such as mrms,
which has observed frames rather than forecast steps, it picks the newest frame.
from datetime import datetime, timezone
client.forecast.point("gfs", (41.26, -95.94), "temperature_2m") # nearest now
client.forecast.point("gfs", (41.26, -95.94), "temperature_2m", at="2026-11-14T00Z")
client.forecast.point("gfs", (41.26, -95.94), "temperature_2m",
at=datetime(2026, 11, 14, tzinfo=timezone.utc))
run= asks for an older run by its start time (see client.forecast.runs("gfs")). With
run= and no at, the time is the one nearest now among that run's steps. An unknown
run raises RunNotFoundError before the query is sent.
Point, timeseries, route, area¶
point = client.forecast.point("hrrr", (41.26, -95.94), ["temperature_2m", "dewpoint_2m"])
point["temperature_2m"].value # 271.4
point.to_dataframe() # one row, indexed by valid_time
series = client.forecast.timeseries("gfs", (41.26, -95.94), "temperature_2m")
series.to_dataframe() # every step of the run, UTC DatetimeIndex
series = client.forecast.timeseries(
"gfs", (41.26, -95.94), "temperature_2m",
at=pd.date_range("2026-11-13T18Z", periods=8, freq="3h"),
)
A route is a list of waypoints. Each waypoint is one of:
- a place alone, with no time:
(lat, lon), aLatLon,{"lat": ..., "lon": ...}or a ZIP code string; (lat, lon, at);(place, at), where the place is(lat, lon), aLatLonor a ZIP code;- a
Waypoint(place=..., at=...).
Waypoints without a time share one: the time nearest now. When some waypoints carry a time of yours, an out-of-range answer is raised as it is, never retried.
route = client.forecast.route(
"gfs",
[(41.26, -95.94, "2026-11-13T18Z"), (40.81, -96.70, "2026-11-13T19Z"), "68508"],
["temperature_2m", "wind_speed_gust_surface"],
)
route.to_dataframe() # one row per waypoint: lat, lon, valid_time, values
An area is a bounding box: (north, south, east, west), a mapping with those keys,
or a Bounds.
area = client.forecast.area("hrrr", (43.0, 40.0, -95.3, -104.1), "temperature_2m")
The API caps the grid at 256 × 256. By default the longer side is 256 and the other
follows the box's shape (in degrees); pass width= or height= (each at most 256) to
choose. A size over 256 raises ValueError before any request.
The grid is a regular latitude/longitude grid for every model: row 0 is the north edge, column 0 the west edge, and both edges are included. Missing cells are NaN.
Wind¶
wind() asks for the u and v components and returns speed and the direction the wind
blows from (0 = north, 90 = east):
wind = client.forecast.wind("gfs", (41.26, -95.94))
wind.speed.value, wind.direction.value
Results¶
Results are frozen (read-only) models. Every one has to_dataframe():
| Result | to_dataframe() |
|---|---|
| point | one row, indexed by UTC valid_time, one column per parameter |
| timeseries | UTC DatetimeIndex named valid_time, one column per parameter |
| route | one row per waypoint: lat, lon, valid_time, one column per parameter |
| area | long form: one row per cell, lat, lon, one column per parameter |
| listings | one row per model, parameter, run, step or frame |
The units of each column are in df.attrs["units"].
xarray¶
For gridded work, AreaResult.to_xarray() returns an xarray.Dataset with dimensions
(lat, lon) (north first), one variable per parameter, each with attrs["units"]:
ds = area.to_xarray()
ds["temperature_2m"].plot()
It needs the extra: pip install 'stormlore[xarray]'. Without it, to_xarray() raises
MissingExtraError naming the extra. area.array("temperature_2m") gives the plain
(height, width) numpy array, and area.lats / area.lons its coordinates.
Units¶
Values come back exactly as the API serves them: kelvin, m/s, pascals, metres. Nothing is converted silently, so the numbers match the REST API.
To convert, set a default on the client, or ask per call:
client = Client(units="imperial") # or "metric"; default "native"
point = client.forecast.point("gfs", (41.26, -95.94), "temperature_2m")
point["temperature_2m"].value # still kelvin
point.to_dataframe() # °F, and df.attrs["units"] says so
point.to_dataframe(units="native") # kelvin again
point["temperature_2m"].to("°C") # one value, converted
| From | metric | imperial |
|---|---|---|
| K | °C | °F |
| m/s | km/h | mph |
| Pa | hPa | inHg |
| m | km | ft |
| mm | mm | in |
Anything else (percentages, categories) is left as served.
Tiles¶
client.tiles.get(model, parameter, z, x, y) returns a 256 × 256 PNG data tile and the
value range its pixels encode (value_min, value_max, units);
client.tiles.metadata(model, parameter) describes the decoding. The time defaults the
same way as a query.
Draw it¶
series.plot(units="imperial") # a line per parameter; area.plot() and trip.plot() map
Every chart, drawn: charts and maps (pip install 'stormlore[viz]').