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 parameters

Description

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.

Header

Description

Accept-Encoding

Requests 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-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.


Value: Example: 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.


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

Code

Meaning & 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

Content-Encoding

The service supports http compression if desired. Currently, only gzip is supported.


Value: gzip

Content-Type

The format of the served resource. The service always provides data in Protobuf (binary).


Value: application/x-protobuf

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.


Value: 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.


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:

Attribute

Description

creationTime

The actual time in UTC when the content was created as a UNIX epoch.


Protobuf data type: uint64

lastUpdateTime

The 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

source

The source of the original data used to create the returned content, usually the name of the 3rd-party provider.


Protobuf data type: string

numLocations

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

Attribute

Description

id

A unique (and fixed) identifier that refers to that particular location.


Protobuf data type: uint32

longitude

The geographical longitude of the location as a decimal value between -180 and 180.


Protobuf data type: double

latitude

The geographical latitude of the location as a decimal value between -90 and 90.


Protobuf data type: double

weatherInfoLists

A list of WeatherInfoList messages. Each WeatherInfoList message will contain a separate list of WeatherInfo messages of a specific type.


Protobuf data type: repeated WeatherInfoList

name

Name of the location, typically the city, quarter, or admin area, etc.


Protobuf data type: string

country

The ISO 3166-1 alpha-2 code of the location's country in capital letters, e.g., "DE".


Protobuf data type: string

timezone

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

Attribute

Description

lastChangeTime

The latest original publication time of source data when information in this list was changed in UTC as a UNIX epoch.


Protobuf data type: int64

type

The type of WeatherInfo messages contained in this list. The initialized fields of the included WeatherInfo messages depend on this InfoType.
Protobuf data type: InfoType

intervalInHours

Interval in hours between the single WeatherInfo messages contained in this list. Only set if type == PERIOD (see above).


Protobuf data type: uint32

weatherInfos

A 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.

Value

Description

DAY

Each WeatherInfo in a WeatherInfoList of this type represents a measurement or forecast for a single day.

PERIOD

Each 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

D

Day

N

Night

Code <XX>

Sky/cloud status

CS

Clear sky

MI

Mist

FO

Fog

SA

Sand/dust storm

HZ

Hazy

SC

Some clouds

PC

Partly cloudy

CL

Cloudy

OC

Overcast

ST

Storm

CY

Cyclone

Code <PPP>

Precipitation type

DRI

Drizzle

RAI

Rain

RAS

Rain Showers

RAT

(Rain &) Thunderstorm

SNO

Snow

SNS

Snow showers

SNT

Snow & thunderstorm

SLE

Sleet

SLS

Sleet showers

SLT

Sleet & thunderstorm

ICR

Ice rain

HAI

Hail

HAS

Hail showers

HAT

Hail & thunderstorm

Code <L>

Precipitation level

1

Light

2

Moderate

3

Heavy

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

Value

Description

VAR

Variable/changing wind directions.

N

Wind from North.

NNE

Wind from North-North-East.

NE

Wind from North-East.

ENE

Wind from North-East.

E

Wind from East.

ESE

Wind from East-South-East.

SE

Wind from South-East.

SSE

Wind from South-South-East.

S

Wind from South.

SSW

Wind from South-South-West.

SW

Wind from South-West.

WSW

Wind from West-South-West.

W

Wind from West.

WNW

Wind from West-North-West.

NW

Wind from North-West.

NNW

Wind from North-North-West.

UNK

Wind 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

Region

RegionCode

World

world