Skip to content

Forecast and tiles

client.forecast and client.tiles. AsyncClient has the same methods, awaited.

Forecast

Forecast models and queries. Reach it as client.forecast.

Every query takes a model slug ("gfs", "hrrr" …), a place or area, and one or more parameter names. With no time given, the forecast valid nearest to now from the newest run is used. Values come back in the units the API serves (see units=).

models

models() -> ModelList

The models this API key can use.

parameters

parameters(model: str) -> ParameterList

The model's parameters, with their units.

runs

runs(model: str) -> RunList

The model's runs in the store, newest first, with the steps each has landed.

steps

steps(model: str) -> Steps

The serving run's forecast steps; .valid_times turns them into times.

times

times(model: str) -> Times

An analysis model's frame times (a forecast model answers InvalidRequestError).

point

point(
    model: str,
    place: PlaceLike,
    parameters: str | Iterable[str],
    *,
    at: TimeLike | None = None,
    run: TimeLike | None = None,
) -> PointResult

Values at one place and time.

Parameters:

Name Type Description Default
model str

Model slug, e.g. "gfs".

required
place PlaceLike

(lat, lon), a LatLon, or a 5-digit ZIP code string.

required
parameters str | Iterable[str]

One parameter name or several.

required
at TimeLike | None

When. None: the forecast valid nearest to now from the newest run.

None
run TimeLike | None

Query this run (its start time) instead of the newest.

None

Returns:

Type Description
PointResult

The values, with to_dataframe() giving one row.

timeseries

timeseries(
    model: str,
    place: PlaceLike,
    parameters: str | Iterable[str],
    *,
    at: TimeLike | Iterable[TimeLike] | None = None,
    run: TimeLike | None = None,
) -> TimeseriesResult

Values at one place over time.

Parameters:

Name Type Description Default
model str

Model slug.

required
place PlaceLike

(lat, lon), a LatLon, or a ZIP code string.

required
parameters str | Iterable[str]

One parameter name or several.

required
at TimeLike | Iterable[TimeLike] | None

The times wanted (one or many). None: every step of the run.

None
run TimeLike | None

Query this run instead of the newest.

None

Returns:

Type Description
TimeseriesResult

The series; to_dataframe() is indexed by UTC valid_time.

route

route(
    model: str,
    waypoints: Sequence[Any],
    parameters: str | Iterable[str],
    *,
    run: TimeLike | None = None,
) -> RouteResult

Values along a route.

Parameters:

Name Type Description Default
model str

Model slug.

required
waypoints Sequence[Any]

Each a Waypoint, a place, (place, at) or (lat, lon, at). Waypoints without a time share one: the forecast valid nearest to now.

required
parameters str | Iterable[str]

One parameter name or several.

required
run TimeLike | None

Query this run instead of the newest.

None

Returns:

Type Description
RouteResult

One entry per waypoint; to_dataframe() gives one row each.

area

area(
    model: str,
    bounds: BoundsLike,
    parameters: str | Iterable[str],
    *,
    at: TimeLike | None = None,
    width: int | None = None,
    height: int | None = None,
    run: TimeLike | None = None,
) -> AreaResult

Values over a bounding box, on a regular latitude/longitude grid.

Parameters:

Name Type Description Default
model str

Model slug.

required
bounds BoundsLike

A Bounds, a mapping with north/south/east/west, or (north, south, east, west).

required
parameters str | Iterable[str]

One parameter name or several.

required
at TimeLike | None

When. None: the forecast valid nearest to now from the newest run.

None
width int | None

Grid columns, at most 256. Default: follows the bounds' aspect.

None
height int | None

Grid rows, at most 256. Default: the longer side is 256.

None
run TimeLike | None

Query this run instead of the newest.

None

Returns:

Type Description
AreaResult

The grid; to_xarray() gives a Dataset(lat, lon).

Raises:

Type Description
ValueError

width or height is outside 1..256 (nothing is sent).

wind

wind(
    model: str,
    place: PlaceLike,
    *,
    at: TimeLike | None = None,
    run: TimeLike | None = None,
    u: str = "u_component_of_wind_10m",
    v: str = "v_component_of_wind_10m",
) -> WindResult

Wind speed and the direction it blows from, from the u/v components.

Parameters:

Name Type Description Default
model str

Model slug.

required
place PlaceLike

(lat, lon), a LatLon, or a ZIP code string.

required
at TimeLike | None

When. None: the forecast valid nearest to now from the newest run.

None
run TimeLike | None

Query this run instead of the newest.

None
u str

The eastward component's parameter name.

'u_component_of_wind_10m'
v str

The northward component's parameter name.

'v_component_of_wind_10m'

Tiles

Web Mercator data tiles (256 × 256 PNG). Reach it as client.tiles.

get

get(
    model: str,
    parameter: str,
    z: int,
    x: int,
    y: int,
    *,
    at: TimeLike | None = None,
    run: TimeLike | None = None,
    encoding: str = "grey8",
    threshold: float | None = None,
) -> Tile

One data tile.

Parameters:

Name Type Description Default
model str

Model slug.

required
parameter str

Parameter name.

required
z int

Zoom, 0..8.

required
x int

Tile column.

required
y int

Tile row.

required
at TimeLike | None

When. None: the forecast valid nearest to now from the newest run.

None
run TimeLike | None

Render this run instead of the newest.

None
encoding str

grey8 (8-bit) or rg16 (16-bit, exact to 1/65535 of the range).

'grey8'
threshold float | None

Hail size in inches, for hail_probability tiles only.

None

Returns:

Type Description
Tile

The PNG and the value range its pixels encode.

metadata

metadata(model: str, parameter: str) -> TileMetadata

The value range and units a parameter's tiles encode.