Tabular Weather API

Service version: v1
Last edit: 2022.08.25

Purpose

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

Request data

HTTPS method: GET

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

Plain GET messages must be used to create requests.

URL format

GET
URL Request format
https://{baseURL}/weatherconditions/{versionNumber}/{regionCode}?key={Your_API_Key}

URL example

GET
URL Request example
https://api.tomtom.com/weatherconditions/v1/world?key={Your_API_Key}

curl command example

GET
curl command request example
curl 'https://api.tomtom.com/weatherconditions/v1/world?key={Your_API_Key}'

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.

Note: There are no optional parameters in this endpoint.

Required parametersDescription
baseURL
string
Base URL for calling TomTom services.
Value: api.tomtom.com
versionNumber
string
The version of the service to call.
Value: v1
regionCode
string
The name of the product region. See the Region Coverage for supported regionCode values.
Value: world
key
string
Authorization key for access to the API.
Value: Your valid API Key.

Request headers

Note: There are no required headers in this endpoint - all are optional.

HeaderDescription
Accept-EncodingRequests that the response is compressed in the specified way. The service supports HTTP compression if desired. Currently, only gzip is supported.
Value: gzip
If-None-MatchProvides 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.
Value: Example: 4f3d2af4
If-Modified-SinceSpecifies 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.
Value: Example: Sat, 29 Oct 1994 19:43:31 GMT

Response data

The weather conditions are served in a Protobuf format according to this schema. Although the structure defined in the schema allows wrapping 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 the type WeatherInfoList each containing 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 & 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

HeaderDescription
Content-EncodingThe service supports http compression if desired. Currently, only gzip is supported.
Value: gzip
Content-TypeThe format of the served resource. The service always provides data in Protobuf (binary).
Value: 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.
Value: 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.
Value: Example: 4f3d2af4

Example response

The following code example 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:

AttributeDescription
creationTimeThe actual time in UTC when the content was created as a UNIX epoch.
Protobuf data type: uint64
lastUpdateTimeThe 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.
Protobuf data type: uint64
sourceThe source of the original data used to create the returned content, usually the name of the 3rd-party provider.
Protobuf data type: string
numLocationsThe number of locations for which weather information is contained in the returned content (can be used for sequential parsing).
Protobuf data type: uint32

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:

AttributeDescription
idA unique (and fixed) identifier that refers to that particular location.
Protobuf data type: uint32
longitudeThe geographical longitude of the location as a decimal value between -180 and 180.
Protobuf data type: double
latitudeThe geographical latitude of the location as a decimal value between -90 and 90.
Protobuf data type: double
weatherInfoListsA list of WeatherInfoList messages. Each WeatherInfoList message will contain a separate list of WeatherInfo messages of a specific type.
Protobuf data type: repeated WeatherInfoList
nameName of the location, typically the city, quarter, or admin area, etc.
Protobuf data type: string
countryThe ISO 3166-1 alpha-2 code of the location's country in capital letters, e.g., "DE".
Protobuf data type: string
timezoneThe time zone string of the location according to the standard time zone database (also known as the Olson database), e.g., "Europe/Berlin".
Protobuf data type: string

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:

AttributeDescription
lastChangeTimeThe latest original publication time of source data when information in this list was changed in UTC as a UNIX epoch.
Protobuf data type: int64
typeThe type of WeatherInfo messages contained in this list. The initialized fields of the included WeatherInfo messages depend on this InfoType.
Protobuf data type: InfoType
intervalInHoursInterval in hours between the single WeatherInfo messages contained in this list. Only set if type == PERIOD (see above).
Protobuf data type: uint32
weatherInfosA list of WeatherInfo messages of the specified type (& potentially interval) summarizing weather conditions at different times.
Protobuf data type: repeated WeatherInfo

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 following table.

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