Weather API -technical details

Please note: the information on this page concerns the old Weather API formulation which is not for sale anymore. For the documentation of the latest version of Foreca Weather API, please visit our developer site.

Interested in trying the latest version of Foreca Weather API?

Sign up for Weather API free trial

How Does It Work?

weather_API

Foreca Weather API responses in JSON, XML or delimited ASCII format.

The forecasts can be given by coordinate or by location name. Coordinate based, the so-called hyper-local forecasts are calculated on the exact point in real time. All the commonly used weather parameters are available. If you need parameters not mentioned in this page, please read more about our add-on data sets or ask about our custom API's.

Weather Parameters

Current Conditions

In addition to forecasts, the API includes the latest measurements from tens of thousands official weather stations worldwide. Foreca gathers observation data from the official SYNOP and METAR weather stations and other similar high-quality sources worldwide. Observations are given from the closest relevant weather observation station that would best tell the weather at the forecast location.

Parameters provided
  • Name of the closest relevant weather station (e.g. London Heathrow)
  • Distance to the observation station
  • Observation time (latest)
  • Weather code and symbol (gif, png)
  • Temperature (°C, °F)
  • Feels-like temperature (°C, °F)
  • Wind speed (in m/s, kmph, km/h, knots)
  • Wind direction (N, NE, E, …, or pictures)
  • Air pressure (in hPa)
  • Relative humidity (in %)
  • Visibility (in meters)

Observations are updated according to the measurement schedule of the station, which can vary from 10 minutes for automated stations in the developed nations to 3 hours for rural manual stations. The parameters above are provided from most of the weather stations. Some parameters can be missing in case of the weather station is lacking instruments or they are broken. The missing parameters can be fulfilled with the synthetic observations.

 

Synthetic Observations

As official weather stations are not everywhere, Foreca Nowcasting technology enables forecasting hyper-local current conditions also in locations that do not have a weather station close-by. The so-called synthetic (or augmented) observations are calculated in real-time to any coordinate point worldwide.

Nowcasting technology is used for rain, temperature and cloudiness to dramatically improve their accuracy. The other parameters are interpolated from the forecast data.

Parameters provided
  • Weather code and symbol (gif, png)
  • Temperature (°C, °F)
  • Feels-like temperature (°C, °F)
  • Wind speed (in m/s, mph, km/h, knots)
  • Wind direction (N, NE, E, ..., or pictures)
  • Precipitation probability (in %)
  • Precipitation sum for the 1-hour period (in mm)
  • Solar radiation

 

15-Minute Forecast

Foreca provides forecasts in 15-minute steps for the following couple of hours, starting from the zero-time (synthetic observation). Rain, temperature, and cloudiness parameters are provided by Nowcasting technology and the other parameters below are broken down from the hourly forecasts’ data sets. 15-minute steps are recommended to use for the following 2 hours maximum.

Parameters provided
  • Weather code and symbol (gif, png)
  • Temperature (°C, °F)
  • Feels-like temperature (°C, °F)
  • Wind speed (in m/s, mph, km/h, knots)
  • Wind direction (N, NE, E, ..., or pictures)
  • Precipitation probability (in %)
  • Precipitation sum for the 15-minute period (in mm)
  • Solar radiation (optional)

 

Hourly Forecast

With hourly forecast data, you are able to receive weather forecasts in one-hour steps. Hourly forecast is adequate to show detailed weather forecasts in the coming days as a table or graphical module. In addition to 1h steps, additional 3h and 6h summaries are available. The data is provided for the next 14 days, including the current day.

Parameters provided
  • Weather code and symbol (gif, png)
  • Temperature (°C, °F)
  • Feels-like temperature (°C, °F)
  • Wind speed (in m/s, mph, km/h, knots)
  • Wind direction (N, NE, E, ..., or pictures)
  • Precipitation probability (in %)
  • Precipitation sum for the 1/3/6-hour period (in mm)
  • Solar radiation (optional)

 

Daily Forecast

Daily forecast is a 24-hour summary of the day. The data is provided for the next 14 days, including the current day.

Parameters provided
  • Weather code and symbol (gif, png)
  • Daily forecasted high and low temperatures (°C, °F)
  • Precipitation sum for the 24-hour period (in mm)
  • Wind speed maximum (in m/s, mph, km/h, knots)
  • Precipitation probability
  • Sunset and sunrise time
  • Moonset and moonrise time
  • Day length (in minutes)
  • UV index based on the global ozone forecast model
  • Average cloudiness
  • Thunder probability
  • Last-updated time

 

Add-On modules

Foreca provides the following weather information data that can be delivered together with Foreca Weather API.

Weather-observations-1

The official weather stations are maintained by national weather institutes. The stations measure the state of the ground and the lower atmosphere. The stations are standardized and the data is freely exchanged between all the nations of the world. The station locations are carefully chosen to represent the average climate in the region.

Foreca selects the closest relevant weather station based on the following principles: the closer a station is, the better; the closer a station is an altitude, the better (critical in mountainous areas); a station providing more data/parameters is better; fresh data is better than old.

Current-conditions-1

Synthetic observations are calculated in realtime to exact coordinate points with the help of Foreca Nowcasting technology. Nowcasting accuracy is dependent on available data sources varying in different locations - e.g. rain radar is available for limited geographical areas only.

Nowcasting-1

Synthetic observations are calculated in realtime to exact coordinate points with the help of Foreca Nowcasting technology. Nowcasting accuracy is dependent on available data sources varying in different locations - e.g. rain radar is available for limited geographical areas only.

Hourly-forecast

An example of hourly forecast data visualised.

Daily-forecasts

Daily forecast data gives comprehensive daily summaries up to two weeks in the future.

Weather Data Delivery

Weather API is based on HTTP queries, which are sent to Foreca's servers. Foreca provides two query methods valid for different occasions. Queries can be made based on 1) Coordinate or 2) Location name.

Coordinate-based queries are ideal for mobile and navigation applications, as the forecasts are calculated on the exact point in real time. Location name-based queries are commonly used in web applications (140.000 named locations worldwide), when location search or picklists are practical for the end-user. Replies are in JSON, XML or delimited ASCII format.

Our services are reasonably priced based on the customer use case, the service usage volume and amount of customisation work required. We would be happy to offer you our pricing quote after we have specified together your requirements for the service. Our value proposition is to always deliver a weather service that is a perfect fit for the customer need. To be able to focus on major customer projects currently we are not offering freemium services or short term project deliveries.

Weather API in Detail

This is the technical documentation of the old version of Weather API. If you are using the new version of Foreca Weather API, please see the documentation on our developer site.

Weather API is based on HTTP queries, which are sent to Foreca servers. Locations are identified by lat/lon coordinates. Replies are JSON, XML or delimited ASCII raw data, which is language independent.

Customer must relay queries from end users/devices via a central proxy server(s). Foreca 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: 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
  • Foreca 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
    • temperature in Celsius or Fahrenheit
    • 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: contain intra-day details for several time steps

  • Available with one hour, 3-hourly, 6-hourly intervals
  • Foreca provides complimentary gif/png images for visualization of weather codes
  • Recommended forecast length up to two days

Daily overview forecasts: contain summary data for one day

  • Recommended forecast length up to seven days
  • Foreca 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 Foreca raw data feed packages must display attribution to Foreca near the weather information by one of the following phrases, or an appropriate translation: "Powered by Foreca", "Weather data provided by Foreca", "Weather data source: Foreca". If possible, the text "Foreca" should be replaced by one of the graphic images available here.  See document Foreca 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

Forecast for the next two days

http://HOST/data?lon=24.97&lat=60.22&ftimes=48/24h&format=json/[YOUR_API_KEY]&tempunit=C&windunit=MS&tz=
dailyoverview

Short forecast queries

Forecast for the next two hours

shortforecast

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

Forecast for the next two hours

 
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 hourly forecast for the next 24 hours and daily forecast for the next 5 days. In response these forecast intervals are found under separate json keys (fc1,fc2,...).

Using location name to search for weather forecast

Search a location from Foreca location database, for example with term "lond":

searchresults

 

Pick the location from the result list and use its "id" to request weather data for the location:

http://HOST/data?l=102643743&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 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 - Foreca 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 variation. 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 time stamps, 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 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. 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 first timestep

There are two formats:

  1. ftimes=length/timestep
  2. ftimes=length/timestep/firststep

Format 1 uses default values for deciding the time of the first forecast. In format 2 the firststep 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 - time stamp 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 - probability of precipitation in percentages, range from 0 to 100
  • tp - 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://developer.foreca.com/resources)
  • 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 lang parameter to control output language
  • rise - sun rise time in 24h clock notation in local time
  • set - sun set 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 appear. 

Pricing principle

Please note! This pricing principle applies only in the license agreements where the pricing is agreed to be based on requested data units. This pricing does not apply in Foreca's new API products. For further information, please contact our sales.

Weather API is designed to be flexible in order to give application developer possibility to optimize queries to include only data that is used in the application. I.e. if application uses only short forecasts it is possible to request only short forecasts. Pricing is based on the requested data units. 

One data unit is:
  • one forecast time step for one location
  • one observation data for one location
  • one response to name search query
Hourly-forecast-1

Weather data queried for 8 time steps consumes 8 data units.

For example, query:

http://HOST/data?lon=24.97&lat=60.32&ftimes=2/1h&format=json/[YOUR_API_KEY]&tempunit=C&windunit=MS&tz=

The query above consumes 3 data units (1 observation + 2 forecast time steps).

For example, query:

http://HOST/data?lon=24.97&lat=60.32&ftimes=24/1h&format=json/[YOUR_API_KEY]&tempunit=C&windunit=MS&tz=

The query above consumes 25 data units (1 observation + 24 forecast time steps).

For example, query:

http://HOST/search?q=lond

The query above consumes 1 data unit.

Name search

One location name search response consumes 1 data unit.

For more information please contact us.