Tabular Weather API

Introduction

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

Request

Format

GET
URL request example
https://<baseURL>/weatherconditions/<version>/<regionCode>?key=<apiKey>

Example

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

Parameters

ParameterDescriptionRequiredExampleDefault
baseURLBase URL for calling TomTom services.Yesapi.tomtom.com-
versionThe version of the service to call.Yesv1-
regionCodeThe name of the product region. See the Region Coverage for supported regionCode values.Yesworld-
apiKeyAuthorization key for access to the API.Yes--

Headers

HeaderDescriptionRequiredExampleDefault
[Accept-Encoding]Requests that the response is compressed in the specified way. The service supports http compression if desired. Currently, only gzip is supported.Nogzip-
[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.NoSat, 29 Oct 1994 19:43:31 GMT-

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

CodeMeaning and possible causes
200OK
304Not 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.
401Unauthorized: The supplied API key is not valid for this request (or missing).
404Not 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.
500Internal Server Error: Oops.

Response Headers

HeaderDescriptionValues
Content-EncodingThe service supports http compression if desired. Currently, only gzip is supported.gzip
Content-TypeThe format of the served resource. The service always provides data in Protobuf (binary).application/x-protobuf
DateA 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"
EtagEntity-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

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:

AttributeProtobuf data typeDescription
creationTimeuint64The actual time in UTC when the content was created as a UNIX epoch.
lastUpdateTimeuint64The latest original publication time of the source data for the returned content in UTC as a UNIX epoch that caused any included information to change in comparison to before the respective source update.
sourcestringThe source of the original data used to create the returned content, usually the name of the 3rd-party provider.
numLocationsuint32The number of locations for which weather information is contained in the returned content (can be used for sequential parsing).

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:

AttributeProtobuf data typeDescription
iduint32A unique (and fixed) identifier that allows to refer to that particular location.
longitudedoubleThe geographical longitude of the location as a decimal value between -180 and 180.
latitudedoubleThe geographical latitude of the location as a decimal value between -90 and 90.
weatherInfoListsrepeated WeatherInfoListA list of WeatherInfoList messages. Each WeatherInfoList message will contain a separate list of WeatherInfo messages of a specific type.
namestringName of the location, typically the city, quarter, or admin area, etc.
countrystringThe ISO 3166-1 alpha-2 code of the location's country in capital letters, e.g. "DE".
timezonestringThe time zone string of the location according to the standard time zone database (also known as the Olson database), e.g. "Europe/Berlin".

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:

AttributeProtobuf data typeDescription
lastChangeTimeint64The latest original publication time of source data when information in this list was changed in UTC as a UNIX epoch.
typeInfoTypeThe type of WeatherInfo messages contained in this list. The initialized fields of the included WeatherInfo messages depend on this InfoType.
intervalInHoursuint32Interval in hours between the single WeatherInfo messages contained in this list. Only set if type == PERIOD (see above).
weatherInfosrepeated WeatherInfoA list of WeatherInfo messages of the specified type (& potentially interval) summarizing weather conditions at different times.
The InfoType Enum

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

ValueDescription
DAYEach WeatherInfo in a WeatherInfoList of this type represents a measurement or forecast for a single day.
PERIODEach WeatherInfo in a WeatherInfoList of this type represents a measurement or forecast for a certain sub-daily period (defined by the intervalInHours of the respective WeatherInfoList), e.g. for a single hour of a day.

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:

AttributeProtobuf data typeProvided if type==DAYProvided if type==PERIODDescription
datestring(+)(-)The date to which this measurement/forecast applies in local time (of the location in question) as an ISO-8601-compliant date string of the Form YYYY-MM-DD (Year-Month-Day), e.g. "2015-06-09" (see also here).
dateTimestring(-)(+)The time to which this measurement/forecast applies 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". Note that the time zone specifier TZD is always "Z" since the time is always given in UTC (see also here). Note: If separate start- & end-times are required for interpretation, this time can be interpreted as the start time, while the end time is derived by taking this time plus the intervalInHours specified in the containing WeatherInfoList.
dateTimeLocalstring(-)(+)The time to which this measurement/forecast applies in local time of the location as an ISO-8601-compliant date-time string of the form YYYY-MM-DDThh:mm:ss (Year-Month-DayTHour:Minute:Second), e.g. "2015-06-09T12:30:00". Note that the time zone specifier is always omitted (see also here). Note: If separate start- & end-times are required for interpretation, this time can be interpreted as the start time, while the end time is derived by taking this time plus the intervalInHours specified in the containing WeatherInfoList.
temperaturesint32(-)(+)The actual ambient temperature in °C with 1° precision.
feelsLikesint32(-)(+)The perceived outdoor temperature in °C with 1° precision.
minTemperaturesint32(+)(-)Minimum temperature encountered during the covered interval (day) in °C with 1° precision.
maxTemperaturesint32(+)(-)Maximum temperature encountered during the covered interval (day) in °C with 1° precision.
weatherCodestring(+)(+)9-character string in a well-defined format (see Weather Codes) providing a short description of the overall weather, e.g. for determining appropriate icons for display.
windSpeeddouble(+)(+)Wind speed in m/s as positive decimal value with 0.1 m/s precision.
windDirectionWindDirection(+)(+)Wind direction (where the wind comes from) as one of 16 compass directions represented as corresponding values of the WindDirection enum.
sunProbabilityuint32(+)(+)Probability for sunshine during the covered interval in percent with 1 % precision (between 0 and 100).
precipitationProbabilityuint32(+)(+)Probability for precipitation during the covered interval in percent with 1 % precision (between 0 and 100).
thunderProbabilityuint32(+)(+)Probability for thunderstorm during the covered interval in percent with 1 % precision (between 0 and 100).
precipitationdouble(+)(+)Precipitation sum in mm as a positive decimal value with 0.1 mm precision accumulated over the covered interval.
pressureuint32(-)(+)Barometric pressure in hPa with 1hPa precision.
relativeHumidityuint32(-)(+)Ambient relative humidity in percent with 1 % precision (between 0 and 100).
uvIndexuint32(+)(+)UV index according to the standard scale from 0 - infinity in integer steps.
visibilityuint32(-)(-)Visibility in km with 1km precision.
sunRisestring(+)(-)Time of the sunrise in local time in format hh:mm:ss.
sunSetstring(+)(-)Time of the sunset in local time in format hh:mm:ss.
moonRisestring(+)(-)Time of the moonrise in local time in format hh:mm:ss.
moonSetstring(+)(-)Time of the moonset in local time in format hh:mm:ss.
moonPhaseuint32(+)(-)Moon phase in degrees between 0° and 360° with 1° precision, where 0° corresponds to new moon and 180° correspond to full moon.
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:

Code <T>Time of day
DDay
NNight
Code <XX>Sky/cloud status
CSClear sky
MIMist
FOFog
SASand/dust storm
HZHazy
SCSome clouds
PCPartly cloudy
CLCloudy
OCOvercast
STStorm
CYCyclone
Code <PPP>Precipitation type
DRIDrizzle
RAIRain
RASRain Showers
RAT(Rain &) Thunderstorm
SNOSnow
SNSSnow showers
SNTSnow & thunderstorm
SLESleet
SLSSleet showers
SLTSleet & thunderstorm
ICRIce rain
HAIHail
HASHail showers
HATHail & thunderstorm
Code <L>Precipitation level
1Light
2Moderate
3Heavy

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":

ValueDescription
VARVariable/changing wind directions.
NWind from North.
NNEWind from North-North-East.
NEWind from North-East.
ENEWind from North-East.
EWind from East.
ESEWind from East-South-East.
SEWind from South-East.
SSEWind from South-South-East.
SWind from South.
SSWWind from South-South-West.
SWWind from South-West.
WSWWind from West-South-West.
WWind from West.
WNWWind from West-North-West.
NWWind from North-West.
NNWWind from North-North-West.
UNKWind direction 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

RegionRegionCode
Worldworld