Sorry, you need to enable JavaScript to visit this website.

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.

metaData {
  creationTime: 1429007400
  lastUpdateTime: 1429007400
  source: "TomTom"
  numLocations: 2
}
locations {
  id: 102804646
  longitude: 13.62
  latitude: 52.37
  weatherInfoLists {
    lastChangeTime: 1423567860
    type: DAY
    weatherInfos {
      date: "2015-04-14"
      minTemperature: 2
      maxTemperature: 6
      weatherCode: "D_CL_RAI1"
      windSpeed: 5.2
      windDirection: NW
      sunProbability: 3
      precipitationProbability: 55
      thunderProbability: 0
      precipitation: 0.5
      uvIndex: 0
      sunRise: "07:32:00"
      sunSet: "17:08:00"
      moonSet: "09:48:00"
      moonPhase: 250
    }
    weatherInfos {
      date: "2015-04-15"
      minTemperature: -2
      maxTemperature: 5
      weatherCode: "D_OC_____"
      windSpeed: 2.6
      windDirection: W
      sunProbability: 0
      precipitationProbability: 18
      thunderProbability: 0
      precipitation: 0.4
      uvIndex: 1
      sunRise: "07:30:00"
      sunSet: "17:10:00"
      moonRise: "00:13:00"
      moonSet: "10:15:00"
      moonPhase: 260
    }
  }
  weatherInfoLists {
    lastChangeTime: 1429007400
    type: PERIOD
    intervalInHours: 1
    weatherInfos {
      dateTime: "2015-04-14T10:00:00Z"
      dateTimeLocal: "2015-04-14T12:00:00"
      temperature: 12
      feelsLike: 12
      weatherCode: "D_CL_____"
      windSpeed: 4.3
      windDirection: W
      sunProbability: 27
      precipitationProbability: 2
      thunderProbability: 0
      precipitation: 0.0
      pressure: 1026
      relativeHumidity: 53
      uvIndex: 4
    }
    weatherInfos {
      dateTime: "2015-04-14T11:00:00Z"
      dateTimeLocal: "2015-04-14T13:00:00"
      temperature: 13
      feelsLike: 13
      weatherCode: "D_CL_____"
      windSpeed: 4.6
      windDirection: W
      sunProbability: 26
      precipitationProbability: 2
      thunderProbability: 0
      precipitation: 0.0
      pressure: 1025
      relativeHumidity: 48
      uvIndex: 4
    }
  }
  name: "Zeuthen"
  country: "DE"
  timeZone: "Europe/Berlin"
}
locations {
  id: 102810815
  longitude: 13.73
  latitude: 52.63
  weatherInfoLists {
    lastChangeTime: 1423567860
    type: DAY
    weatherInfos {
      date: "2015-04-14"
      minTemperature: 1
      maxTemperature: 6
      weatherCode: "D_OC_RAI1"
      windSpeed: 5.3
      windDirection: NW
      sunProbability: 1
      precipitationProbability: 50
      thunderProbability: 0
      precipitation: 0.4
      uvIndex: 0
      sunRise: "07:32:00"
      sunSet: "17:07:00"
      moonSet: "09:47:00"
      moonPhase: 250
    }
    weatherInfos {
      date: "2015-04-15"
      minTemperature: -2
      maxTemperature: 3
      weatherCode: "D_CL_____"
      windSpeed: 2.7
      windDirection: W
      sunProbability: 2
      precipitationProbability: 17
      thunderProbability: 0
      precipitation: 0.3
      uvIndex: 1
      sunRise: "07:30:00"
      sunSet: "17:09:00"
      moonRise: "00:13:00"
      moonSet: "10:14:00"
      moonPhase: 260
    }
  }
  weatherInfoLists {
    lastChangeTime: 1429007400
    type: PERIOD
    intervalInHours: 1
    weatherInfos {
      dateTime: "2015-04-14T10:00:00Z"
      dateTimeLocal: "2015-04-14T12:00:00"
      temperature: 10
      feelsLike: 7
      weatherCode: "D_CL_____"
      windSpeed: 4.5
      windDirection: W
      sunProbability: 27
      precipitationProbability: 2
      thunderProbability: 0
      precipitation: 0.0
      pressure: 1026
      relativeHumidity: 55
      uvIndex: 4
    }
    weatherInfos {
      dateTime: "2015-04-14T11:00:00Z"
      dateTimeLocal: "2015-04-14T13:00:00"
      temperature: 11
      feelsLike: 11
      weatherCode: "D_CL_____"
      windSpeed: 4.9
      windDirection: W
      sunProbability: 24
      precipitationProbability: 3
      thunderProbability: 0
      precipitation: 0.0
      pressure: 1025
      relativeHumidity: 49
      uvIndex: 4
    }
  }
  name: "Werneuchen"
  country: "DE"
  timeZone: "Europe/Berlin"
}

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