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 to 2 decimal places (which implies that the maximum possible error equals ~1km or 0.7 miles).

model

Forecast model. Accepted values:

Weather models

• arome - covers France and surrounding areas
• aromeAntilles - covers French Antilles
• aromeFrance - covers metropolitan France
• aromeReunion - covers Réunion island
• icon - global model (ICON-Global)
• iconD2 - covers Germany, Austria and Switzerland with high resolution
• iconEu - covers Europe and surrounding areas
• gfs - global model
• namConus - covers the continental USA and surrounding areas
• namHawaii - covers Hawaii
• namAlaska - covers Alaska and surrounding areas
• hrrrConus - covers the continental USA with high resolution
• hrrrAlaska - covers Alaska with high resolution
• canHrdps - covers Canada with high resolution

Sea models

• gfsWave - global wave model, excluding Hudson Bay (partly), Black Sea, Caspian Sea and most of the Arctic Ocean
• iconWave - global wave model (ICON-GWAM)
• iconEuWave - covers European seas (ICON-EWAM)
• canRdwpsWave - covers Canadian waters
• cmems - global ocean current model (Copernicus Marine Service)

Air quality models

• cams - global air quality model
• camsEu - covers Europe, includes pollen data

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

A forecast parameter. Accepted values:

Weather models

Sea models

Air quality models

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 work for the 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 is 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 indices 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 to 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 means that the particular model has no forecast for the given combination 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.

Weather parameters

Parameter	Response key	Description
temp	temp-[level]	Air temperature
dewpoint	dewpoint-[level]	The dew point temperature, i.e. the temperature at which 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 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 5 - Snow 7 - Mixture of rain and snow 8 - Ice pellets Note: Not all precipitation types are supported by all models.
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.
cbase	cbase-surface	Cloud base height, the altitude of the lowest cloud layer above ground.
visibility	visibility-surface	Horizontal visibility at surface level.
weatherWarnings	weatherwarnings-surface	Numeric code for significant weather phenomena in the past 3 hours. 45 Fog 48 Fog, depositing rime 51 Slight drizzle 53 Moderate drizzle 55 Heavy drizzle 56 Drizzle, freezing, slight 57 Drizzle, freezing, moderate or heavy 61 Slight rain, not freezing 63 Moderate rain, not freezing 65 Heavy rain, not freezing 66 Rain, freezing, slight 67 Rain, freezing, moderate or heavy 71 Slight fall of snowflakes 73 Moderate fall of snowflakes 75 Heavy fall of snowflakes 77 Snow grains 80 Rain shower(s), slight 81 Rain shower(s), moderate or heavy 82 Rain shower(s), violent 85 Snow shower(s), slight 86 Snow shower(s), moderate or heavy 95 Thunderstorm, slight or moderate 96 Thunderstorm with hail, or heavy thunderstorm

Sea parameters

Parameter	Response key	Description
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.
wavesPower	waves_power-surface	Wave energy flux, the power transported by waves per unit of wave crest length.
swell1	swell1_height-surface swell1_period-surface swell1_direction-surface	The height, period and direction of the waves' swell. The waves were 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 smaller 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.
currents	seacurrents_u-surface seacurrents_v-surface	Ocean surface current speed and direction defined by a two-dimensional vector. The component u defines the speed of a current flowing from the West towards the East (a negative value therefore implies the opposite direction). The component v similarly defines the speed of a current flowing from the South towards the North.
currentsTide	seacurrents_tide_u-surface seacurrents_tide_v-surface	Tidal component of the ocean surface current, defined by a two-dimensional vector. The component u defines the speed of a tidal current flowing from the West towards the East (a negative value therefore implies the opposite direction). The component v similarly defines the speed of a tidal current flowing from the South towards the North.

Air quality parameters

Parameter	Response key	Description
aqi	aqi_us-surface	Air Quality Index (US standard, 0–500).
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 carbon monoxide concentration in the troposphere.
go3	go3-surface	Ground-level ozone concentration.
no2	no2-surface	Nitrogen dioxide concentration, a pollutant produced primarily by combustion processes.
pm10	pm10-surface	Concentration of particulate matter with diameter up to 10 µm.
pm2p5	pm2p5-surface	Concentration of fine particulate matter with diameter up to 2.5 µm.
pollenAlder	pollen_alder-surface	Alder pollen concentration.
pollenBirch	pollen_birch-surface	Birch pollen concentration.
pollenGrass	pollen_grass-surface	Grass pollen concentration.
pollenMugwort	pollen_mugwort-surface	Mugwort pollen concentration.
pollenOlive	pollen_olive-surface	Olive pollen concentration.
pollenRagweed	pollen_ragweed-surface	Ragweed pollen concentration.