Technical documentation

Technical documentation

  • APIs
  • Services
  • Meteo
  • Blog

›Maps API

Weather Data

  • Introduction
  • Packages API
  • Images API

Environmental Data

  • Web Interfaces
  • Dataset API

Maps

  • Weather Maps
  • Radar & Satellite

Maps API

  • Overview
  • Maps Plugin
  • Tile API
  • Inventory API
  • Domains

Misc

  • Location Search API
  • Account API

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

Please note that 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

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:

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

AttributeTypeDescription
codeIntegerWeather variable code as integer.
levelStringLevel as in height of measurement
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 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:

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

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.
levelStringLevel as in height of measurement
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 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:

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

  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

Last updated on 1/5/2021
← Maps PluginInventory API →
  • Basic URL
    • Format definition
    • Domain definition
    • Time definition
    • GET parameter
  • Raster
    • Raster Layer definition
    • Raster Type definition
  • Vector
    • Vector Layer definition
    • Vector Type definition
  • Aggregation and Comparing
/*section markup create horizantal plane and under the section markup user can horizantally divide horizontal footer plane */
meteoblue
Weather ForecastProducts
API
IntroductionPackages APIImages APIEnvironmental DataMapsLocation Search
Services
EnergyWeather Station ForecastsCity ClimateOther Transmissions
Meteo
VariablesData SourcesVerification
Other
Blog
Imprint | Privacy | meteoblue AG © 2006 - 2021