This document describes how to use TV 2 Vejrcenters weather API: VEJRET-API.
Get started instructions
- Select version and response format you wish to use (JSON or XML at the moment).
- Select the type of resource you want; Today forecast, Search, etc.
- Type in the parameters you wish to use (the ones in bold are required)
- Type the "app" name that has been provided to you.
- Type in an expire date and time. It has to be within one hour.
- If a signature is required, generate it from the give instructions.
- Select "Get url" or "Execute" to get the url/page with the response.
Example: I want to retrieve the data for the today resource with my "example_app_user" app account and have been provided the secret: "1234".
The URL I want is:
My query is "geonameid=2621942&app=example_app_user&expire=2010-11-01-16-30-00"
and md5(query+secret) = md5(geonameid=2621942&app=example_app_user&expire=2010-11-01-16-30-001234) is 023bb848256b06e18b26f603785d501d
The TV 2 NET Weather-API is based on the notion of Representational State Transter or REST (http://en.wikipedia.org/wiki/Representational_State_Transfer). All requests are made, using HTTP GET. The resulting response is either in JSON or XML format, with the appropriate HTTP status code.
Parameters and URL-structure
Parameters are specified as normal GET parameters, using & (ambersand) as parameter separator. It has to be URL-encoded.
- Integer: One or more occurrences of the number 0-9, possibly with plus or minus in front. (ex. http://vejret-api.tv2.dk/api/vi/forecast/today.json?lat=56&lon=12&app=...)
- String: We use a whitelist of allowed characters:
"a-zA-Z0-9ÀÁÂÃÇÈÊËÌÍÎÏÑÒÓÔÕÙÚÛÝßàáâãçéèêëìíîïñòóôõùúûýÿæøåÆØÅÉÄÖÅÜéäöåü" (ex. http://vejret-api.tv2.dk/api/vi/search/index.json?q=G%F6teborgs%20Botaniska%20Tr%E4dg%E5rd...)
- Float: An integer optionally followed by a dot (.) and one or more integers. Can be prefixed with plus or minus. (http://vejret-api.tv2.dk/api/vi/forecast/today.json?lat=-32&lon=12.3&app=...)
- Latitude/longitude: We use the decimal version of refering to a geographic coordinate. Fx.
40d 26' 47" N 79d 58' 36" W is refered to as "lat=40.446195" and "lon=-79.948862" (se more at http://en.wikipedia.org/wiki/Geographic_coordinate_conversion)
- Limitations: The values that you can call the services with are depending on the limitations of the Geographic coordinate system (latitude/longitude) and the finite number of GeoNames id's (please refer to http://www.geonames.org/).
Values for latitude must be within -90 and 90, longitude within -180 and 180, inclusive.
Errors and return values
- On success, the resulting data will be returned with the HTTP status code 200 OK. These data can be XML or JSON formatted, as requested in the URL.
- On error, the HTTP status code can be 400 Bad request or 403 Forbidden.
- If a request will return an empty result, it depends on the type of resource, what kind of response you get. Fx if you do a search for something that will result in zero results (http://vejret-api.tv2.dk/api/vi/search/index.xml?q=Country that does not exist&app=...), you will get an empty json or xml makes sense with a HTTP status code 200 OK. In another case, where fx weather for a geoname that doesnt exist is requested, the result is an error 400 Bad Request along with an explanation(http://vejret-api.tv2.dk/api/vi/forecast/today.xml?geonameid=2&app=...).
The version number of the API should be provided in the URL, fx. "http://vejret-api/api/v1/forecast/...".
We will in the period until versioning is implemented try to keep changes on a minumum, but in dialog with our users, we can make, hopefully only minor, changes to the Weather API.
- 2010-11-03 - Changes to instructions and layout.
- 2010-10-27 - New authentication is applied.
- 2010-10-27 - Weather symbols are now calculated for at 2 hour period always starting in an even hour, so that the symbol is repeated in the odd hour (they will alway be identical). If an odd hour is the starting hour (the current hour), the symbol will be calculated from data one hour behind and one forward.
- 2010-10-22 - We have moved the location of the symbol and wind icons to the same site as the rest of the api. This is due to an error with the direction of the wind arrows (they were reversed). Also notice, that when it is wind still, an empty string is returned for the direction. In this case, use the wind speed, which is 0 (zero) to get the correct icon.
- 2010-10-12 - Added GZIP encoding of content for clients that supports it.
- 2010-10-11 - Added a name attribute for the forecast xml views. This is either the day; "_dag" or night "_nat" name, based on sunrise and -set information.
- 2010-10-11 - Added. Api for getting weather symbol and wind images. The name and direction parameters are retrieved from the forecast service.
- 2010-10-07 - Removed URLs from the forecast feeds to reduce size. Icons will soon be available to request in separate resources. Sorry if this causes any inconvenience.
- 2010-10-06 - Added URLs to wind arrow images in two sizes for json and xml format.
- 2010-10-06 - Added URLs to symbol images in three sizes for both json and xml format.
- 2010-10-05 - Added version requirement to the url (for backwards compatibility urls without version numbers are still accepted, but it is encouraged to use the new urls).
- 2010-09-22 - Fixed problem with precipitation being shifted one hour. Places outside Europe (GFS) are now reported in 3 hour time periods.
- 2010-09-20 - Nearby resource
Added a "nearby" resource, that returns a toponym or list of toponyms in the viscinity of the given lat/lon position. The coordinates are rounded off to the nearest two decimals.
- 2010-09-17 - XML format
In the <meta><location> entities for all resources, <regionname>Region Hovedstaden</regionname> has been changed to <region code="17">Region Hovedstaden</region> to show the region code also. The json format is unchanged.
This service cannot be used without having obtained legal consent by TV 2 Danmark.
Back to the API overview