Skip to content

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 raises ValueError before 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 the read:observations scope on your key; without it you get ZipLookupForbiddenError — pass (lat, lon) instead. A ZIP that does not exist raises UnknownZipError.
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.datetime64 or pandas.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), a LatLon, {"lat": ..., "lon": ...} or a ZIP code string;
  • (lat, lon, at);
  • (place, at), where the place is (lat, lon), a LatLon or 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]').