Weather Forecast API

Service version: 1.0
Last edit: 2022.05.16

Purpose

The Weather Forecast API delivers current and forecasted point-based weather conditions.

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.

URL format

GET
URL request example
https://{baseURL}/weatherforecast/{version}?lat={latitude}&lon={longitude}&forecastHours={number_of_hours}&key={Your_API_Key}

Example

GET
URL request example
https://api.tomtom.com/weatherforecast/v1?lat=40.7911106&lon=-73.8525824&forecastHours=5&key={Your_API_Key}
Required parametersDescription
baseURL
string
The base URL for calling the API.
Value: api.tomtom.com
version
string
Service version.
Value: 1.0
apiKey
string
An API Key valid for the requested service.
Value: Your valid API Key.
lon
double
Longitude.
Value: between -180 and 180.
lat
double
Latitude.
Value: between -90 and 90.
Optional parametersDescription
forecastHours
integer
Number of hours from now for which the forecast is needed.
Default: 24

Response data

Response body

The following JSON code block demonstrates a successful response from the API server.

Response body - JSON
1{
2 "metadata" : {
3 "version" : "1.0",
4 "lastUpdatedTime" : "2022-05-10T09:59:07.526391Z"
5 },
6 "data" : {
7 "stationCoordinates" : {
8 "lat" : 52.45,
9 "lon" : 4.83
10 },
11 "hourlyWeatherInfo" : [ {
12 "dateTime" : "2022-05-10T09:00:00Z",
13 "dateTimeLocal" : "2022-05-10T11:00:00",
14 "temperature" : 19,
15 "feelsLike" : 19,
16 "weatherCode" : "D_OC_____",
17 "windSpeed" : 6.4,
18 "windDirection" : "SW",
19 "sunProbability" : 0,
20 "precipitationProbability" : 13,
21 "thunderProbability" : 0,
22 "precipitation" : 0.0,
23 "pressure" : 1016,
24 "relativeHumidity" : 64,
25 "uvIndex" : 2
26 } ]
27 }
28}

Response fields

The following table describes all of the response fields.

Primary fields
FieldDescription
metadata
object
Metadata about the rendered response.
data
object
Weather forecast information.
stationCoordinates
object
Co-ordinates of the weather station where the weather data was recorded.
hourlyWeatherInfo
array
Array of weather data, one per hour.
metadata object
FieldDescription
version
string
Version of the data model.
lastUpdatedTime
string (date-time)
UTC Timestamp of the response generated in ISO8601 format.
stationCoordinates object
FieldDescription
lat
double
Latitude of the weather station.
lon
double
Longitude of the weather station.
hourlyWeatherInfo object
FieldDescription
dateTime
string (data-time)
The time that applies to the forecast.
dateTimeLocal
string
The time that applies to the forecast in the local time zone.
temperature
integer
The temperature in degrees celsius with a 1° precision.
feelsLike
integer
Feels like temperature in degrees celsius with a 1° precision.
weatherCode
string
Weather code. See the weatherCode values table for possible values.
windSpeed
double
The expected wind speed in m/s.
windDirection
string
The expected direction of the wind, in up to three characters.
sunProbability
integer
The probability of sunshine (value between 0 & 100 with a precision of 1).
precipitationProbability
integer
The probability of getting some form of precipitation (value between 0 & 100 with a precision of 1).
thunderProbability
integer
The probability of having a thunderstorm (value between 0 & 100 with a precision of 1).
precipitation
integer
The total precipitation (in mm) with a precision of 0.1.
pressure
integer
The barometric pressure (in hPa) with a precision of 1hPa.
relativeHumidity
integer
The ambient relative humidity (value between 0 & 100 with a precision of 1).
uvIndex
integer
The UV index.

Response Codes

CodeMeaning and possible causes
200OK
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.
400Bad request: One of the supplied parameters has a wrong format.
500Internal Server Error.

Examples

To get the weather forecast for the next 2 hours in Amsterdam Central station (lat: 52.37971857640887, lon: 4.900282722759855)

GET
Request
https://api.tomtom.com/weatherforecast/v1?lat=52.37971857640887&lon=4.900282722759855&forecastHours=2&key={Your_API_Key}
Response - JSON
1{
2 "metadata" : {
3 "version" : "1.0",
4 "lastUpdatedTime" : "2022-05-12T09:01:09.154814Z"
5 },
6 "data" : {
7 "stationCoordinates" : {
8 "lat" : 52.37,
9 "lon" : 4.9
10 },
11 "hourlyWeatherInfo" : [ {
12 "dateTime" : "2022-05-12T08:00:00Z",
13 "dateTimeLocal" : "2022-05-12T10:00:00",
14 "temperature" : 15,
15 "feelsLike" : 15,
16 "weatherCode" : "D_CS_____",
17 "windSpeed" : 4.7,
18 "windDirection" : "W",
19 "sunProbability" : 95,
20 "precipitationProbability" : 2,
21 "thunderProbability" : 0,
22 "precipitation" : 0.0,
23 "pressure" : 1018,
24 "relativeHumidity" : 68,
25 "uvIndex" : 2
26 }, {
27 "dateTime" : "2022-05-12T09:00:00Z",
28 "dateTimeLocal" : "2022-05-12T11:00:00",
29 "temperature" : 16,
30 "feelsLike" : 16,
31 "weatherCode" : "D_CS_____",
32 "windSpeed" : 5.2,
33 "windDirection" : "W",
34 "sunProbability" : 100,
35 "precipitationProbability" : 2,
36 "thunderProbability" : 0,
37 "precipitation" : 0.0,
38 "pressure" : 1018,
39 "relativeHumidity" : 59,
40 "uvIndex" : 3
41 } ]
42 }
43}

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 the North.
NNEWind from the North-North-East.
NEWind from the North-East.
ENEWind from the East-North-East.
EWind from the East.
ESEWind from the East-South-East.
SEWind from the South-East.
SSEWind from the South-South-East.
SWind from the South.
SSWWind from the South-South-West.
SWWind from the South-West.
WSWWind from the West-South-West.
WWind from the West.
WNWWind from the West-North-West.
NWWind from the North-West.
NNWWind from the North-North-West.
UNKWind direction unknown.