Welcome to the WeatherAPI

Introduction

The weather data API is loosely based on the REST style of web service programming. All queries are done via HTTP GET, and the results are returned as either XML or the binary format appropriate for the data, as documented by each module.

Available products:

Interface documentation

Read our F.A.Q

Data restrictions

We have a few cases with data that are not freely available. This is marked in the documentation for each product, under the heading Restrictions.

Versions

We recommend reading the section about error handling.

Since a product can change its API, there is a version number part of every product URL. If you try to use a product version which is deprecated, you will get the data you expect, but with the HTTP status code 203 Non-Authoritative Information. It is important for client software to accept 203-responses, but you probably want to se up some checks or alarms on the return codes.

After a period of being deprecated, versions will be end-of-lifed. When this happens, asking for these versions will be treated as an error, like described in the section about errors. See the changelog for each particular product to find information about the end-of-life date for a deprecated version. You can also keep yourself up to date on changes in our products by following our changelog rss feed. See the Actions section below for the specific url.

The purpose of the version number scheme is to provide a stable interface for devices and software to use, since we are able to handle the changes we can't avoid making in a graceful manner. The goal is not to change the interface often or indeed at all.

Actions

Errors and return values

On success, the appropriate data will be returned with the HTTP status code 200 OK. These data may be XML or some other format (like PNG, GIF or JPEG), but as long as the status code indicates success, they should be there.

On error, the HTTP status code 400 Bad request is returned along with an error message formatted as HTML. Other 4XX-codes may be added in the future to differentiate errors. In other words, a client expecting binary data (like images) should not attempt to parse, decode or use the data returned to it if it got a 4XX code.

If the request is OK as such, but the product handler does not have any data to offer, you will normally receive a 4XX code. Note, however, that there are cases where empty response data (ie. an XML document with no real content) makes sense. In these cases, it can be impossible for the WeatherAPI to see if the input data it gets from the weather models is empty because of an error, or because it really should be empty.

Parameters and data type definitions

Parameters are specified as normal GET parameters, using ; (semicolon) as parameter separator as recommended by W3C.

This is the complete set of data types accepted by the WeatherAPI modules. The documentation for each product will refer to these data types. Note that the only character set allowed in the input parameters/URLs is UTF-8.

Data compression

Data of MIME types text/html text/plain text/xml are gzip encoded if the client requests this in the HTTP headers.