Advanced Weather API
Introduction
The Advanced Weather API delivers spatio-temporally resolved, real-time weather information. The provided content comprises polygonal information about radar-based current precipitation, precipitation forecasts in different time slices, and local warnings about safety-relevant weather events for the present and future.
Request
Format
https://<baseURL>/weatherpolygons/<version>/<regionCode>?key=<apiKey>
Example
https://api.tomtom.com/weatherpolygons/v1/europe?key=<apiKey>
Parameters
Parameter | Description | Required | Example | Default |
---|---|---|---|---|
baseURL | Base URL for calling TomTom services. | Yes | api.tomtom.com | - |
version | The version of the service to call. | Yes | v1 | - |
regionCode | The name of the product region. See the Region Coverage for supported regionCode values. | Yes | europe | - |
apiKey | Authorization key for access to the API. | Yes | - | - |
Headers
Header | Description | Required | Example | Default |
---|---|---|---|---|
[Accept-Encoding] | Requests that the response is compressed in the specified way. The fuelprices service supports http compression if desired. Currently, only gzip is supported. | No | gzip | - |
[If-None-Match] | Provides the entity-tag (E-tag) of the requested resource as last received by the client. Allows efficient updates of cached information with a minimum amount of transaction overhead: The service can respond with a 304 (not modified) message if the data that would otherwise be provided has the same entity tag. | No | "4f3d2af4" | - |
[If-Modified-Since] | Specifies the time stamp of the last actual update of the requested resource received by the client. Allows the service to respond with a 304 (not modified) message if no newer data is available. | No | Sat, 29 Oct 1994 19:43:31 GMT | - |
Content
Plain GET messages must be used to create requests.
Response
The weather polygons are served in GeoJSON format. Root level of the response is a single FeatureCollection holding all weather polygons.
Every weather polygon is represented by a Feature, having a unique id and a set of properties. The enclosing FeatureCollection has an additional set of properties holding metadata such as the creation time of the response.
Response Codes
Code | Meaning and possible causes |
---|---|
200 | OK |
304 | Not Modified: The requested content did not change since the last request, as indicated by the value(s) of the If-Modified-Since and/or or If-None-Match http header fields. |
401 | Unauthorized: The supplied API key is not valid for this request (or missing). |
404 | Not Found: The specified path was not valid. At least one of the path parameters was omitted or not entered correctly. If an unsupported or invalid country code was specified, the included response message provides a list of valid available country codes. |
500 | Internal Server Error: Oops. |
Response Headers
Header | Description | Values |
---|---|---|
Content-Encoding | The service supports http compression if desired. Currently, only gzip is supported. | gzip |
Content-Type | The format of the served resource. The service always provides data in GeoJSON. | application/json |
Date | A timestamp specifying when the response was sent. Can be used by the client in the If-Modified-Since header field of subsequent requests in order to optimize the update procedure. | Example: "Wed, 20 Jul 2016 14:23:59 GMT" |
Etag | Entity-tag of the served resource. Can be used by the client in the If-None-Match header field of subsequent requests in order to optimize the update procedure. | Example: "4f3d2af4" |
Example Response
{
"type" : "FeatureCollection",
"features" : [ {
"type" : "Feature",
"id" : "0",
"properties" : {
"uniqueId" : "7ffffff",
"category" : "precip",
"type" : "rain",
"level" : 0.86,
"area" : 80.968,
"children" : [ ],
"parent" : "1",
"countries" : [ "ESP" ]
},
"geometry" : {
"type" : "Polygon",
"coordinates" : [ [ [ -3.774, 37.513 ], [ -3.68, 37.568 ], [ -3.67, 37.628 ], [ -3.695, 37.653 ], [ -3.759, 37.608 ], [ -3.779, 37.518 ] ] ]
},
"bbox" : [ -3.779, 37.513, -3.67, 37.653 ]
} ],
"properties" : {
"forecastOffset" : 15,
"creationTime" : "2015-10-13T11:14:53.70Z",
"timeStamp" : "2015-10-13T11:14:53.70Z",
"rootTimeStamp" : "2015-10-13T11:14:53.70Z"
}
}
Response Structure
FeatureCollection properties
Property | JSON data type | Description |
---|---|---|
forecastOffset | Number | The forecast horizon of the weather polygon in minutes. A zero stands for the present time. |
creationTime | String | Time of the request in UTC as an ISO-8601-compliant date-time string of the form YYYY-MM-DDThh:mm:ssTZD (Year-Month-DayTHour:Minute:SecondTZD), e.g. "2015-06-09T10:00:00Z". |
timeStamp | String | Time of which the weather polygons refer to (may be in the future) in UTC as an ISO-8601-compliant date-time string of the form YYYY-MM-DDThh:mm:ssTZD (Year-Month-DayTHour:Minute:SecondTZD), e.g. "2015-06-09T10:00:00Z". |
rootTimeStamp | String | Time at which the weather polygons were measured/predicted in UTC as an ISO-8601-compliant date-time string of the form YYYY-MM-DDThh:mm:ssTZD (Year-Month-DayTHour:Minute:SecondTZD), e.g. "2015-06-09T10:00:00Z". |
Feature properties
Property | JSON data type | Description |
---|---|---|
uniqueId | String | A unique and stable id of the current weather polygon. |
category | String | The category of the weather polygon, e.g. "precip" (see section Category Values). |
type | String | The type of the weather polygon, e.g. "rain" (see section Type Values). |
level | Number | The level of the weather atom, i.e. a numeric value describing its magnitude. |
area | Number | The area of the weather polygon in square kilometers (km²). |
children | Array[String] | A list of Feature-Ids that represent polygons of the same category and type with the next higher level which lie inside the weather polygon. An empty array means no children. |
parent | String | A single Feature-Id that represents the polygon of the next lower level which contains the weather polygon. An empty string means no parent. |
countries | Array[String] | The list of countries, given as ISO 3166-1 alpha-3 country codes that intersect with the weather polygon. |
Note: The Feature-Id is given by the id of the Feature object, see also the Feature specification.
Category values
Category | Description |
---|---|
precip | Regional information about the precipitation in the form of regions with different precipitation levels. |
warning | Regional information about severe-weather conditions. |
Type values
The type values are depending on the category value.
Type values for category "precip"
- rain
- snow
- mixed
- hail
Type values for category "warning"
- storm
- thunderstorm
- heavyrain
- snowfall
- frost
- sleet
- heat
- slipperiness
- forestfire
- groundfrost
- fog
- freezingrain
- cyclone
- blizzard
Level values
The level values are depending on the category.
Level values for category "precip"
The value of a level specifies the precipitation intensity in mm/h.
Level values for category "warning"
Value | Description |
---|---|
0 | moderate |
1 | heavy |
2 | extreme |
Usage and Freshness
The weather polygons are updated regularly, typical frequencies being in the order of 15 minutes. Using the support for If-None-Match or If-Modified-Since header fields, higher update request frequencies can be used to minimize the delay between updated information being available in the server and being received by the client.
Region Coverage
Region | RegionCode |
---|---|
Europe | europe |
USA | usa |