Documentation

Request

Requests are sent to the following endpoint: POST https://api.windy.com/api/point-forecast/v2 with the following body:

{
    "lat": 49.809,
    "lon": 16.787,
    "model": "desired_model",
    "parameters": ["desired_parameter_1", "desired_parameter_2", ...],
    "levels": ["optionally_desired_gh_level_1", ...],
    "key": "your_API_key"
}

For example:

{
    "lat": 49.809,
    "lon": 16.787,
    "model": "gfs",
    "parameters": ["wind", "dewpoint", "rh", "pressure"],
    "levels": ["surface", "800h", "300h"],
    "key": "windyisthebest"
}

lat/lon

The numerical values of the coordinates, e.g. 49.809 or -168. The value is automatically rounded off to 2 decimals (which implies that the maximum possible error equals ~1km or 0.7 miles).

model

Forecast model. Accepted values:

• Arome - covers France and surrounding areas
• IconEU - covers Europe and surrounding areas
• GFS - a global model
• GFS Wave - a global model EXCLUDING Hudson bay (partly), Black Sea, Caspian Sea, most of the Arctic Ocean.
• namConus - covers the USA and surrounding areas (Canada, Mexico)
• namHawaii - covers Hawaii
• namAlaska - covers Alaska and surrounding areas.
• geos5 - a global model

levels

An array of geopotential values (the default value is ["surface"]). It is applicable for the following parameters: wind, dewpoint, temp, gh and rh. For all other parameters the default value surface is used instead.

The allowed values are: surface, 1000h, 950h, 925h, 900h, 850h, 800h, 700h, 600h, 500h, 400h, 300h, 200h, 150h

parameters

The forecast's attribute. Accepted values:

The individual parameters are described below in the section Parameters.

key

A specific API key generated by the user. Keys generated for other services, e.g. map forecast or webcams, are a distinct category, and do not function for point forecast API.

Response

A response to the user's request. It can return the following HTTP status codes:

• 200: everything went as expected
• 204: the selected model does not feature any of the requested parameters
• 400: invalid request, error in the body’s description
• 500: unexpected error (normally it should not occur - can happen e.g. when our back ends cannot return data)

If all being well, the body contains the following:

{
    ts:int[],
    units: {
        {parameter-level}: string,
        {parameter2-level}: string,
        ...
    },
    {parameter-level}: float[],
    {parameter2-level}: float[],
    ...
}

Where {parameter - level} corresponds with the individual parameters at specified altitudes.
The object units describes the units in which the individual parameters are presented. More in the Parameters section below.

The sizes of all returned arrays are identical and the indexes mutually correspond. For example at the surface altitude the value of temp-surface[5] in the units defined as units["temp-surface"] contains the temperature for a timestamp ts[5] of the local time for given spatial coordinates. The timestamp value ts[5] corresponds with the number of milliseconds that have passed since January 1st 1970 (compatible with e.g. JavaScript - new Date(ts[5])).

If the value is null, it means that the forecast model has no value for the given time, position and parameter.

If the body of the response lacks a certain combination of a given parameter-level, it implies that for the given combination in the particular model has no forecast whatsoever.

Parameters

The units of individual parameters are explained in the object units, which is a part of the response. The format is as follows: (unit(exp)?)(\*unit(exp)?)*. For example:

• m*s-1 is m/s
• J*kg-1 is J/kg
• µg*m-3 is µg/m³
• Or simply just: s, Pa or %
• Et cetera.

If a given parameter is unitless, the value is null.

Parameter	Response key	Description
temp	temp-[level]	Air temperature
dewpoint	dewpoint-[level]	The temperature of dew point, i.e. at which temperature the air reaches 100% humidity.
precip	past3hprecip-surface	The overall accumulation of all precipitation (water column) for the preceding 3 hours, including snowPrecip and convPrecip (see below).
snowPrecip	past3hsnowprecip-surface	The overall snowfall (water column) for the preceding 3 hours.
convPrecip	past3hconvprecip-surface	The overall precipitation caused by convection (water column) for the preceding 3 hours.
wind	wind_u-[level] wind_v-[level]	Wind speed and direction defined by a two-dimensional vector. The component u defines the speed of a wind blowing from the West towards the East (a negative value therefore implies the opposite direction). The component v similarly defines the speed of a wind blowing from the South towards the North.
windGust	gust-surface	The speed of wind at gusts.
cape	cape-surface	Convective available potential energy.
ptype	ptype-surface	Precipitation type. The value is an integer representing the following types: 0 - No precipitation 1 - Rain 3 - Freezing rain only GFS and NAM 5 - Snow 7 - Mixture of rain and snow only AROME and ICON EU 8 - Ice pellets only GFS and NAM
lclouds	lclouds-surface	Low clouds at levels with air pressure above 800hPa. The value describes the overall cloud coverage.
mclouds	mclouds-surface	Medium clouds at levels with air pressure between 450hPa and 800hPa. The value describes the overall cloud coverage.
hclouds	hclouds-surface	High clouds at levels with air pressure below 450hPa. The value describes the overall cloud coverage.
rh	rh-[level]	Relative humidity of air.
gh	gh-[level]	Geopotential height. Signifies at which altitude there is a given air pressure level.
pressure	pressure-surface	Air pressure.
waves	waves_height-surface waves_period-surface waves_direction-surface	The waves' height, period and direction. The direction defines where the waves come from. The period defines the time interval between arrival of consecutive crests at a stationary point.
windWaves	wwaves_height-surface wwaves_period-surface wwaves_direction-surface	The wind waves' height, period and direction. Wind waves, or wind-generated waves, are surface waves that occur on the free surface of bodies of water (like oceans, seas, lakes, etc.). They result from the wind blowing over an area of water surface. Wind waves are generated by the immediate local wind - which gives them the direction. After the wind ceases to blow, wind waves are called swells. The direction defines where the waves come from. The period defines the time interval between arrival of consecutive crests at a stationary point.
swell1	swell1_height-surface swell1_period-surface swell1_direction-surface	The height, period and direction of the waves' swell. The waves had been created by wind in another area and are not created by local winds. The direction defines where the waves come from (0 = North, 90 = East, 180 = South, 270 = West). The period defines the time interval between arrival of consecutive crests at a stationary point.
swell2	swell2_height-surface swell2_period-surface swell2_direction-surface	The height, period and direction of the waves' swell. Similar to swell1, but the waves are of smaller sizes and come from a different area. The direction defines where the waves come from (0 = North, 90 = East, 180 = South, 270 = West). The period defines the time interval between arrival of consecutive crests at a stationary point.
so2sm	chem_so2sm-surface	Sulfur dioxide is released naturally by volcanic activity and is produced as a by-product of the burning of fossil fuels contaminated with sulfur compounds.
dustsm	chem_dustsm-surface	Dust particles in the atmosphere that come from various sources such as soil, dust lifted by weather, volcanic eruptions, and air pollution.
cosc	chem_cosc-surface	The level of carbon monoxide concentrationin the troposphere.