Skip to main content

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

NameRegionSourceTime ResolutionForecast LengthSpatial Resolution
NEMS4Central Europemeteobluehourly724.0 km
NEMS12Europemeteobluehourly18012.0 km
NEMSGLOBALGlobalmeteobluehourly18030.0 km
GFS05GlobalNOAA NCEP3 hourly18040.0 km
GFS025GlobalNOAA NCEP3 hourly18022.0 km
GFS012GlobalNOAA NCEP3 hourly18012.0 km
MFEUEuropeMETEO FRANCEhourly9611.0 km
MFGLOBALGlobalMETEO FRANCE3 hourly9640.0 km
UMGLOBALGlobalUK MET OFFICE3 hourly14417.0 km
ICONGlobalDeutscher Wetterdienst3 hourly18013.0 km
ICONEUEuropeDeutscher Wetterdienst3 hourly1207.0 km
WW3/GLOBALGlobalNOAA NCEP3 hourly16840.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 parameterTypeDefaultDescription
lastUpdateStringnoneUsed to purge the cache on client and server-side. Should be set to last-model-update time.
temperatureUnitC, K or FC
velocityUnitm/s, km/h , mph, kn or bftkm/h
lengthUnitmetric or imperialmetric
energyUnitwatts or jouleswatts
apikeyStringnone
timeIntervalAggregationmin, max, mean or sumnonethe aggregation function used for time-intervals.
timeIntervalComparatorsubtract, add, or meannonethe 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.

AttributeTypeDescription
codeIntegerWeather variable code as integer. See reference.
levelStringLevel as in height of measurement. See reference.
time-resolutionStringe.g. hourly, daily, monthly, yearly. This way we can select monthly pre aggregations.
aggregationStringUsed for time-intervals. Also required even if only 1 hour is selected. E.g. none, min, max or mean.
typeTypeDefinitionSwitch between diffrend render types.
type-parameterVariousSpecific 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.

TypeType-parametersexample
contourStepsstep0~color0~step1~color1~...~stepN~colorNcontourSteps~-2.3~#f940ad~1~rgb(255,255,0)~10~#2EA
colorBlurRasterstep0~color0~step1~color1~...~stepN~colorNcolorBlurRaster~0.01~#4a6f6e69~15~#39A6~20~rgba(128,64,32,0.5)
uvCodingnoneuvCoding

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.

AttributeTypeDescription
nameStringName of a source layer inside the protobuf. Can be used in a style.json to identify this layer.
codeIntegerWeather variable code as integer. See reference.
levelStringLevel as in height of measurement. See reference.
time-resolutionStringe.g. hourly, daily, monthly, yearly. This way we can select monthly pre aggregations.
aggregationStringUsed for time-intervals. Also required even if only 1 hour is selected. E.g. none,min,max or mean.
typeTypeDefinitionSwitch between diffrend render types.
type-parameterVariousSpecific 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:

TypeType-parametersexample
contourLinearwidth or width~min~maxcontourLinear~2.5~-5~15
contourStepsstep0~step1~step2~...~stepNcontourSteps~-2.3~0.01~1~2~3~4~5~10~15~20~25
linesLinearwidth or width~min~maxlinesLinear~2.5~-5~15
linesStepsstep0~step1~step2~...~stepNlinesSteps~-2.3~0.01~1~2~3~4~5~10~15~20~25
windArrowsnone
lineslinearWithHighLowPressureLabelswidth or width~min~maxlineslinearWithHighLowPressureLabels~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

Aggregation and Comparing

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)

    timeTemp [°C]
    20190401T00008.29
    20190401T01007.35
    20190401T02006.78
    ......
    20190501T230013.52
    timeTemp [°C]
    20200401T00000.77
    20200401T01000.04
    20200401T0200-0.77
    ......
    20200501T230011.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.

    timeTemp [°C]
    20190401T000017.97
    20190402T000019.25
    20190403T000012.09
    ......
    20190430T000011.60
    timeTemp [°C]
    20200402T000014.08
    20200403T000012.76
    20200404T000016.82
    ......
    20200430T000014.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.

    timeTemp [°C]
    20190401T000016.174
    timeTemp [°C]
    20200401T000019.959

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

    timeTemp [°C]
    20190401T0000-3.785