Developer

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
https://{baseURL}/weatherforecast/{version}/hourly?lat={latitude}&lon={longitude}&forecastHours={number_of_hours}&key={Your_API_Key}

Example

get
URL request example
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
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.

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

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

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
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
https://{baseURL}/weatherforecast/{version}/daily?lat={latitude}&lon={longitude}&forecastHours={number_of_hours}&key={Your_API_Key}

Example

get
URL request example
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
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.

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

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.

dailyWeatherInfo object

FieldDescription

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

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