Tile API

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

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

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

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

1. Single time-step. For most maps this is sufficient.
2. 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.
3. 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.
4. 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 supports an aggregation. Both can be used at the same time. Consider the Layer Definition and the Aggregation and Comparing chapters 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 call 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

The Weather Model Domains page contains a full list of all available codes and levels.

Attribute	Type	Description
code	Integer	Weather variable code as integer. See reference.
level	String	Level as in height of measurement. See reference.
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. 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:

note

Special characters must get encoded. E.g. the #, (, ) and , must be percent encoded as %23, %28, %29 and %2C.

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 call one vector tile and the server could combine weather variables that would have been read twice otherwise. In the call 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

The Weather Model Domains page contains 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. See reference.
level	String	Level as in height of measurement. See reference.
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. 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.

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

The API processes this URL in the following steps:

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

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

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

4. Compare the data for both time ranges with the function specified in the timeIntervalComparator parameter.

   time	Temp [°C]
   20190401T0000	-3.785