Documentation of the MetGIS Maps API

Version 1.2, October 7, 2015

The MetGIS Weather Maps API offers forecasts as a Tile Maps Service (TMS). This standardized format enables you to integrate our weather predictions for Central Europe into any dynamic map on your website or within your app. Check our demo page to see an example of weather data layers integrated in zoomable maps.

Our forecasts are updated every 24 hours. Once a day, at approximately 4:00 UTC, a new forecast is available, covering the following 75 hours in three-hour time intervals. Beside regular tiles (in PNG-format) we also provide UTFGrid Tiles to enable a fast numerical representation of our colored maps.

The following sections provide detailed information about our Maps API, with various examples showing how to include our weather in your maps.

Weather Parameters

The following weather parameters are currently available, check the coding behind the name:

Temperature - tmp2m
Precipitation - hr_p
Fresh Snow - hr_sn
Cloudiness - tcdcprs
Wind - wind

Some more parameters (cumulative snow and precipitation for time spans of one to three days) are currently under development and will be available soon.

API Call for Tiles

To view our weather tiles within your website or application you need to call the following address with parameters specified according to your requirements:

http://{t1-t3}.metgis.com/tilestache/{parameter}_{timestep}/{z}/{x}/{y}.png?key={YOUR-API-KEY}

Parameters:

{t1-t3} - subdomains to get around browser limitations on the number of simultaneous HTTP connections to each host
{parameter} - the code of the desired weather parameter as described in meta.json
{timestep} - value of the desired time step, starting at 1 which reflects the weather forecasts for the time forecastIssued, see meta.json
{x}, {y}, {z} - x,y coordinates and zoom of a tile
{YOUR-API-KEY} - your unique API-Key, more information

Please check our sample code to see how to place the code line above in the right context.

UTFGrid

To enable fast information about our weather layers we also provide UTFGrids (specification) for our tiles. Like in our demo page you can use the UTFGrid Layers with a mouseover or on tap on mobile devices.

To load the UTFGrid layers use the following URL:

http://{t1-t3}.metgis.com/tilestache/{parameter}_{timestep}_grid/{z}/{x}/{y}.json?callback={cb}&key={YOUR-API-KEY}

Parameters:

{t1-t3} - subdomains to get around browser limitations on the number of simultaneous HTTP connections to each host
{parameter} - the code of the desired weather parameter as described in meta.json
{timestep} - value of the desired time step, starting at 1 which reflects the weather forecasts for the time forecastIssued
{x}, {y}, {z} - zoom and x,y coordinates of a UTFGrid-tile
{YOUR-API-KEY} - your unique API-Key, more information

Please check our sample code to see how to place the code line above in the right context.

Values for selected points

To show values for a variety of significant locations (cities, towns, peaks, ...) as additional overlay on your map, you can integrate our Point-Layers. They are disposable for all available weather parameters and you can show them on your map in the same way.

Sample call

http://{t1-t3}.metgis.com/tilestache/{parameter}_{timestep}_point/{z}/{x}/{y}.png?key={YOUR-API-KEY}

Please note that this feature is currently only available in the demo page. Please contact us for further information.

API-Key

To use our service you must include your unique API-Key with every call. Please contact us to get an API-Key and more information on pricing and availability.

meta.json

We issue a file with meta-information for every forecast run. It consists of the start time of the forecast run and other useful information. This meta.json is located at http://tiles.metgis.com/meta/{V}/meta.json where {V} stands for the version number. The current version number is 0.6.

Attributes:

description - a brief description of the service
productInfo - information on the product
forecastIssued - start time of the calculations of the meteorological forecast model as ISO-Datestring (UTC). This is also the time of the latest measurements that exercise an influence on the forecast.
forecastCompleted - end time of the calculation of the tiles, the time when the forecasts are available to be viewed as ISO-Datestring (UTC).
projection - EPSG-Code of the coordinate reference system used for the tiles
bbox - the bounding box of the currently available tiles (latitude/longitude of the lower left and upper right box limit)
timeStep - length of period of time between two forecast times, tipically 3 hours
timeStepUnit - the unit of timeStep and parameterPeriod, h stands for hour
timeStepNumber - number of timeSteps for this forecast
attribution - attribution that has to be shown in conjunction with the forecasts, see the demo page
parameters - list of available weather parameters
- parameterUnit - unit of the given parameter
- parameterPeriod - time period which a single prediction refers to. For most parameters (e.g. temperature) this is a point in time, for some others (e.g. precipitation) it is a period (typically as long as the timeStep). 0 indicates a point in time, any other number describes the length of the time period.
- parameterName - localized name of the given parameter, indetified by ISO 639-1 Codes. Currently available languages: English, German, Spanish, French, Italian, Slovenian.

{
   "description":"MetGIS Tile Server",
   "productInfo":"MetGIS Weather Forecast based on GFS Data",
   "forecastIssued":"2015-01-03T18:00Z",
   "forecastCompleted":"2015-01-04T03:44Z",
   "projection":"EPSG:3857",
   "bbox":"43.0,5.0,50.0,18.0",
   "timeStep":3,
   "timeStepUnit":"h",
   "timeStepNumber":25,
   "attribution":"Weather Forecast &copy; <a title='MetGIS Professional Weather Service' href='http:\/\/www.metgis.com\/' target='_blank'>MetGIS</a>",
   "parameters":{
      "wind":{
         "parameterUnit":"m\/s",
         "parameterPeriod":0,
         "parameterName":{
            "sl":"Veter",
            "de":"Wind",
            "it":"Vento",
            "fr":"Vent",
            "en":"Wind",
            "es":"Viento"
         }
      },
      "tmp2m":{
         "parameterUnit":"°C",
         "parameterPeriod":0,
         "parameterName":{
            "sl":"Temperatura",
            "de":"Temperatur",
            "it":"Temperatura",
            "fr":"Température",
            "en":"Temperature",
            "es":"Temperatura"
         }
      },
      "tcdcprs":{
         "parameterUnit":"%",
         "parameterPeriod":0,
         "parameterName":{
            "sl":"Oblačnost",
            "de":"Bewölkung",
            "it":"Nuvolosità",
            "fr":"Nébulosité",
            "en":"Cloudiness",
            "es":"Nubosidad"
         }
      },
      "hr_p":{
         "parameterUnit":"mm",
         "parameterPeriod":3,
         "parameterName":{
            "sl":"Padavine",
            "de":"Niederschlag",
            "it":"Precipitazione",
            "fr":"Précipitations",
            "en":"Precipitation",
            "es":"Precipitación"
         }
      },
      "hr_sn":{
         "parameterUnit":"cm",
         "parameterPeriod":3,
         "parameterName":{
            "sl":"Novozapadli sneg",
            "de":"Neuschnee",
            "it":"Neve fresca",
            "fr":"Neige fraiche",
            "en":"Fresh Snow",
            "es":"Nieve fresca"
         }
      }
   }
}

Color values

The color values related to the parameters are as follows:

{
    "tmp2m": [[">40","#35000f"],["38","#4c0016"],["36","#7f0000"],["34","#800026"],["32","#b30000"],["30","#bd0026"],["28","#d7301f"],["26","#ef6548"],["24","#fc8d59"],["22","#fdbb84"],["20","#fd8d3c"],["18","#feb24c"],["16","#fed976"],["14","#ffeda0"],["12","#ffffcc"],["10","#f7fcb9"],["8","#d9f0a3"],["6","#addd8e"],["4","#78c679"],["2","#41ab5d"],["0","#238443"],["-2","#9ecae1"],["-4","#6baed6"],["-6","#4292c6"],["-8","#2171b5"],["-10","#08519c"],["-12","#06407c"],["-14","#544082"],["-16","#6a51a3"],["-18","#807dba"],["-20","#9e9ac8"],["-22","#bcbddc"],["-24","#dadaeb"],["-26","#efedf5"],["-28","#bdbdbd"],["-30","#969696"],["<-30","#737373"]],

    "hr_p": [["16","#c51b7d"],["12","#de77ae"],["8","#f1b6da"],["6","#fde0ef"],["4","#08306b"],["3","#08519c"],["2","#2171b5"],["1.5","#4292c6"],["1","#6baed6"],["0.5","#9ecae1"],["0.2","#c6dbef"],["0.1","#deebf7"]],

    "hr_sn": ["120","#a11a04"],["80","#e03603"],["50","#f7760f"],["30","#fba204"],["20","#fbc607"],["16","#f311e8"],["12","#f353ec"],["8","#f79df3"],["6","#019ccf"],["4","#19bbf1"],["2","#59ccf2"],["1","#a0e0f6"],["0.3","#c6ecf9"],["0.1","#ffffff"],

    "tcdcprs": [["87.5","#4c4c4c"],["75","#666666"],["62.5","#7f7f7f"],["50","#999999"],["37.5","#b2b2b2"],["25","#cccccc"]],

    "wind": [["24","#00441b"],["21","#006d2c"],["18","#1d8640"],["15","#359e53"],["12","#54b466"],["9","#7ac77b"],["6","#9dd798"],["3","#bbe4b4"],["2","#d4eece"],["1","#e9f6e4"]]
}

Examples

Our weather maps may be embedded within your website or app, using different software frameworks.

For your website you can use JavaScript Frameworks like Leaflet, OpenLayers or Google Maps API.
For Apps there are different SDKs like the Google Maps Android API, the Google Maps SDK for iOS, Apple's Maps for Developers or the Mapbox SDK.

The integration of our maps is as easy as this brief example for Leaflet shows:

var temperature = L.tileLayer( 'http://t1.metgis.com/tilestache/tmp2m_5/{z}/{x}/{y}.png?key=YOUR_API_KEY' );

The following examples show possible implementations with different frameworks.

Leaflet

Simple example of temperature:

var tmp2mUrl = 'http://{s}.metgis.com/tilestache/tmp2m_';
var urlSuffix = '/{z}/{x}/{y}.png?key=YOUR-API-KEY';

var layertmp2m = L.tileLayer( tmp2mUrl + initialStep + urlSuffix, {
  maxZoom: 15,
  attribution: "Weather Forecast &copy; <a title='MetGIS Professional Weather Service' href='http://www.metgis.com/' target='_blank'>MetGIS</a>",
  opacity:0.7,
  subdomains: ["t1", "t2", "t3"]
});

To integrate UTFGrids with Leaflet you have to use the Leaflet.utfgrid plugin.

var tmp2mGridUrl = 'http://{s}.metgis.com/tilestache/tmp2m_';
var gridUrlSuffix = '_grid/{z}/{x}/{y}.json?callback={cb}';

var layertmp2mGrid = new L.UtfGrid(tmp2mGridUrl + initialStep + gridUrlSuffix, {
  resolution: 4,
  pointerCursor: false,
  maxRequests:8,
  subdomains: ["t1", "t2", "t3"]
});
layertmp2mGrid.on('mouseover', function(e){console.log(e.data);});

Please refer to our demo page to view a full working example.

OpenLayers 3