Tile API · Technical documentation

To make the Tile API as flexible as possible, many options are encoded in the URL. Which weather model, variable or aggregation should be used. Should iso lines or contour bands be generated and how is the bandwidth of each band defined.

Basic URL

Every URL has the following structure:

https://maps-api.meteoblue.com/v1/map/{format}/{domain}/{time}/{layer}/{z}/{x}/{y}{get-parameter}

The Placeholders {format}, {domain}, {time}, {layer} and {get-parameter} must be replaced by the values of corresponding parameters.

Format definition

The Tile API can output tiles as

rastergraphic ("raster tile") in png format
vectordata ("vector tile") in protobuf format

The Format parameter can be set to raster to generate raster tiles or to vector to generate vector tiles. The Domain and Time parameter are defined equally for both formats. Only the Layer parameter differs according to this parameter (see Raster and Vector).

Domain definition

The Domain parameter specifies the source of the weather data. It can be set to the name of any available weather domain. Following a incomplete list of available domains.

note

Please note that special characters must get encoded. E.g. the / in WW3/GLOBAL must be percent encoded as %2F.

Name	Region	Source	Time Resolution	Forecast Length	Spatial Resolution
`NEMS4`	Central Europe	meteoblue	hourly	72	4.0 km
`NEMS12`	Europe	meteoblue	hourly	180	12.0 km
`NEMSGLOBAL`	Global	meteoblue	hourly	180	30.0 km
`GFS05`	Global	NOAA NCEP	3 hourly	180	40.0 km
`GFS025`	Global	NOAA NCEP	3 hourly	180	22.0 km
`GFS012`	Global	NOAA NCEP	3 hourly	180	12.0 km
`MFEU`	Europe	METEO FRANCE	hourly	96	11.0 km
`MFGLOBAL`	Global	METEO FRANCE	3 hourly	96	40.0 km
`UMGLOBAL`	Global	UK MET OFFICE	3 hourly	144	17.0 km
`ICON`	Global	Deutscher Wetterdienst	3 hourly	180	13.0 km
`ICONEU`	Europe	Deutscher Wetterdienst	3 hourly	120	7.0 km
`WW3/GLOBAL`	Global	NOAA NCEP	3 hourly	168	40.0 km

Time definition

A time-step is a string which represents a time according to ISO 8601 with the format YYYY-MM-DDThh:mm:ss+TIMEZONE. If hour, minute or second are omitted, 0 is assumed. If the timezone is missing, UTC is assumed. Dashes and colons are also optional. With those rules the time-step 20190822T18 represent the same time than 2019-08-22T18:00:00Z.

A time-interval represents a range in time by concatinating the start and end time with a slash /. E.g. 2019-01-01T00Z/2019-02-01T00Z.

note

Please note that special characters like slash /, colon : and plus + must get percent encoded to %2F, %3A and %2B.

There are four diffrent kinds of time allowed for this parameter:

Single time-step. For most maps this is sufficient.
A time-interval is used in combination with an aggregation function. E.g. the precipitation sum of 2 weeks. The GET parameter timeIntervalAggregation must be specified. For daily data the hour 0 must be selected. For monthly data the first day of the month. The correct time-zone is important for daily aggregations.
Two time-steps separated with an underscore _. This can be used with a comparator function to e.g. show the temperature difference between two hours. The GET parameter timeIntervalComparator must be set.
Two time-intervals separated with an underscore _. This can be used with a comparator function to e.g. show the precipitation deficit of 2 growing seasons. The GET parameters timeIntervalAggregation and timeIntervalComparator must be set.

note

Each layer also support a aggregation. Both can be used at the same time. Please see the Layer definition and the Aggregation and Comparing chapter for details.

GET parameter

GET parameter	Type	Default	Description
`lastUpdate`	String	none	Used to purge the cache on client and server-side. Should be set to last-model-update time.
`temperatureUnit`	`C`, `K` or `F`	`C`
`velocityUnit`	`m/s`, `km/h` , `mph`, `kn` or `bft`	`km/h`
`lengthUnit`	`metric` or `imperial`	`metric`
`energyUnit`	`watts` or `joules`	`watts`
`apikey`	String	none
`timeIntervalAggregation`	`min`, `max`, `mean` or `sum`	none	the aggregation function used for time-intervals.
`timeIntervalComparator`	`subtract`, `add`, or `mean`	none	the function to apply on 2 different time-steps/time-intervals. E.g. calculate the pressure deficit.

Raster

note

The following section only applies if raster was selected for the format parameter.

Raster Layer definition

One request can draw several layers in one png file. The layers are separated by underline _. Each layer contains multiple parameters which must be present. Those parameters are separated by a tilde ~.

Structure for one layer: {code}~{level}~{time-resolution}~{aggregation}~{type}~{type-parameter}

tip

See the Domains page for a full list of all available codes and levels.

Attribute	Type	Description
code	Integer	Weather variable code as integer.
level	String	Level as in height of measurement
time-resolution	String	e.g. `hourly`, `daily`, `monthly`, `yearly`. This way we can select monthly pre aggregations.
aggregation	String	Used for time-intervals. Also required even if only 1 hour is selected. E.g. `none`, `min`, `max` or `mean`.
type	TypeDefinition	Switch between diffrend render types.
type-parameter	Various	Specific parameters for each type. Must also be separated with tilde `~`

note

Spaces must be encoded as %20 or +. Some level contain some other special character like spread@180-0mbabovegnd. They also need to be URL encoded to spread%40180-0mbabovegnd.

Examples with time and layer selections:

2019-09-04T15:00:00+02:00 with hourly~none selects data for 2 o'clock local-time (e.g. CEST)
2019-09-04+02:00 with daily~max selects the daily maximum in local-time
20190901 with monthly~max selects the monthly max of september 2019
2019-08-01/2019-08-14 with daily~max and &timeIntervalAggregation=mean selects the daily max of 2 weeks and then calculates the mean value.
2018-04-01+02:00/2018-04-14+02:00_2019-04-01+02:00/2019-04-14+02:00 with hourly~none, &timeIntervalAggregation=sum and &timeIntervalComparator=subtract will calculate the sum of the first 2 weeks of april in 2018 and 2019 and afterwards subtract the value.

Raster Type definition

Types and Type-parameters:

Type	Type-parameters	example
`contourSteps`	`step0~color0~step1~color1~...~stepN~colorN`	`contourSteps~-2.3~#f940ad~1~rgb(255,255,0)~10~#2EA`
`colorBlurRaster`	`step0~color0~step1~color1~...~stepN~colorN`	`colorBlurRaster~0.01~#4a6f6e69~15~#39A6~20~rgba(128,64,32,0.5)`
`uvCoding`	none	`uvCoding`

Vector

note

The following section only applies if vector was selected for the format parameter.

Vector Layer definition

By definition one vector tile may contain multiple source-layer. Combining multiple source-layer in one protobuf file is more efficient, because the client only needs to request one vector tile and the server could combine weather variables that would have been read twice otherwise. In the request URL those Layers are separated by _. Each single layer contains multiple parameters which must be present. Those are separated by a tilde ~.

Structure for one layer: {name}~{code}~{level}~{time-resolution}~{aggregation}~{type}~{type-parameter}

tip

See the Domains page for a full list of all available codes and levels.

Attribute	Type	Description
name	String	Name of a source layer inside the protobuf. Can be used in a `style.json` to identify this layer.
code	Integer	Weather variable code as integer.
level	String	Level as in height of measurement
time-resolution	String	e.g. `hourly`, `daily`, `monthly`, `yearly`. This way we can select monthly pre aggregations.
aggregation	String	Used for time-intervals. Also required even if only 1 hour is selected. E.g. `none`,`min`,`max` or `mean`.
type	TypeDefinition	Switch between diffrend render types.
type-parameter	Various	Specific parameters for each type. Must also be separated with tilde `~`

note

Spaces must be encoded as %20 or +. Some level contain some other special character like spread@180-0mbabovegnd. They also need to be URL encoded to spread%40180-0mbabovegnd.

Vector Type definition

Types and Type-parameters:

Type	Type-parameters	example
`contourLinear`	`width` or `width~min~max`	`contourLinear~2.5~-5~15`
`contourSteps`	`step0~step1~step2~...~stepN`	`contourSteps~-2.3~0.01~1~2~3~4~5~10~15~20~25`
`linesLinear`	`width` or `width~min~max`	`linesLinear~2.5~-5~15`
`linesSteps`	`step0~step1~step2~...~stepN`	`linesSteps~-2.3~0.01~1~2~3~4~5~10~15~20~25`
`windArrows`	none
`lineslinearWithHighLowPressureLabels`	`width` or `width~min~max`	`lineslinearWithHighLowPressureLabels~2.5~-5~15`

Aggregation and Comparing

The following example uses both aggregations and the comparator to show their order of processing. The URL could be https://maps-api.meteoblue.com/map/vector/NEMSAUTO/2019-04-01%2f2019-04-30_2020-04-01%2f2020-04-30/specialTempLayer~11~2%20m%20above%20gnd~daily~max~contourLinear~2~-100~46/5/17/11?timeIntervalAggregation=mean&timeIntervalComparator=substract

Aggregation and Comparing

The API processes this URL in the following steps:

Read data for every grid point, for every layer, for every time range in the highest available resolution. In this example it will load hourly temperature data data for both time ranges. (only one grid point shown)

time	Temp [°C]
20190401T0000	8.29
20190401T0100	7.35
20190401T0200	6.78
...	...
20190501T2300	13.52

time	Temp [°C]
20200401T0000	0.77
20200401T0100	0.04
20200401T0200	-0.77
...	...
20200501T2300	11.61

Aggregate the loaded data for every grid point and every time range with the aggregation specified in the layer. In this example it will take the maximum temperature for each day.

time	Temp [°C]
20190401T0000	17.97
20190402T0000	19.25
20190403T0000	12.09
...	...
20190430T0000	11.60

time	Temp [°C]
20200402T0000	14.08
20200403T0000	12.76
20200404T0000	16.82
...	...
20200430T0000	14.53

Aggregate the data with the function specified in the timeIntervalAggregation parameter. In this example it will calculate the mean over the daily maximum temperatures.

time Temp [°C]

20190401T0000 16.174

time Temp [°C]

20200401T0000 19.959
Compare the data for both time ranges with the function specified in the timeIntervalComparator parameter.

time Temp [°C]

20190401T0000 -3.785