Developer

Advanced Weather API

Request Access
Service version: v1
Last edit: 2024.01.18

Purpose

The Advanced Weather API delivers spatio-temporally resolved, real-time weather information. The provided content is comprised of polygonal information about radar-based current precipitation and precipitation forecasts in different time slices.

Request data

HTTPS Method: GET

For ease of viewing and identification:

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

Format

get
URL request format
https://{baseURL}/weatherpolygons/{version}/{regionCode}?key={Your_API_Key}
get
curl request format
curl 'https://{baseURL}/weatherpolygons/{version}/{regionCode}?key={Your_API_Key}'

Example

get
URL request example
https://api.tomtom.com/weatherpolygons/v1/europe?key={Your_API_Key}

Request parameters

Required parameters

Description

baseURL
string

Base URL for calling TomTom services.
Value: api.tomtom.com

version
string

The version of the service to call.
Value: v1

regionCode
string

The name of the product region. See the Region Coverage for supported regionCode values.
Value: Example: europe

key
string

Authorization key for access to the API.
Value: Your valid API Key.

Request headers

Note: There are no required request headers in this endpoint.

Optional headers

Description

Accept-Encoding

Requests that the response compressed in the specified way. The fuelprices service supports http compression if desired. Currently, only gzip is supported.
Value: 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.
Value: 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 an HTTP 304 (not modified) message if no newer data is available.
Value: Sat, 29 Oct 1994 19:43:31 GMT

Content

Plain GET messages must be used to create requests.

Response data

The weather polygons are served in GeoJSON format. The root level of the response is a single FeatureCollection holding all weather polygons.

Every weather polygon is represented by a Feature , having a unique id and a set of properties. The enclosing FeatureCollection has an additional set of properties holding metadata such as the creation time of the response.

Response codes

Code

Meaning & 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 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

Content-Encoding

The service supports http compression if desired. Currently, only gzip is supported.
Example: gzip

Content-Type

The format of the served resource. The service always provides data in GeoJSON.
Example: application/json

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

E-tag

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

Response example

Response body example - JSON
1{
2  "type": "FeatureCollection",
3  "features": [
4    {
5      "type": "Feature",
6      "id": "0",
7      "properties": {
8        "uniqueId": "7ffffff",
9        "category": "precip",
10        "type": "rain",
11        "level": 0.86,
12        "area": 80.968,
13        "children": [],
14        "parent": "1",
15        "countries": ["ESP"]
16      },
17      "geometry": {
18        "type": "Polygon",
19        "coordinates": [
20          [
21            [-3.774, 37.513],
22            [-3.68, 37.568],
23            [-3.67, 37.628],
24            [-3.695, 37.653],
25            [-3.759, 37.608],
26            [-3.779, 37.518]
27          ]
28        ]
29      },
30      "bbox": [-3.779, 37.513, -3.67, 37.653]
31    }
32  ],
33  "properties": {
34    "forecastOffset": 15,
35    "creationTime": "2015-10-13T11:14:53.70Z",
36    "timeStamp": "2015-10-13T11:14:53.70Z",
37    "rootTimeStamp": "2015-10-13T11:14:53.70Z"
38  }
39}

Response structure

FeatureCollection properties

Property

Description

forecastOffset
integer

The forecast horizon of the weather polygon in minutes. A zero stands for the present time.

creationTime
string

Time of the request 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".

timeStamp
string (datetime)

Time of which the weather polygons refer to (may be in the future) 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".

rootTimeStamp
string (datetime)

Time at which the weather polygons were measured/predicted 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".

Feature properties

Property

Description

uniqueId
string

A unique and stable id of the current weather polygon.

category
string

The category of the weather polygon, e.g., "precip" (see section Category Values ).

type
string

The type of the weather polygon, e.g., "rain" (see section Type Values ).

level
integer

The level of the weather atom, i.e., a numeric value describing its magnitude.

area
integer

The area of the weather polygon in square kilometers (km²).

children
array (of strings)

A list of Feature-Ids that represent polygons of the same category and type with the next higher level which lie inside the weather polygon. An empty array means no children.

parent
string

A single Feature-Id that represents the polygon of the next lower level which contains the weather polygon. An empty string means no parent.

countries
array (of strings)

The list of countries, given as ISO 3166-1 alpha-3 country codes that intersect with the weather polygon.

The Feature-Id is given by the id of the Feature object, see also the Feature specification.

Category values

Category

Description

precip
string

Regional information about the precipitation in the form of regions with different precipitation levels.

Type values

  • Type values for category precip
    • rain
    • snow
    • mixed
    • hail

Level values

  • Level values for category precip

The value of a level specifies the precipitation intensity in mm/h.

Usage and Freshness

The weather polygons are updated regularly, typical frequencies being in the order of 15 minutes. Using the support for the 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

RegionRegionCode
Europe

europe

USA

usa

North America

nam

Latin America

latam

Australia

australia