Tabular Weather API

Introduction

The Tabular Weather API delivers current and predicted location-based weather conditions in different temporal resolutions.

Request

Format

https://<baseURL>/weatherconditions/<version>/<regionCode>?key=<apiKey>

Example

https://api.tomtom.com/weatherconditions/v1/world?key=<apiKey>

Parameters

Headers

Content

Plain GET messages must be used to create requests.

Response

The weather conditions are served in a Protobuf format according to this schema. Although the structure defined in the schema allows to wrap the provided content for all known locations and supported InfoTypes into a single TabularWeather message, the binary content delivered by this feed follows a different convention: On root level, the content of a response contains exactly one MetaData message and a list of Location messages (in order). Each Location message can contain multiple messages of type WeatherInfoList which each contain multiple WeatherInfo messages of a specific InfoType, i.e. DAY or PERIOD.

Thus, for parsing the data: 1. Parse a single MetaData message from the binary input stream using MetaData.parseDelimitedFrom(...) 2. Infer the number n of Location messages remaining in the binary stream from the numLocations attribute of the parsed MetaData message 3. Repeatedly call Location.parseDelimitedFrom(...) for n times. After that, the end of the data should be reached.

This way of transferring the data has the advantage that the binary data for the provided locations does not have to be transformed to internal Protobuf message data structures for all locations at the same time (which would require a significant amount of memory due to the object overhead). Instead, only a single Location message data structure has to be kept in memory and can be entirely processed (translated to/from internal data structures) before the next one is parsed/written.

Response Codes

Response Headers

Example Response

The following is the textual representation of an exemplary response content (in Protobuf text format) . Note that any real response content will be encoded in Protobuf binary format which is not that human-readable.

1metaData {
2  creationTime: 1429007400
3  lastUpdateTime: 1429007400
4  source: "TomTom"
5  numLocations: 2
6}
7locations {
8  id: 102804646
9  longitude: 13.62
10  latitude: 52.37
11  weatherInfoLists {
12    lastChangeTime: 1423567860
13    type: DAY
14    weatherInfos {
15      date: "2015-04-14"
16      minTemperature: 2
17      maxTemperature: 6
18      weatherCode: "D_CL_RAI1"
19      windSpeed: 5.2
20      windDirection: NW
21      sunProbability: 3
22      precipitationProbability: 55
23      thunderProbability: 0
24      precipitation: 0.5
25      uvIndex: 0
26      sunRise: "07:32:00"
27      sunSet: "17:08:00"
28      moonSet: "09:48:00"
29      moonPhase: 250
30    }
31    weatherInfos {
32      date: "2015-04-15"
33      minTemperature: -2
34      maxTemperature: 5
35      weatherCode: "D_OC_____"
36      windSpeed: 2.6
37      windDirection: W
38      sunProbability: 0
39      precipitationProbability: 18
40      thunderProbability: 0
41      precipitation: 0.4
42      uvIndex: 1
43      sunRise: "07:30:00"
44      sunSet: "17:10:00"
45      moonRise: "00:13:00"
46      moonSet: "10:15:00"
47      moonPhase: 260
48    }
49  }
50  weatherInfoLists {
51    lastChangeTime: 1429007400
52    type: PERIOD
53    intervalInHours: 1
54    weatherInfos {
55      dateTime: "2015-04-14T10:00:00Z"
56      dateTimeLocal: "2015-04-14T12:00:00"
57      temperature: 12
58      feelsLike: 12
59      weatherCode: "D_CL_____"
60      windSpeed: 4.3
61      windDirection: W
62      sunProbability: 27
63      precipitationProbability: 2
64      thunderProbability: 0
65      precipitation: 0.0
66      pressure: 1026
67      relativeHumidity: 53
68      uvIndex: 4
69    }
70    weatherInfos {
71      dateTime: "2015-04-14T11:00:00Z"
72      dateTimeLocal: "2015-04-14T13:00:00"
73      temperature: 13
74      feelsLike: 13
75      weatherCode: "D_CL_____"
76      windSpeed: 4.6
77      windDirection: W
78      sunProbability: 26
79      precipitationProbability: 2
80      thunderProbability: 0
81      precipitation: 0.0
82      pressure: 1025
83      relativeHumidity: 48
84      uvIndex: 4
85    }
86  }
87  name: "Zeuthen"
88  country: "DE"
89  timeZone: "Europe/Berlin"
90}
91locations {
92  id: 102810815
93  longitude: 13.73
94  latitude: 52.63
95  weatherInfoLists {
96    lastChangeTime: 1423567860
97    type: DAY
98    weatherInfos {
99      date: "2015-04-14"
100      minTemperature: 1
101      maxTemperature: 6
102      weatherCode: "D_OC_RAI1"
103      windSpeed: 5.3
104      windDirection: NW
105      sunProbability: 1
106      precipitationProbability: 50
107      thunderProbability: 0
108      precipitation: 0.4
109      uvIndex: 0
110      sunRise: "07:32:00"
111      sunSet: "17:07:00"
112      moonSet: "09:47:00"
113      moonPhase: 250
114    }
115    weatherInfos {
116      date: "2015-04-15"
117      minTemperature: -2
118      maxTemperature: 3
119      weatherCode: "D_CL_____"
120      windSpeed: 2.7
121      windDirection: W
122      sunProbability: 2
123      precipitationProbability: 17
124      thunderProbability: 0
125      precipitation: 0.3
126      uvIndex: 1
127      sunRise: "07:30:00"
128      sunSet: "17:09:00"
129      moonRise: "00:13:00"
130      moonSet: "10:14:00"
131      moonPhase: 260
132    }
133  }
134  weatherInfoLists {
135    lastChangeTime: 1429007400
136    type: PERIOD
137    intervalInHours: 1
138    weatherInfos {
139      dateTime: "2015-04-14T10:00:00Z"
140      dateTimeLocal: "2015-04-14T12:00:00"
141      temperature: 10
142      feelsLike: 7
143      weatherCode: "D_CL_____"
144      windSpeed: 4.5
145      windDirection: W
146      sunProbability: 27
147      precipitationProbability: 2
148      thunderProbability: 0
149      precipitation: 0.0
150      pressure: 1026
151      relativeHumidity: 55
152      uvIndex: 4
153    }
154    weatherInfos {
155      dateTime: "2015-04-14T11:00:00Z"
156      dateTimeLocal: "2015-04-14T13:00:00"
157      temperature: 11
158      feelsLike: 11
159      weatherCode: "D_CL_____"
160      windSpeed: 4.9
161      windDirection: W
162      sunProbability: 24
163      precipitationProbability: 3
164      thunderProbability: 0
165      precipitation: 0.0
166      pressure: 1025
167      relativeHumidity: 49
168      uvIndex: 4
169    }
170  }
171  name: "Werneuchen"
172  country: "DE"
173  timeZone: "Europe/Berlin"
174}

Response Structure

The MetaData Message

A MetaData message provides the following information as attributes:

The Location Message

A Location message comprises all provided weather data for a single location plus additional meta information about the location itself. The following attributes are provided:

The WeatherInfoList Message

A WeatherInfoList message is a container for a list of WeatherInfo messages of the same type & interval, providing additional information about the common type & interval and the last (source publication-) time the included information was updated. The following attributes are provided:

The InfoType Enum

The InfoType enum provides all possible values for the type parameter of a WeatherInfoList.

The WeatherInfo Message

A WeatherInfo message summarizes weather parameters for a certain point in time for the location in question. All potentially provided weather parameter attributes (depending on the type of the containing WeatherInfoList) are specified & described in the table below:

Weather Codes

The weather codes are defined as a 9-character string with the following basic structure:

<T>_<XX>_<PPP><L>

The single parts have the following meaning:

• <T> - single-letter time-of-day specifier: "D" or "N" for day and night respectively
• <XX> - 2-letter sky/cloud status specifier
• <PPP> - 3-letter precipitation type specifier
• <L> - 1-digit precipitation level specifier

Valid Code Values

The following tables summarize the allowed values for the single parts and their interpretations:

Combination Rules

• Both day and night codes can be combined with any other (valid) combination of the other parts.
• The cloud/sky status codes PC, CL, OC, ST and CY can be combined with all precipitation codes. All other codes are followed by 5 underscores to fill up the entire code to 9 characters.
• If no precipitation is present, the weather code is also filled up with 5 underscores after the cloud/sky status.
• If precipitation is present, both type and level must be specified.
• All supported precipitation types can be combined with any valid value for the precipitation level.

Examples

The following codes are valid:

• D_CS_____ - Day, clear sky - Berlin in summer
• D_OC_RAI2 - Day, overcast, moderate rain - Bielefeld in summer
• N_PC_RAT1 - Night, partly cloudy, light thunderstorm - the occasional summer thunderstorm
• D_OC_____ - Day, overcast - lucky day for Bielefeld
• D_CY_SNO3 - Day, cyclone, heavy snow - blizzard
• N_PC_SNO1 - Night, partly cloudy, light snow - white Christmas

The WindDirection Enum

The WindDirection enum provides all possible values for the windDirection parameter of a WeatherInfo. It defines 16 equally distributed compass directions plus one value for "variable" and one value for "unknown":

Usage and Freshness

The weather conditions are updated regularly, typical frequencies being in the order of 1 hour. 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