Weather Forecast API

Request access

Service version: 1.0 Last edit: 2022.08.25

Purpose

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

Request data for Hourly Forecasts

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

1
https://{baseURL}/weatherforecast/{version}/hourly?lat={latitude}&lon={longitude}&forecastHours={number_of_hours}&key={Your_API_Key}

Example

get

URL request example

1
https://api.tomtom.com/weatherforecast/v1/hourly?lat=40.7911106&lon=-73.8525824&forecastHours=5&key={Your_API_Key}

curl command example

get

curl request example

1
curl 'https://api.tomtom.com/weatherforecast/v1/hourly?lat=40.7911106&lon=-73.8525824&forecastHours=5&key={Your_API_Key}'

Request parameters

Required parameters	Description
`baseURL` string	The base URL for calling the API. Value: `api.tomtom.com`
`version` string	Service version. Value: `1.0`
`key` 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.

Required parameters

Description

baseURL

string

The base URL for calling the API.

Value: api.tomtom.com

version

string

Service version.

Value: 1.0

key

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 parameters	Description
`forecastHours` integer	Number of hours from now for which the forecast is needed. Default value: `24`

Optional parameters

Description

forecastHours

integer

Number of hours from now for which the forecast is needed.

Default value: 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
      {
13
        "dateTime": "2022-05-10T09:00:00Z",
14
        "dateTimeLocal": "2022-05-10T11:00:00",
15
        "temperature": 19,
16
        "feelsLike": 19,
17
        "weatherCode": "D_OC_____",
18
        "windSpeed": 6.4,
19
        "windDirection": "SW",
20
        "sunProbability": 0,
21
        "precipitationProbability": 13,
22
        "thunderProbability": 0,
23
        "precipitation": 0.0,
24
        "pressure": 1016,
25
        "relativeHumidity": 64,
26
        "uvIndex": 2
27
      }
28
    ]
29
  }
30
}

Response fields

The following table describes all of the response fields.

Primary fields
Field	Description
`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
Field	Description
`version` string	Version of the data model.
`lastUpdatedTime` string (date-time)	UTC Timestamp of the response generated in ISO8601 format.
stationCoordinates object
Field	Description
`lat` double	Latitude of the weather station.
`lon` double	Longitude of the weather station.
hourlyWeatherInfo object
Field	Description
`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

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

Examples

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

get

Request

1
https://api.tomtom.com/weatherforecast/v1/hourly?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
      {
13
        "dateTime": "2022-05-12T08:00:00Z",
14
        "dateTimeLocal": "2022-05-12T10:00:00",
15
        "temperature": 15,
16
        "feelsLike": 15,
17
        "weatherCode": "D_CS_____",
18
        "windSpeed": 4.7,
19
        "windDirection": "W",
20
        "sunProbability": 95,
21
        "precipitationProbability": 2,
22
        "thunderProbability": 0,
23
        "precipitation": 0.0,
24
        "pressure": 1018,
25
        "relativeHumidity": 68,
26
        "uvIndex": 2
27
      },
28
      {
29
        "dateTime": "2022-05-12T09:00:00Z",
30
        "dateTimeLocal": "2022-05-12T11:00:00",
31
        "temperature": 16,
32
        "feelsLike": 16,
33
        "weatherCode": "D_CS_____",
34
        "windSpeed": 5.2,
35
        "windDirection": "W",
36
        "sunProbability": 100,
37
        "precipitationProbability": 2,
38
        "thunderProbability": 0,
39
        "precipitation": 0.0,
40
        "pressure": 1018,
41
        "relativeHumidity": 59,
42
        "uvIndex": 3
43
      }
44
    ]
45
  }
46
}

Request data for Daily Forecasts

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 format

1
https://{baseURL}/weatherforecast/{version}/daily?lat={latitude}&lon={longitude}&forecastHours={number_of_hours}&key={Your_API_Key}

Example

get

URL request example

1
https://api.tomtom.com/weatherforecast/v1/daily?lat=40.7911106&lon=-73.8525824&forecastHours=5&key={Your_API_Key}

curl command example

get

curl request example

1
curl 'https://api.tomtom.com/weatherforecast/v1/daily?lat=40.7911106&lon=-73.8525824&forecastHours=5&key={Your_API_Key}'

Required parameters	Description
`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.

Required parameters

Description

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 parameters	Description
`forecastDays` integer	Number of days from now for which the forecast is needed. Default: `14`

Optional parameters

Description

forecastDays

integer

Number of days from now for which the forecast is needed.

Default: 14

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-07-28T09:00:06.318191Z"
5
  },
6
  "data": {
7
    "stationCoordinates": {
8
      "lat": 10.12,
9
      "lon": 9.83
10
    },
11
    "dailyWeatherInfo": [
12
      {
13
        "date": "2022-07-28",
14
        "minTemperature": 21,
15
        "maxTemperature": 28,
16
        "weatherCode": "D_OC_RAT2",
17
        "windSpeed": 1.4,
18
        "windDirection": "W",
19
        "sunProbability": 3,
20
        "precipitationProbability": 96,
21
        "thunderProbability": 57,
22
        "precipitation": 21.7,
23
        "uvIndex": 7,
24
        "sunRise": "06:09:00",
25
        "sunSet": "18:44:00",
26
        "moonRise": "05:48:00",
27
        "moonSet": "18:49:00",
28
        "moonPhase": 360
29
      }
30
    ]
31
  }
32
}

Response fields

The following table describes all of the response fields.

Primary fields
Field	Description
`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.
`dailyWeatherInfo` array	Array of weather data, one per day.
metadata object
Field	Description
`version` string	Version of the data model.
`lastUpdatedTime` string (date-time)	UTC Timestamp of the response generated in ISO8601 format.
stationCoordinates object
Field	Description
`lat` double	Latitude of the weather station.
`lon` double	Longitude of the weather station.
dailyWeatherInfo object
Field	Description
`date` string (data)	The day that applies to the forecast.
`minTemperature` string	The temperature in degrees celsius with a 1° precision.
`maxTemperature` 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.
`uvIndex` integer	The UV index.
`sunRise` integer	Time of the sunrise in local time.
`sunSet` integer	Time of the sunset in local time.
`moonRise` integer	Time of the moonrise in local time.
`moonSet` integer	Time of the moonset in local time.
`moonPhase` integer	Moon phase in degrees between 0° and 360° with 1° precision.

Response codes

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

Examples

Get the weather forecast for the next 2 days for the Amsterdam Central station (lat: 52.37971857640887, lon: 4.900282722759855).

get

Request

1
https://api.tomtom.com/weatherforecast/v1/daily?lat=52.37971857640887&lon=4.900282722759855&forecastHours=2&key={Your_API_Key}

Response - JSON

1
{
2
  "metadata": {
3
    "version": "1.0",
4
    "lastUpdatedTime": "2022-07-28T13:00:08.257660Z"
5
  },
6
  "data": {
7
    "stationCoordinates": {
8
      "lat": 52.37,
9
      "lon": 4.9
10
    },
11
    "dailyWeatherInfo": [
12
      {
13
        "date": "2022-07-28",
14
        "minTemperature": 14,
15
        "maxTemperature": 22,
16
        "weatherCode": "D_CL_____",
17
        "windSpeed": 5.0,
18
        "windDirection": "E",
19
        "sunProbability": 18,
20
        "precipitationProbability": 6,
21
        "thunderProbability": 0,
22
        "precipitation": 0.3,
23
        "uvIndex": 5,
24
        "sunRise": "05:53:00",
25
        "sunSet": "21:39:00",
26
        "moonRise": "04:53:00",
27
        "moonSet": "22:11:00",
28
        "moonPhase": 360
29
      },
30
      {
31
        "date": "2022-07-29",
32
        "minTemperature": 14,
33
        "maxTemperature": 24,
34
        "weatherCode": "D_PC_____",
35
        "windSpeed": 4.4,
36
        "windDirection": "N",
37
        "sunProbability": 31,
38
        "precipitationProbability": 19,
39
        "thunderProbability": 0,
40
        "precipitation": 0.0,
41
        "uvIndex": 6,
42
        "sunRise": "05:55:00",
43
        "sunSet": "21:37:00",
44
        "moonRise": "06:04:00",
45
        "moonSet": "22:33:00",
46
        "moonPhase": 10
47
      }
48
    ]
49
  }
50
}

Weather codes

The weather codes are defined as a 9-character string with the following basic structure:

1
{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 the North.
`NNE`	Wind from the North-North-East.
`NE`	Wind from the North-East.
`ENE`	Wind from the East-North-East.
`E`	Wind from the East.
`ESE`	Wind from the East-South-East.
`SE`	Wind from the South-East.
`SSE`	Wind from the South-South-East.
`S`	Wind from the South.
`SW`	Wind from the South-South-West.
`SW`	Wind from the South-West.
`WSW`	Wind from the West-South-West.
`W`	Wind from the West.
`WNW`	Wind from the West-North-West.
`NW`	Wind from the North-West.
`NNW`	Wind from the North-North-West.
`UNK`	Wind direction unknown.

Weather Forecast API

Purpose

Request data for Hourly Forecasts

HTTPS method: GET

URL format

Example

curl command example

Request parameters

Response data

Response body

Response fields

Response codes

Examples

Request data for Daily Forecasts

HTTPS method: GET

URL format

Example

curl command example

Response data

Response body

Response fields

Response codes

Examples

Weather codes

Valid code values

Combination Rules

Examples

The WindDirection enum

HTTPS method: `GET`

HTTPS method: `GET`