Weather API in Detail Weather API is based on HTTP queries, which are sent to Vaisala servers. Locations are identified by lat/lon coordinates. Replies are JSON, XML or delimited ASCII raw data, which is language independent. Customers must relay queries from end users/devices via a central proxy server(s). Vaisala will open access to the query interface only for specified proxy server IP address(es). The service also assumes a random distribution of queries, i.e. it is not allowed to use Weather API for batch mode querying of a large number of places in a busy loop. Any batch mode querying should include a 1 s delay between queries (1 QPS), over 10 QPS batch querying accounts may be throttled without advance notice.
Weather data provided Current conditions Current conditions: data from the closest relevant weather observation station which has recently reported data If there are no recent observations within 100 km of the given coordinates, current conditions will not be reported. Vaisala provides complimentary gif/png images for visualization of weather codes. Current condition parameters as reported by the station observation station name - e.g. "London Heathrow" distance - distance to the observations station from the chosen location e.g. "8 km NE" observation time - the time the observation was made in local time the temperature in Celsius or Fahrenheit the feels-like temperature in Celsius or Fahrenheit graphical symbol code - e.g. "d420" wind speed in m/s, knots, km/h or miles/h wind direction (N, NE, E, ...) pressure in hPa, e.g. "1012" relative humidity in percentages, e.g. "87" visibility in meters, e.g. "10000" for 10 km Detailed short forecasts Detailed short forecasts: contain intra-day details for several time steps Available with one hour, 3-hourly, 6-hourly intervals Vaisala provides complimentary gif/png images for visualization of weather codes Recommended forecast length up to two days Daily overview forecasts Daily overview forecasts: contain summary data for one day Recommended forecast length up to seven days Vaisala provides complimentary gif/png images for visualization of weather codes Weather parameters limited to: graphical symbol code min/max temperature in Celsius or Fahrenheit
Current conditions Current conditions: data from the closest relevant weather observation station which has recently reported data If there are no recent observations within 100 km of the given coordinates, current conditions will not be reported. Vaisala provides complimentary gif/png images for visualization of weather codes. Current condition parameters as reported by the station observation station name - e.g. "London Heathrow" distance - distance to the observations station from the chosen location e.g. "8 km NE" observation time - the time the observation was made in local time the temperature in Celsius or Fahrenheit the feels-like temperature in Celsius or Fahrenheit graphical symbol code - e.g. "d420" wind speed in m/s, knots, km/h or miles/h wind direction (N, NE, E, ...) pressure in hPa, e.g. "1012" relative humidity in percentages, e.g. "87" visibility in meters, e.g. "10000" for 10 km
Detailed short forecasts Detailed short forecasts: contain intra-day details for several time steps Available with one hour, 3-hourly, 6-hourly intervals Vaisala provides complimentary gif/png images for visualization of weather codes Recommended forecast length up to two days
Daily overview forecasts Daily overview forecasts: contain summary data for one day Recommended forecast length up to seven days Vaisala provides complimentary gif/png images for visualization of weather codes Weather parameters limited to: graphical symbol code min/max temperature in Celsius or Fahrenheit
Options Weather API can be configured with an additional for-fee GeoLocation feature. Enabling the GeoLocation feature adds an additional name attribute to the weather data replies so that a meaningful location name can be provided for the end-user in addition to the weather data. How to display attribution? All products which use any of the Weather API, Weather Map API or other Vaisala raw data feed packages must display attribution to Vaisala near the weather information by one of the following phrases, or an appropriate translation: "Powered by Vaisala", "Weather data provided by Vaisala", "Weather data source: Vaisala". If possible, the text "Vaisala" should be replaced by one of the graphic images available here. See document Vaisala logo and attribution requirements for detailed instructions.
Query examples NOTE: reply parsing must be able to cope with new weather parameters that may appear in the API in the future, i.e. new JSON keys, XML tags or new columns in delimited ASCII. Daily overview queries API query for a two day forecast https://HOST/data?lon=24.97&lat=60.32&ftimes=48/24h&tz=Europe/Helsinki&format=json/[YOUR-API-KEY] API response { "loc": [ { "obs":{ "station":"Helsinki Kumpula", "dist":"2 km S", "dt":"2020-10-22 09:20:00", "t":"9", "tf":"7", "s":"d410", "wn":"SE", "ws":"5", "p":"998.5", "rh":"97", "v":"6610" }, "fc": [ { "dt":"2020-10-22", "s":"d430", "tx":"11", "tn":"8", "pr": "14.83", "wsx":"6" }, { "dt":"2020-10-23", "s":"d220", "tx":"11", "tn":"1", "pr": "5.91", "wsx":"6" } ] } ] } Short forecast queries API query for a two hour forecast https://HOST/data?lon=24.97&lat=60.32&ftimes=2/1h&tz=Europe/Helsinki&format=json/[YOUR-API-KEY] API Response { "loc":[ { "obs": { "station":"Helsinki-Vantaa", "dist":"1 km NW", "dt":"2020-10-22 09:49:00", "t":"9", "tf":"6", "s":"d430", "wn":"SE", "ws":"5", "p":"998.2", "rh":"98", "v":"3879" }, "fc": [ { "dt":"2020-10-22 10:00", "s":"d430", "t":"8", "tf":"5", "ws":"5", "wn":"S", "pp":"99", "pr":"2.06" }, { "dt":"2020-10-22 11:00", "s":"d430", "t":"8", "tf":"6", "ws":"5", "wn":"S", "pp":"99", "pr":"2.45" } ] } ] } Requesting several forecast intervals in one call It is possible to request for example hourly and daily forecast in one API call. The following request http://HOST/data?lon=24.97&lat=60.22&ftimes=24/1h,120/24h&format=json/[YOUR_API_KEY]&tempunit=C&windunit=MS is responded with the hourly forecast for the next 24 hours and a daily forecast for the next 5 days. In response these forecast intervals are found under separate json keys (fc1,fc2,...). API query to search locations API query to search locations https://HOST/search?q=new%20york&format=json/[YOUR-API-KEY] API Response { "searchresults": { "query":"new york", "loc": [ { "id":"105128581" "name":"New York City", "country":"United States", "tz":"America\/New_York", "lon":"-74.005973816","lat":"40.714267731"}, { "id":"105128616", "name":"New York Mills", "country":"United States", "tz":"America\/New_York", "lon":"-75.291275024", "lat":"43.105346680" }, { "id":"105039192", "name":"New York Mills", "country":"United States", "tz":"America\/North_Dakota\/Center", "lon":"-95.376144409", "lat":"46.518016815" } ] } } Pick the location from the result list and use its "id" to request weather data for the location: http://HOST/data?l=105128581&ftimes=48/24h&format=json/[YOUR_API_KEY]&tempunit=C&windunit=MS&tz=
Daily overview queries API query for a two day forecast https://HOST/data?lon=24.97&lat=60.32&ftimes=48/24h&tz=Europe/Helsinki&format=json/[YOUR-API-KEY] API response { "loc": [ { "obs":{ "station":"Helsinki Kumpula", "dist":"2 km S", "dt":"2020-10-22 09:20:00", "t":"9", "tf":"7", "s":"d410", "wn":"SE", "ws":"5", "p":"998.5", "rh":"97", "v":"6610" }, "fc": [ { "dt":"2020-10-22", "s":"d430", "tx":"11", "tn":"8", "pr": "14.83", "wsx":"6" }, { "dt":"2020-10-23", "s":"d220", "tx":"11", "tn":"1", "pr": "5.91", "wsx":"6" } ] } ] }
Short forecast queries API query for a two hour forecast https://HOST/data?lon=24.97&lat=60.32&ftimes=2/1h&tz=Europe/Helsinki&format=json/[YOUR-API-KEY] API Response { "loc":[ { "obs": { "station":"Helsinki-Vantaa", "dist":"1 km NW", "dt":"2020-10-22 09:49:00", "t":"9", "tf":"6", "s":"d430", "wn":"SE", "ws":"5", "p":"998.2", "rh":"98", "v":"3879" }, "fc": [ { "dt":"2020-10-22 10:00", "s":"d430", "t":"8", "tf":"5", "ws":"5", "wn":"S", "pp":"99", "pr":"2.06" }, { "dt":"2020-10-22 11:00", "s":"d430", "t":"8", "tf":"6", "ws":"5", "wn":"S", "pp":"99", "pr":"2.45" } ] } ] }
Requesting several forecast intervals in one call It is possible to request for example hourly and daily forecast in one API call. The following request http://HOST/data?lon=24.97&lat=60.22&ftimes=24/1h,120/24h&format=json/[YOUR_API_KEY]&tempunit=C&windunit=MS is responded with the hourly forecast for the next 24 hours and a daily forecast for the next 5 days. In response these forecast intervals are found under separate json keys (fc1,fc2,...).
API query to search locations API query to search locations https://HOST/search?q=new%20york&format=json/[YOUR-API-KEY] API Response { "searchresults": { "query":"new york", "loc": [ { "id":"105128581" "name":"New York City", "country":"United States", "tz":"America\/New_York", "lon":"-74.005973816","lat":"40.714267731"}, { "id":"105128616", "name":"New York Mills", "country":"United States", "tz":"America\/New_York", "lon":"-75.291275024", "lat":"43.105346680" }, { "id":"105039192", "name":"New York Mills", "country":"United States", "tz":"America\/North_Dakota\/Center", "lon":"-95.376144409", "lat":"46.518016815" } ] } } Pick the location from the result list and use its "id" to request weather data for the location: http://HOST/data?l=105128581&ftimes=48/24h&format=json/[YOUR_API_KEY]&tempunit=C&windunit=MS&tz=
Response interpretation Be prepared to handle missing current conditions (observations) information, since missing instrumentation or instrument malfunctions may affect data. Any of the parameter values can be missing/empty, and even the entire obs key (in JSON), tag (in XML) or OBSH/OBS rows (in the text) can be missing, try lon=0&lat=0 for an example. In case of missing data, it is recommended to simply adapt lay-out so that white space is shown instead. Texts like "No data" are often interpreted by end-users as a service malfunction, which is not the case. The forecast parameters/rows will always be there, so missing value handling does not need to be as robust as with the current conditions. The forecasts can only be missing in the case of real technical problems. Required query parameters lon - the longitude of the location, in decimal degrees lat - the latitude of the location, in decimal degrees or id - Vaisala location id format - reply format, Each customer is provided a dedicated format name, "json/standardfeed" and "xml/standardfeed" are used as examples above. Custom formats can be created. Optional query parameters alt - altitude above sea level in meters, e.g. "2148" for 2148 meters. By default, the altitude is estimated from the numerical weather prediction (NWP) model value for the given coordinates, which can cause errors in mountain regions. Providing the actual altitude will enable the Weather API forecast engine to make better temperature predictions in locations with large height variations. On level ground, the benefit will be negligible. tempunit - either "C" or "F" for Celsius or Fahrenheit, defaults to Celsius windunit - either "MS", "KTS", "KMH", or "MPH" for m/s, knots, km/h or miles/h, defaults to m/s tz - POSIX formatted time zone string for response timestamps, e.g. "UTC", or "Europe/Helsinki". If not given, time zone is approximated from coordinates, which can result in errors near time zone borders. ftimes - (only standard/premium packages) length/step-interval of the requested forecast in hours, 24h interval switches on the daily overview mode. E.g. "72/24h" returns daily overview for the next three days, "48/3h" returns three-hourly forecasts for the next two days, and "12/1h" returns hourly forecasts for the next 12 hours. Recommended intervals are: 1, 3, 6, 24. The maximum forecast length is 10 days. Optionally the time of the first forecast can be given in the ftimes parameter, see below for details (*). (*) using ftimes query parameter to specify the first timestep There are two formats: ftimes=length/timestep ftimes=length/timestep/firststep Format 1 uses default values for deciding the time of the first forecast. In format 2 the first step parameter modifies the time of the first forecast. For daily summary forecasts (of type x/24h) it is interpreted as the number of hours before midnight, default is 11. For hourly forecasts it is interpreted as the minimum number of hours from now to the first forecast time step, default is 0. Examples: ftimes=72/24h - Default, 1 pm, i.e. switch the date at 13:00 o'clock ftimes=72/24h/11 - Same as default, switch the date at 13:00 o'clock, 11 hours before midnight ftimes=72/24h/3 - Switch the date at 9 pm (3 hours before midnight) ftimes=72/24h/0 - Switch the date at midnight ftimes=72/24h/-6 - Show yesterday's forecast until 6 am ftimes=12/1h - Default, hourly forecasts twelve hours forwards from now ftimes=12/1h/0 - Same as default, hourly forecasts with first-time step zero hours from now ftimes=12/1h/6 - Hourly forecasts for twelve hours, starting six hours from now, i.e. ending 18 hours from now Please note that the time zone calculation for local time is approximate. Response parameters dt - timestamp of the observation/forecast, for daily overview dt contains only the date part. Unless provided in the query parameters, for Weather API forecasts the time zone is an approximation, which may be inaccurate near time zone borders. When using Foreca IDs the time zone is accurate. For observations (the obs tag) the time is always in local time of the observation station. station - observation station name - e.g. "Berlin Tegelhof" dist - distance to the observations station from the given coordinates appended with wind direction in English, e.g. "8 km NE" p - pressure in hPa, e.g. "1012" v - visibility in meters, e.g. "10000" for 10 km t - air temperature (default unit: Celsius) tx - 24h maximum temperature (default unit: Celsius) (daily summary data) tn - 24h minimum temperature (default unit: Celsius) (daily summary data) tf - the so-called feels-like temperature (default unit: Celsius), which is the combined NOAA/NWS 'face only' wind chill index and Rothfusz heat index, which take into account the cooling and heating effects of wind and humidity rh - relative humidity in percentages, range from 0 to 100 pp - the probability of precipitation in percentages, range from 0 to 100 tp - the probability of thunder in percentages, range from 0 to 100 pr - accumulated precipitation (default unit: millimeters). Exception: If 15 minute time steps are requested "pr" is the intensity of the rain (unit :millimeters / hour). ws - 10-minute average wind speed (default unit: m/s) wsx - daily maximum of the 10-minute average wind speed (default unit: m/s) wsa - daily average of the 10-minute average wind speed (default unit: m/s) wn - wind direction string, one of N, NE, E, SE, S, SW, W, NW s - symbol code (see explanations in https://corporate.foreca.com/en/resources/foreca-symbols) c - cloudiness, in percentages, range from 0 to 100 ca - average cloudiness during the day in percentages, range from 0 to 100 sT - symbol code as text, use the lang parameter to control output language rise - sunrise time in 24h clock notation in local time set - sunset time in 24h clock notation in local time UV - UV index based on the global ozone forecast model (1-2=low, 3-5=moderate, 6-7=high, 8-10=very high, 11+=extreme) NOTE: max 5 days forecast available dl - day length in minutes Please note that Weather API may be upgraded with new data in the future. This means that your application must parse the response so that it does not break if the order of the parameters changes or new parameters appears.
Required query parameters lon - the longitude of the location, in decimal degrees lat - the latitude of the location, in decimal degrees or id - Vaisala location id format - reply format, Each customer is provided a dedicated format name, "json/standardfeed" and "xml/standardfeed" are used as examples above. Custom formats can be created.
Optional query parameters alt - altitude above sea level in meters, e.g. "2148" for 2148 meters. By default, the altitude is estimated from the numerical weather prediction (NWP) model value for the given coordinates, which can cause errors in mountain regions. Providing the actual altitude will enable the Weather API forecast engine to make better temperature predictions in locations with large height variations. On level ground, the benefit will be negligible. tempunit - either "C" or "F" for Celsius or Fahrenheit, defaults to Celsius windunit - either "MS", "KTS", "KMH", or "MPH" for m/s, knots, km/h or miles/h, defaults to m/s tz - POSIX formatted time zone string for response timestamps, e.g. "UTC", or "Europe/Helsinki". If not given, time zone is approximated from coordinates, which can result in errors near time zone borders. ftimes - (only standard/premium packages) length/step-interval of the requested forecast in hours, 24h interval switches on the daily overview mode. E.g. "72/24h" returns daily overview for the next three days, "48/3h" returns three-hourly forecasts for the next two days, and "12/1h" returns hourly forecasts for the next 12 hours. Recommended intervals are: 1, 3, 6, 24. The maximum forecast length is 10 days. Optionally the time of the first forecast can be given in the ftimes parameter, see below for details (*). (*) using ftimes query parameter to specify the first timestep There are two formats: ftimes=length/timestep ftimes=length/timestep/firststep Format 1 uses default values for deciding the time of the first forecast. In format 2 the first step parameter modifies the time of the first forecast. For daily summary forecasts (of type x/24h) it is interpreted as the number of hours before midnight, default is 11. For hourly forecasts it is interpreted as the minimum number of hours from now to the first forecast time step, default is 0. Examples: ftimes=72/24h - Default, 1 pm, i.e. switch the date at 13:00 o'clock ftimes=72/24h/11 - Same as default, switch the date at 13:00 o'clock, 11 hours before midnight ftimes=72/24h/3 - Switch the date at 9 pm (3 hours before midnight) ftimes=72/24h/0 - Switch the date at midnight ftimes=72/24h/-6 - Show yesterday's forecast until 6 am ftimes=12/1h - Default, hourly forecasts twelve hours forwards from now ftimes=12/1h/0 - Same as default, hourly forecasts with first-time step zero hours from now ftimes=12/1h/6 - Hourly forecasts for twelve hours, starting six hours from now, i.e. ending 18 hours from now Please note that the time zone calculation for local time is approximate.
Response parameters dt - timestamp of the observation/forecast, for daily overview dt contains only the date part. Unless provided in the query parameters, for Weather API forecasts the time zone is an approximation, which may be inaccurate near time zone borders. When using Foreca IDs the time zone is accurate. For observations (the obs tag) the time is always in local time of the observation station. station - observation station name - e.g. "Berlin Tegelhof" dist - distance to the observations station from the given coordinates appended with wind direction in English, e.g. "8 km NE" p - pressure in hPa, e.g. "1012" v - visibility in meters, e.g. "10000" for 10 km t - air temperature (default unit: Celsius) tx - 24h maximum temperature (default unit: Celsius) (daily summary data) tn - 24h minimum temperature (default unit: Celsius) (daily summary data) tf - the so-called feels-like temperature (default unit: Celsius), which is the combined NOAA/NWS 'face only' wind chill index and Rothfusz heat index, which take into account the cooling and heating effects of wind and humidity rh - relative humidity in percentages, range from 0 to 100 pp - the probability of precipitation in percentages, range from 0 to 100 tp - the probability of thunder in percentages, range from 0 to 100 pr - accumulated precipitation (default unit: millimeters). Exception: If 15 minute time steps are requested "pr" is the intensity of the rain (unit :millimeters / hour). ws - 10-minute average wind speed (default unit: m/s) wsx - daily maximum of the 10-minute average wind speed (default unit: m/s) wsa - daily average of the 10-minute average wind speed (default unit: m/s) wn - wind direction string, one of N, NE, E, SE, S, SW, W, NW s - symbol code (see explanations in https://corporate.foreca.com/en/resources/foreca-symbols) c - cloudiness, in percentages, range from 0 to 100 ca - average cloudiness during the day in percentages, range from 0 to 100 sT - symbol code as text, use the lang parameter to control output language rise - sunrise time in 24h clock notation in local time set - sunset time in 24h clock notation in local time UV - UV index based on the global ozone forecast model (1-2=low, 3-5=moderate, 6-7=high, 8-10=very high, 11+=extreme) NOTE: max 5 days forecast available dl - day length in minutes Please note that Weather API may be upgraded with new data in the future. This means that your application must parse the response so that it does not break if the order of the parameters changes or new parameters appears.
Weather API The Weather API delivers quality weather forecasts to every coordinate point in the world. The interface with hyper-local forecasts is suitable for integrating weather conditions into mobile applications, web applications or any other application. Vaisala Weather API