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
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 | world | - |
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 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 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
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 Protobuf (binary). | 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. | 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
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: 14290074003 lastUpdateTime: 14290074004 source: "TomTom"5 numLocations: 26}7locations {8 id: 1028046469 longitude: 13.6210 latitude: 52.3711 weatherInfoLists {12 lastChangeTime: 142356786013 type: DAY14 weatherInfos {15 date: "2015-04-14"16 minTemperature: 217 maxTemperature: 618 weatherCode: "D_CL_RAI1"19 windSpeed: 5.220 windDirection: NW21 sunProbability: 322 precipitationProbability: 5523 thunderProbability: 024 precipitation: 0.525 uvIndex: 026 sunRise: "07:32:00"27 sunSet: "17:08:00"28 moonSet: "09:48:00"29 moonPhase: 25030 }31 weatherInfos {32 date: "2015-04-15"33 minTemperature: -234 maxTemperature: 535 weatherCode: "D_OC_____"36 windSpeed: 2.637 windDirection: W38 sunProbability: 039 precipitationProbability: 1840 thunderProbability: 041 precipitation: 0.442 uvIndex: 143 sunRise: "07:30:00"44 sunSet: "17:10:00"45 moonRise: "00:13:00"46 moonSet: "10:15:00"47 moonPhase: 26048 }49 }50 weatherInfoLists {51 lastChangeTime: 142900740052 type: PERIOD53 intervalInHours: 154 weatherInfos {55 dateTime: "2015-04-14T10:00:00Z"56 dateTimeLocal: "2015-04-14T12:00:00"57 temperature: 1258 feelsLike: 1259 weatherCode: "D_CL_____"60 windSpeed: 4.361 windDirection: W62 sunProbability: 2763 precipitationProbability: 264 thunderProbability: 065 precipitation: 0.066 pressure: 102667 relativeHumidity: 5368 uvIndex: 469 }70 weatherInfos {71 dateTime: "2015-04-14T11:00:00Z"72 dateTimeLocal: "2015-04-14T13:00:00"73 temperature: 1374 feelsLike: 1375 weatherCode: "D_CL_____"76 windSpeed: 4.677 windDirection: W78 sunProbability: 2679 precipitationProbability: 280 thunderProbability: 081 precipitation: 0.082 pressure: 102583 relativeHumidity: 4884 uvIndex: 485 }86 }87 name: "Zeuthen"88 country: "DE"89 timeZone: "Europe/Berlin"90}91locations {92 id: 10281081593 longitude: 13.7394 latitude: 52.6395 weatherInfoLists {96 lastChangeTime: 142356786097 type: DAY98 weatherInfos {99 date: "2015-04-14"100 minTemperature: 1101 maxTemperature: 6102 weatherCode: "D_OC_RAI1"103 windSpeed: 5.3104 windDirection: NW105 sunProbability: 1106 precipitationProbability: 50107 thunderProbability: 0108 precipitation: 0.4109 uvIndex: 0110 sunRise: "07:32:00"111 sunSet: "17:07:00"112 moonSet: "09:47:00"113 moonPhase: 250114 }115 weatherInfos {116 date: "2015-04-15"117 minTemperature: -2118 maxTemperature: 3119 weatherCode: "D_CL_____"120 windSpeed: 2.7121 windDirection: W122 sunProbability: 2123 precipitationProbability: 17124 thunderProbability: 0125 precipitation: 0.3126 uvIndex: 1127 sunRise: "07:30:00"128 sunSet: "17:09:00"129 moonRise: "00:13:00"130 moonSet: "10:14:00"131 moonPhase: 260132 }133 }134 weatherInfoLists {135 lastChangeTime: 1429007400136 type: PERIOD137 intervalInHours: 1138 weatherInfos {139 dateTime: "2015-04-14T10:00:00Z"140 dateTimeLocal: "2015-04-14T12:00:00"141 temperature: 10142 feelsLike: 7143 weatherCode: "D_CL_____"144 windSpeed: 4.5145 windDirection: W146 sunProbability: 27147 precipitationProbability: 2148 thunderProbability: 0149 precipitation: 0.0150 pressure: 1026151 relativeHumidity: 55152 uvIndex: 4153 }154 weatherInfos {155 dateTime: "2015-04-14T11:00:00Z"156 dateTimeLocal: "2015-04-14T13:00:00"157 temperature: 11158 feelsLike: 11159 weatherCode: "D_CL_____"160 windSpeed: 4.9161 windDirection: W162 sunProbability: 24163 precipitationProbability: 3164 thunderProbability: 0165 precipitation: 0.0166 pressure: 1025167 relativeHumidity: 49168 uvIndex: 4169 }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 | Protobuf data type | Description |
creationTime | uint64 | The actual time in UTC when the content was created as a UNIX epoch. |
lastUpdateTime | uint64 | 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. |
source | string | The source of the original data used to create the returned content, usually the name of the 3rd-party provider. |
numLocations | uint32 | The 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:
Attribute | Protobuf data type | Description |
id | uint32 | A unique (and fixed) identifier that allows to refer to that particular location. |
longitude | double | The geographical longitude of the location as a decimal value between -180 and 180. |
latitude | double | The geographical latitude of the location as a decimal value between -90 and 90. |
weatherInfoLists | repeated WeatherInfoList | A list of WeatherInfoList messages. Each WeatherInfoList message will contain a separate list of WeatherInfo messages of a specific type. |
name | string | Name of the location, typically the city, quarter, or admin area, etc. |
country | string | The ISO 3166-1 alpha-2 code of the location's country in capital letters, e.g. "DE". |
timezone | string | The 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:
Attribute | Protobuf data type | Description |
lastChangeTime | int64 | The latest original publication time of source data when information in this list was changed in UTC as a UNIX epoch. |
type | InfoType | The type of WeatherInfo messages contained in this list. The initialized fields of the included WeatherInfo messages depend on this InfoType. |
intervalInHours | uint32 | Interval in hours between the single WeatherInfo messages contained in this list. Only set if type == PERIOD (see above). |
weatherInfos | repeated WeatherInfo | A 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.
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 table below:
Attribute | Protobuf data type | Provided if type==DAY | Provided if type==PERIOD | Description |
date | string | (+) | (-) | 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). |
dateTime | string | (-) | (+) | 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. |
dateTimeLocal | string | (-) | (+) | 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. |
temperature | sint32 | (-) | (+) | The actual ambient temperature in °C with 1° precision. |
feelsLike | sint32 | (-) | (+) | The perceived outdoor temperature in °C with 1° precision. |
minTemperature | sint32 | (+) | (-) | Minimum temperature encountered during the covered interval (day) in °C with 1° precision. |
maxTemperature | sint32 | (+) | (-) | Maximum temperature encountered during the covered interval (day) in °C with 1° precision. |
weatherCode | string | (+) | (+) | 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. |
windSpeed | double | (+) | (+) | Wind speed in m/s as positive decimal value with 0.1 m/s precision. |
windDirection | WindDirection | (+) | (+) | Wind direction (where the wind comes from) as one of 16 compass directions represented as corresponding values of the WindDirection enum. |
sunProbability | uint32 | (+) | (+) | Probability for sunshine during the covered interval in percent with 1 % precision (between 0 and 100). |
precipitationProbability | uint32 | (+) | (+) | Probability for precipitation during the covered interval in percent with 1 % precision (between 0 and 100). |
thunderProbability | uint32 | (+) | (+) | Probability for thunderstorm during the covered interval in percent with 1 % precision (between 0 and 100). |
precipitation | double | (+) | (+) | Precipitation sum in mm as a positive decimal value with 0.1 mm precision accumulated over the covered interval. |
pressure | uint32 | (-) | (+) | Barometric pressure in hPa with 1hPa precision. |
relativeHumidity | uint32 | (-) | (+) | Ambient relative humidity in percent with 1 % precision (between 0 and 100). |
uvIndex | uint32 | (+) | (+) | UV index according to the standard scale from 0 - infinity in integer steps. |
visibility | uint32 | (-) | (-) | Visibility in km with 1km precision. |
sunRise | string | (+) | (-) | Time of the sunrise in local time in format hh:mm:ss. |
sunSet | string | (+) | (-) | Time of the sunset in local time in format hh:mm:ss. |
moonRise | string | (+) | (-) | Time of the moonrise in local time in format hh:mm:ss. |
moonSet | string | (+) | (-) | Time of the moonset in local time in format hh:mm:ss. |
moonPhase | uint32 | (+) | (-) | 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 |
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 |