Point Forecast API

Get machine-readable weather forecast data for a specified set of coordinates.

Getting started

To get API working, just do these 2 simple steps:

  1. Obtain your Point Forecast API key here
  2. Send POST request to the URL: https://api.windy.com/api/point-forecast/v2

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": "abcd123"
}
        

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
  • Wavewatch - a global model EXCLUDING the mediterranean, Hudson bay, Black Sea, Caspian Sean, 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:

arome iconEu gfs wavewatch namConus namHawaii namAlaska geos5
temp
dewpoint
precip
convPrecip
snowPrecip
wind
windGust
cape
ptype
lclouds
mclouds
hclouds
rh
gh
pressure
waves
windWaves
swell1
swell2
so2sm
dustsm
cosc

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
  • 5 - Snow
  • 6 - Wet snow (i.e. starting to melt)
    only GFS
  • 7 - Mixture of rain and snow
    only AROME and ICON EU
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.

Technical support

Drop a line in our Windy API section of our Windy Community forum.

Windy community forum