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.
Current conditions: data from the closest relevant weather observation station which has recently reported data
Detailed short forecasts: contain intra-day details for several time steps
Daily overview forecasts: contain summary data for one day
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.
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.
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.
Forecast for the next two days
Forecast for the next two hours
It is possible to request for example hourly and daily forecast in one API call. The following request
is responded with hourly forecast for the next 24 hours and daily forecast for the next 5 days.
Search a location from Foreca location database, for example with term "lond":
Pick the location from the result list and use its "id" to request weather data for the location:
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:
Optional query parameters:
(*) using ftimes query parameter to specify first timestep
There are two formats:
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:
Please note that the time zone calculation for local time is approximate.
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.
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:
Weather data queried for 8 time steps consumes 8 data units.
For example, query:
The query above consumes 3 data units (1 observation + 2 forecast time steps).
For example, query:
The query above consumes 25 data units (1 observation + 24 forecast time steps).
For example, query:
The query above consumes 1 data unit.
One location name search response consumes 1 data unit.
For more information, please fill out the form.