API Request

GET requests

According to the REST1 standard, data can be queried using HTTP-GET or HTTP-POST requests from api.meteomatics.com. A request can be constructed using the format:
https://api.meteomatics.com/<validdatetime>/<parameters>/<location>/<format>?<optionals>
Example: https://api.meteomatics.com/__replace__0T12ZP1D:PT1H/t_2m:C,relative_humidity_2m:p/47.4245,9.3767/html?model=mix

POST requests

POST requests can not be performed from a browser directly but there are graphical tools that can be used to construct and test POST requests. If you are sending a POST request, which is recommended for large URL lengths (>1000 characters), follow this notation:
URL: https://api.meteomatics.com/<validdatetime>/
Post-Body: <parameters>/<location>/<format>?<optionals> in plain text
Example: Note: We assume authentication is handled by the REST client software separately. Therefore, we omit the authentication for the rest of this document. It is possible to send the username and password in the URL (it would then start with https://username:password@api.meteomatics.com) but not recommended since the password is sent in plain text.

Required Parameters

The following table describes all required parameters for the URL:
Option Description Value Example
validdatetime A date or date range to retrieve the weather forecast for. (see separate table with Date/Time Description below) 2017-05-28T13:00:00Z or 2017-05-28T13:00:00Z--2017-05-30T13:00:00Z:P1D
parameters One or more parameters to be included in this request. Please refer to Available Parameters for a list of valid parameters. List of strings in a format <parameter_name>:<parameter_value> separated by commas ','. t_2m:C,relative_humidity_2m:p
location Geo-coordinates (latitude and longitude) in WGS-84 decimal format. It is possible to query a single point, a point list, a line, or a rectangle. In source mix-obs you can also use an identifier instead of coordinates to specify a station. (see a separate table with Coordinate Description below, or with Station Identifiers) 47.423336,9.377225+50,10 or 50,9_47,10:10x10 or wmo_066810
format The data format of the output. csv,xml, json, png, etc. (see a full list of supported formats below). json

Date/Time Description

Dates and times are specified according to the ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). All times are in UTC. Note that the part containing time specifications (Thh:mm:ss) is optional.

General notation

Example for single point in time: 2015-01-20T18:45Z 20th of January 2015, 18:45 UTC You can specify the time zone by adding the deviation from UTC: 2015-01-20T18:45+01:00 20th of January 2015, 19:45 CET

Specification of time periods

a) Start point + duration You need to define the beginning and the duration of the desired period. A period of date elements always starts with the duration designator P and is followed by the desired period (years (Y), months (M) and days (D)). For periods of time elements the time designator T follows (hours (H), minutes (M) and seconds (S)). Additionally, you have to specify the spacing of the time period - depending on your needs you may want hourly time steps or just daily steps? The spacing is also denoted with P or PT within the command. Example: 2017-05-28T13:00:00ZP5D:PT12H https://api.meteomatics.com/2017-05-28T13:00:00ZP5D:PT12H/t_2m:C/47.4245,9.3767/csv?model=mix

validdate;t_2m:C
2017-05-28T13:00:00Z;26.7
2017-05-29T01:00:00Z;20.9
2017-05-29T13:00:00Z;26.5
2017-05-30T01:00:00Z;18.8
2017-05-30T13:00:00Z;26.1
2017-05-31T01:00:00Z;17.1
2017-05-31T13:00:00Z;22.9
2017-06-01T01:00:00Z;16.4
2017-06-01T13:00:00Z;20.1
2017-06-02T01:00:00Z;16.0
2017-06-02T13:00:00Z;23.2
The definition of the period starts with P and means that the time period starts on the 28th of May 2017 at 13 UTC and lasts 5 days until the 2nd of June 2017 at 13 UTC. After PT follows the spacing of the time period. In this case the time period is divided into steps of 12 hours. The example link fetches temperature data for a given location for the specified time steps.

b) Start point + end point Alternatively, you can specify the start point and the end point and define the desired spacing. Note that the two dates are separated by --. Example: 2017-05-28T13:00:00Z--2017-05-30T13:00:00Z:P1D https://api.meteomatics.com/2017-05-28T13:00:00Z--2017-05-30T13:00:00Z:P1D/t_2m:C/47.4245,9.3767/csv?model=mix

validdate;t_2m:C
2017-05-28T13:00:00Z;26.7
2017-05-29T13:00:00Z;26.5
2017-05-30T13:00:00Z;26.1
This command represents the time period from the 28th of May 2017 at 13 UTC until the 30th of May 2017 at 13 UTC with an interval length of 1 day. Again, the example link fetches temperature data.

List of time points

You can also enter a list of dates and times. The time points have to be comma separated and sorted from the earliest to the latest. Example: 2018-10-20T18Z,2018-10-21T18Z,2018-10-22T18Z https://api.meteomatics.com/2018-10-20T18Z,2018-10-21T18Z,2018-10-22T18Z/relative_humidity_2m:p/47.4245,9.3767/csv?model=mix
validdate;relative_humidity_2m:p
2018-10-20T18:00:00Z;76.7
2018-10-21T18:00:00Z;71.9
2018-10-22T18:00:00Z;70.1
This series of time points would fetch data (relative humidity in this example) for the 20th, the 21st and the 22nd of October 2018 at 18 UTC. Time periods and time points can be mixed, as long as the resulting list of time points is in ascending order. Example: 2018-10-20T18Z,2018-10-21T18ZPT2H:PT20M https://api.meteomatics.com/2018-10-20T18Z,2018-10-21T18ZPT2H:PT20M/relative_humidity_2m:p/47.4245,9.3767/csv?model=mix
validdate;relative_humidity_2m:p
2018-10-20T18:00:00Z;76.7
2018-10-21T18:00:00Z;71.9
2018-10-21T18:20:00Z;78.9
2018-10-21T18:40:00Z;80.4
2018-10-21T19:00:00Z;82.9
2018-10-21T19:20:00Z;82.0
2018-10-21T19:40:00Z;83.7
2018-10-21T20:00:00Z;85.6

Shortcuts

There are several shortcuts available for easier access to recent data. If you use such a shortcut in a command it will expand to full date/time notation. There are two kinds of shortcuts: a) Shortcuts including date and time In order to represent the current date and time you can use now. This command will expand to YYYY-MM-DDThh:mm:ssZ. The shortcut now can be shifted by hours (H), minutes (M) and seconds (S). For example, now+2H, now+30M and now+60S. Example: now--now+5H:PT1H https://api.meteomatics.com/now--now+5H:PT1H/precip_3h:mm/47.4245,9.3767/html?model=mix This example fetches precipitation data for the current time until 5 hours ahead with a step size of one hour. b) Shortcuts including date only: additional specification of time required The shortcuts yesterday, today, tomorrow will expand to YYYY-MM-DD. These shortcuts can be shifted by years (Y), months (M) and days (D). For example, yesterday-1Y, today-3M. tomorrow+2D. Note that you have to add a time specification to these shortcuts. The shortcuts can also be used in a list of time points: yesterdayT18Z,todayT18Z,tomorrowT18Z. Example: yesterdayT00:00Z--todayT12:00Z:PT3H https://api.meteomatics.com/yesterdayT00:00Z--todayT12:00Z:PT3H/relative_humidity_2m:p/47.4245,9.3767/html?model=mix This example fetches relative humidity data from yesterday with a step size of 3 hours.

Interval parameters

If you query parameters, which are averaged or accumulated over a certain time interval, you have to note that all time intervals are right-bounded. This means that a parameter like precip_3h:mm yields the accumulated precipitation sum over the previous 3 hours. So, the value at 18 UTC represents the precipitation sum from 15 UTC until 18 UTC. Examples:

Summary

The following table shows a summary of all described possibilities:
Time Description Example
Single point UTC <isodate> 2015-01-20T18Z - 20th January 2015, 18:00 UTC
Single point local time <isodate> 2015-01-20T14:35+01:00 - 20th January 2015, 14:35, time zone UTC+01:00
Time Period (fixed length) <isodate>P<duration>:P<step> 2017-05-28T13:00:00ZP10D:PT1H (a period of 10 days with a step size of 1 hour) Options for duration and step: 1D: 1 day 1W: 1 week 1M: 1 month 1Y: 1 year T1H: 1 hour T1M: 1 minute T1S: 1 second and combinations of the previous, e.g. 1DT1H
Time Period (fixed end) <isodate>--<isodate>:P<step> 2017-05-28T13:00:00Z--2017-05-30T13:00:00Z:P1D (a period between two dates with step size of 1 day
Comma-separated list of sorted time points and/or periods <isodate or period>,<isodate or period>,...,<isodate or period> 2018-10-20T18Z,2018-10-21T18Z,2018-10-22T18Z, 2018-10-20T18Z,2018-10-21T18ZPT2H:PT20M, 2018-10-20T18ZPT2H:PT20M,2018-10-21T18ZPT2H:PT20M
Shortcut now <shortcut>[<shift>] now, now+1H, now-30M
Shortcuts today, yesterday, tomorrow <shortcut>[<shift>] today, today+1D, yesterday-2D, yesterdayT00:00:00Z--tomorrow+1DT12:00:00Z:PT1H (a period from yesterday at noon (UTC) to the day after tomorrow at noon (UTC) with 1-hour step)

Coordinate Description

Geometry Description Example
Single point
<lat>,<lon> 47.419708,9.358478
Point list
<lat1>,<lon1>+...+<latN>,<lonN> 47.41,9.35+47.51,8.74+47.13,8.22
Line
<start_point>_<end_point>:<number_of_points> 50,10_50,20:100
Polyline
<segment1_start_point>_<segment1_end_point>:<number_of_segment1_points>+<segment2_end_point>:<number_of_segment2_points> The start point of each segment is the end point of the previous segment. 50,10_50,20:100+60,20:10, 47.42,9.37_47.46,9.04:10+47.51,8.78:10+47.39,8.57:10
Rectangle (fixed number of points)
<lat_max>,<lon_min>_<lat_min>,<lon_max>:<number_lons>x<number_lats> 50,10_40,20:100x100
Rectangle (fixed resolution)
<lat_max>,<lon_min>_<lat_min>,<lon_max>:<resolution_lat>,<resolution_lon> 50,10_40,20:0.1,0.1
Rectangle shortcuts
<shortcut>:<resolution_lat>,<resolution_lon> europe:0.1,0.1,north-atlantic:100x100
Postal (Zip) Codes
postal_<country_code><zip_code> Country code refers to ISO3166-1 alpha-2 values postal_CH9014,postal_DE10117,postal_CH9014+postal_DE10117
When working with latitudes and longitudes, please note that their representation in the response will contain at most 6 digits after the decimal point. This allows to represent coordinates with sub-m precision, which significantly exceeds the resolution of most data sources. An example showing the temperature along the train line from St. Gallen via Wil and Winterthur to Zurich with 10 sample points between each two stations: https://api.meteomatics.com/__replace__0T12:00:00Z/t_2m:C/47.42,9.37_47.46,9.04:10+47.51,8.78:10+47.39,8.57:10/csv Please note that following requests require the area requests option:
  • Rectangles
  • Point lists containing more than 100 points
  • Polylines with more than 100 segments
Available shortcuts:
Shortcut Coordinates
world 80,-180_-80,180
global 80,-180_-80,180
Continents
africa 40,-28_-40,+060
asia 80,40_-13,180
australia -8,110_-50,180
europe 67.96,-12_35,30
north-america 72,-170_23,-50
south-america 15,-100_-60,-20
Countries and regions The API features a broad list of country shortcuts.
e.g. switzerland 47.89,5.77_45.74,10.65
e.g. uk 59.48,-10.88_49.83,2.06
many more...
Seas
baltic-sea 66.31,8.31_53.12,31.12
mediterranean-sea 46.25,-6.6_30,36.9
north-atlantic 70,-85_20,20
north-sea 63.33,-5.77_50.58,11.31
Don't hesitate to contact us if you require another country or region.

Weather Station Identifiers

In mix-obs you can use either coordinates as described above or specify stations using WMO, METAR, AMDA or MCH codes:
Identifier Description Example
WMO ID wmo_<wmo_id> wmo_066810 is St. Gallen
METAR ID metar_<metar_id> metar_LSZH is Zurich Airport
AMDA ID amda_<amda_id> amda_P100 is Kahl/Main
MCH ID mch_<mch_id> mch_LUG is Lugano
MM unique ID <mmuid> 1463524709 is Zurich Airport

Available Formats

This is a short description of available output formats. Please refer to the API-Response section for details.
Format Description
csv Semicolon separated values.
xml Hierarchical structure in XML.
json Hierarchical structure in JSON.
png A lossless PNG image of a single time step of a geographical region. Uses a recommended colormap with a fixed scale.
png_<colormap> Same as png above but you can choose a color map from the available colormaps, for example with png_viridis.
geotiff A georeferenced TIFF image for a single time step and area that can be easily displayed in GIS software such as QGIS. Uses a recommended default colormap and scaling.
geotiff_<colormap> As geotiff above, but with a color map from the available colormaps. Example: geotiff_plasma.
netcdf A NetCDF file containing a time series over a geographical region.
html An HTML plot graphically displaying a time series or an interactive png of a domain.
html_map An geographical HTML map showing up to two parameters as a semi-transparent overlay.
grads Grid Analysis and Display System (GrADS)3 plots.

Available Colormaps

Identifier Description WMS Legend Example
blue_magenta Colormap with custom markings for precipitation. The inverted version is magenta_blue without custom markers.
blue_to_red Colormap with fixed parameter dependent scaling. Also exists as an inverted version called red_to_blue.
blues Colormap with fixed parameter dependent scaling.
blues_inverted Inversion of blues.
ceiling_height_segmented Designed for ceiling_height_agl parameters.
dwd_warnings Segmented colormap intended to be used for warn parameters.
gray Colormap with fixed parameter-dependent scaling.
gray_inverted Inversion of gray.
gray_transparent Grayscale from transparent to white.
jet Colormap with fixed parameter-dependent scaling that goes from blue to red with green in between.
jet_inverted Inversion of jet.
jet_segmented A segmented version of jet with 40 steps.
jet_segmented_inverted Inversion of jet_segmented.
lifted_index_global A colormap specifically created to display the subtle changes of the lifted index on a global scale.
lifted_index_global_segmented A segmented version of lifted_index_global.
magenta_blue Inversion of blue_magenta.
periodic Periodic colormap with fixed parameter dependent scaling. Best used for periodic quantities like directions.
periodic_inverted Inversion of periodic.
plasma Colormap with fixed parameter dependent scaling that goes from purple to yellow.
plasma_inverted Inversion of plasma.
prism Colormap with fixed parameter dependent scaling, but without a one-to-one correspondence between values and colors.
prism_inverted Inversion of prism.
radar_log Colormap with fixed parameter dependent logarithmic scaling, developed for displaying precipitation.
radar_segmented An alternative to display precipitation.
reds Colormap with fixed parameter dependent scaling, where the smallest value corresponds to white and the largest one to red.
reds_inverted Inversion of reds.
red_to_blue Inversion of blue_to_red.
red_yellow_green An inverted traffic light, useful e.g. for visibility where lower values correspond to more problematic situations.
seismic Colormap with fixed parameter dependent scaling, similar to blue_to_red but with stronger colors.
seismic_inverted Inversion of seismic.
t_europe Colormap with fixed parameter dependent scaling developed to display temperature in mid-lattitude areas throughout the whole year in pleasant colors.
t_europe_segmented A segmented variant of t_europe.
t_global Colormap with fixed parameter dependent scaling developed to display temperature on the whole globe throughout the whole year, focussing on subtle changes.
t_global_segmented A segmented variant of t_global.
traffic_light From red to green, best suited for warning parameters where low values correspond to higher risks.
traffic_light_inverted From green to red, best suited for warning parameters where high values correspond to higher risks.
viridis Colormap with fixed parameter-dependent scaling, where the smallest value corresponds to blue and the largest value to yellow.
viridis_inverted Inversion of viridis.
visibility_segmented Designed for the visibility:m parameter with transparency for high values.
wave_height_segmented Colormap from blue to red, developed for displaying wave heights.

Optional Parameters

Overview

Optional parameters can be attached to the query string as follows: https://...?option_name=<option_value>&... The following table describes the optional parameters:
Option Description Value Example
source / model This parameter is used to select a specific weather model as source. String. Default: mix ecmwf-ifs or ncep-gfs or ukmo-euro4
temporal_interpolation For some parameters you can specify the temporal interpolation method to be used. (Currently only supported for observational data.) String. Default: best none
vertical_interpolation This method allows the deactivation of the spatial downscaling of the data. This method is only available if explicitly ordered by the customer. String. Default: downscaling is performed none
ens_select When explicitly requesting data from an ensemble model using the 'model' parameter (e.g. ecmwf-ens), you can specify the member or aggregate to return via this parameter. String. Default: member:0 (control run) member:1-50, member:1, median, mean, spread, quantile0.3, quantile0.9
cluster_select For the model ecmwf-ens-cluster, you can specify the cluster to be used. String. No default. cluster:1, cluster:1-6
timeout A timeout (in seconds) after which the API will answer with a timeout message if it hasn't yet finished treating the query. The timeout cannot be increased above its default value. Integer. Default: 300 (30 for WMS/WFS-Queries), Maximum is 300. 10, 60
route Request weather data along a time/space dependent route as specified here. true, false

Model or Source Selection

The data described in the API is based on different models and combined in an intelligent mix so that the best data source is chosen for each time and location. The models can also be queried directly using the optional parameter source or model (they are treated the same). The available models are:

 

Global Weather Forecasting Models

Identifier Description
mix The Meteomatics Mix combines different models and sources into an intelligent blend, such that the best data source is chosen for each time and location. The length of the forecasting period as well as the spatial resolution depends on the model from which the requested parameters originate.
spatial resolution: up to 0.0012° (~90 m)
temporal resolution: up to 5 minutes
lead time: variable
updates per day: variable
ecmwf-ifs The European Center for Medium-Range Weather Forecasts' (ECMWF) Integrated Forecasting System (IFS) is the world's leading atmospheric global circulation model that describes the dynamical evolution of the atmosphere worldwide and is used for medium-range forecasts.
spatial resolution: 0.1° (~7.6 km)
temporal resolution: up to 1 hour
lead time: 10 days (6 and 18 UTC up to 90 hours)
updates per day: 4
ecmwf-ens Model data from the Ensemble Prediction System (EPS) of ECMWF. EPS is a system that is used to predict forecast confidence. Uncertainties in the initial conditions are represented by creating a set of 50 forecasts (ensemble members) with slightly different initial conditions.
spatial resolution: 0.2° (~15.2 km)
temporal resolution: up to 3 hours
lead time: 15 days (6 and 18 UTC up to 144 hours)
updates per day: 4
ecmwf-ens-cluster Daily clustering data of the forecast fields from the ECMWF ensemble data. The clustering is performed according to a set of fixed climatological regimes for each season, computed using 29 years of reanalysis data.
spatial resolution: 1.5° (~114 km)
temporal resolution: 12 hours
lead time: 15 days
updates per day: 2
ecmwf-ens-tc Ensemble model data for tropical cyclones (tropical depressions, tropical storms, hurricanes and typhoons) from ECMWF.
spatial resolution: 0.1° (~7.6 km)
temporal resolution: 6 hours
lead time: 10 days
updates per day: 2
ecmwf-vareps Long-range ensemble forecast by ECMWF.
spatial resolution: 0.4° (~30.4 km)
temporal resolution: up to 3 hours
lead time: 46 days
updates per week: 2
ecmwf-mmsf Long-range seasonal forecast by ECMWF.
spatial resolution: 0.75° (~57 km)
temporal resolution: 6 hours
lead time: 7 months
updates per month: 1
cmc-gem Global Environmental Multiscale model operated by the Canadian Meteorological Center.
spatial resolution: 0.24° (~18.2 km)
temporal resolution: 3 hours
lead time: 6 days
updates per day: 2
ncep-gfs Global Forecasting System by the National Centers for Environmental Prediction (NCEP).
spatial resolution: 0.25° (~19 km)
temporal resolution: 3 hours
lead time: 16 days
updates per day: 4
ncep-gfs-ens Ensemble model of Global Forecasting System by NCEP. The GEFS attempts to quantify the amount of uncertainty in a forecast by generating an ensemble of 21 members, each perturbed from the original observations.
spatial resolution: 0.5° (~38 km)
temporal resolution: 3 hours
lead time: 16 days
updates per day: 4
mm-tides Tidal amplitude simulation by Meteomatics.
spatial resolution: 0.125° (~9.5 km)
temporal resolution: 1 minute
Examples
  • https://api.meteomatics.com/__replace__0T00ZP2D:PT1H/t_2m:C/50,10/html?model=ecmwf-ifs
  • https://api.meteomatics.com/__replace__0T00Z/t_2m:C/switzerland:0.01,0.01/html?source=ukmo-euro4
  • European Weather Models

    Identifier Description
    mm-swiss1k High-resolution model for Switzerland designed by Meteomatics.
    spatial resolution: 0.01° (~760 m)
    temporal resolution: 20 minutes
    lead time: 3 days
    updates per day: 4
    
    ukmo-euro4 European model by the UK MetOffice.
    spatial resolution: 0.04° (~3042 m)
    temporal resolution: 1 hour
    lead time: 54 hours
    updates per day: 4
    
    knmi-hirlam High Resolution Limited Area Model from the Royal Netherlands Meteorological Institute.
    spatial resolution: 0.1° (~7.6 km)
    temporal resolution: 3 hours
    lead time: 2 days
    updates per day: 4
    
    mf-arome Regional model by Meteo France. The resolution of the model depends on the parameter.
    spatial resolution: 0.01° - 0.025° (~760 m - 1900 m)
    temporal resolution: 1 hour
    lead time: 42 hours
    updates per day: 5
    

    Atmospheric pollutants and other chemical compounds

    Identifier Description
    ecmwf-cams Copernicus Atmosphere Monitoring Service by the ECMWF. CAMS is one of six services that form Copernicus (Earth observation program of the European Union). Copernicus offers information services based on satellite Earth observation, in situ (non-satellite) data and modeling. CAMS provides global forecasts of aerosols, atmospheric pollutants, greenhouse gases, stratospheric ozone and the UV-Index.
    spatial resolution: 0.4° (~30.4 km)
    temporal resolution: up to 1 hour
    lead time: 5 days
    updates per day: 2
    
    fmi-silam System for Integrated Modeling of Atmospheric Composition by the Finnish Meteorological Institute for Europe.
    spatial resolution: 0.1° (~7.6 km)
    temporal resolution: up to 1 hour
    lead time: 2 days
    updates per day: 4
    

    Oceanic models

    Identifier Description
    ecmwf-wam The ECMWF Ocean Wave Model is a global model and describes the development and evolution of wind generated surface waves and their height, direction and period. Since it does not dynamically model the ocean itself, it is coupled to the atmospheric forecast model and to the ocean model.
    spatial resolution: 0.125° (~9.5 km)
    temporal resolution: 3 hours
    lead time: 10 days
    updates per day: 2
    
    noaa-hycom The NOAA Hybrid Coordinate Ocean Model provides forecasts for several wave parameters. The hybrid coordinate approach proved to be feasible for handling deep and shallow water regions throughout the annual heating/cooling cycle.
    spatial resolution: 0.08° (~6084 m)
    temporal resolution: 3 hours
    lead time: 7 days
    updates per day: 1
    

    Global Reanalysis

    Identifier Description
    ecmwf-era5 ERA5 is a global atmospheric reanalysis from 1979 to present, continuously updated in real time. ERA5 combines vast amounts of historical observations into global estimates using advanced modeling and data assimilation systems.
    spatial resolution: 0.25° (~19 km)
    temporal resolution: 1 hour
    

    Radar, Satellite and Remote Sensing

    Identifier Description
    mix-radar Composite of precipitation radar from various sources (e.g. NOAA, DWD, ...) including nowcasting.
    spatial resolution: 0.014° (~1 km)
    temporal resolution: 5 minutes
    lead time: 2 hours
    
    mm-heliosat Satellite-based cloud and radiation forecast for Europe by Meteomatics.
    spatial resolution: 0.014° (~1 km)
    temporal resolution: 5 minutes
    lead time: 3 hours
    
    mm-lightning Lightning measurements and nowcast for central Europe.
    temporal resolution: 5 minutes
    lead time: 2 hours
    
    nasa-srtm 90 m resolution topography by NASA.
    spatial resolution: 0.0012° (~90 m)
    spatial extent: latitudes between -60° and 60°
    
    noaa-swpc Geomagnetic activity observation and forecast by NOAA.
    temporal resolution: 3 hours
    lead time: 2 days
    updates per day: 2
    
    mix-satellite Meteomatics satellite composite comprising geostationary satellite images of GOES 16, GOES 17, Himawari8, Meteosat 8, Meteosat 11 and Meteosat MSG. RGB and IR channels are available.
    temporal resolution: 5 - 15 minutes
    spatial resolution: 1 - 3 km
    
    Examples
  • Satellite image
    https://api.meteomatics.com/__replace__0T00Z/sat_ir_039:idx/switzerland:0.01,0.01/html?source=mix-satellite
  • Radar image
    https://api.meteomatics.com/__replace__0T00Z/precip_5min:mm/switzerland:0.01,0.01/html?source=mix-radar
  • Station observations & MOS prognoses

    Identifier Description
    mix-obs Observational data from weather stations (some restrictions to formats might apply). Present data and historical data are available. Further details concerning the selection of stations can be found at Weather Station Identifiers. It is also recommended to specify the treatment of missing data (Behavior on missing or invalid Data).
    mm-mos MOS (Model Output Statistics) based on observational data from weather stations.
    temporal resolution: 1 hour
    lead time: 15 days
    updates per hour: 2
    
    Examples
  • Station query
    http://api.meteomatics.com/2017-10-01T00Z--2017-11-01T00Z:PT1H/t_2m:C,wind_speed_10m:ms/wmo_066810/html?model=mix-obs
  • MOS query
    http://api.meteomatics.com/__replace__0T00ZP5D:PT1H/t_2m:C,wind_speed_10m:ms/wmo_066810/html?model=mm-mos
  • Behavior on missing or invalid Data

    This section describes the options on what to do if data is missing (this currently only applies to source mix-obs): on_invalid parameter:
    Identifier Description
    fail Send an error message as soon as data is missing, instead of the incomplete data. (default)
    fill_with_invalid Replace invalid data by -999 and still send the whole time series.
    Example: https://api.meteomatics.com/__replace__0T00ZP2D:PT1H/t_2m:C/47.43,9.4/csv?model=mix-obs&on_invalid=fill_with_invalid

    Interpolation Selection

    This section describes the different options to select specific interpolations:

    Ensemble Member Selection

    For ensemble models we provide each individual member, as well as mean, median, quantiles, and other basic statistical parameters. They can be queried with the optional parameter 'ens_select'. Possible values are:
    Identifier Description
    member:5 Single Member 5
    member:1-50 All members between 1 and 50
    member:0 Control run (default if nothing else specified)
    mean Arithmetic mean
    median Median
    quantile0.2 The 0.2 quantile (any value between 0 and 1)
    Example: This is the ECMWF ensemble run, for air temperature 2 meters above ground, for 7 days in one hour steps. 15 ensembles are shown. https://api.meteomatics.com/__replace__0T14:00:00ZP7D:PT1H/t_2m:C/47.42,9.37/html?model=ecmwf-ens&ens_select=member:1-15

    Cluster Selection

    For the ensemble cluster products a specific cluster can be queried. The available clusters can be queried using the parameter number_of_clusters:x (refer to Cluster Parameters). Available cluster_select parameters:
    Identifier Description
    cluster:4 Single cluster 4
    cluster:1-6 All clusters between 1 and 6
    Example: https://api.meteomatics.com/__replace__0T00:00:00Z/gh_500hPa:m/72.0000,-14.0000_32.0000,40:100x100/png?model=ecmwf-ens-cluster&cluster_select=cluster:1

    Route Queries

    The route query allows you to query the weather along your travel route. You need to provide a list of times (see time description) and a list of locations (Polyline or Point list may come in handy), both of the same length. The route query has to include the optional flag &route=true. Currently available output formats are csv, json and xml. Examples: The following 3 examples query all the same data in different output formats and with different input specifications, where we are in St. Gallen at 12:00Z, Winterthur at 13:00Z, Zurich at 14:00Z and in Bern at 15:00Z: https://api.meteomatics.com/__replace__0T12Z,__replace__0T13Z,__replace__0T14Z,__replace__0T15Z/t_2m:C,precip_1h:mm,sunshine_duration_1h:min/47.423938,9.3728583+47.499419,8.7265173+47.3819673,8.5306616+46.949911,7.4300993/xml?route=true
    <xml version="1.0" encoding="UTF-8">
    <meteomatics-api-response version="3.0">
     <user>meteomatics</user>
     <dategenerated>2019-05-02T11:45:40Z</dategenerated>
     <status>OK</status>
     <data>
     <location lat="47.4239" lon="9.37286" date="2019-05-02T12:00:00Z">
     <parameter name="t_2m:C">15.7</parameter>
     <parameter name="precip_1h:mm">0.00</parameter>
     <parameter name="sunshine_duration_1h:min">0.0</parameter>
     </location>
     <location lat="47.4994" lon="8.72652" date="2019-05-02T13:00:00Z">
     <parameter name="t_2m:C">15.2</parameter>
     <parameter name="precip_1h:mm">0.00</parameter>
     <parameter name="sunshine_duration_1h:min">0.0</parameter>
     </location>
     <location lat="47.382" lon="8.53066" date="2019-05-02T14:00:00Z">
     <parameter name="t_2m:C">12.8</parameter>
     <parameter name="precip_1h:mm">0.45</parameter>
     <parameter name="sunshine_duration_1h:min">0.0</parameter>
     </location>
     <location lat="46.9499" lon="7.4301" date="2019-05-02T15:00:00Z">
     <parameter name="t_2m:C">13.2</parameter>
     <parameter name="precip_1h:mm">0.00</parameter>
     <parameter name="sunshine_duration_1h:min">0.2</parameter>
     </location>
     </data></meteomatics-api-response>
    Instead of using coordinates explicitly, you can choose your locations by postal code. In this example the output format is json: https://api.meteomatics.com/__replace__0T12Z,__replace__0T13Z,__replace__0T14Z,__replace__0T15Z/t_2m:C,precip_1h:mm,sunshine_duration_1h:min/postal_CH9000+postal_CH8400+postal_CH8000+postal_CH3000/json?route=true
    {
      "version": "3.0",
      "user": "meteomatics",
      "dateGenerated": "2019-04-16T12:20:30Z",
      "status": "OK",
      "data": [
        {
          "station_id": "postal_CH9000",
          "date": "2019-04-16T12:00:00Z",
          "parameters": [
            {
              "parameter": "t_2m:C",
              "value": 12.3
            },
            {
              "parameter": "precip_1h:mm",
              "value": 0.00
            },
            {
              "parameter": "sunshine_duration_1h:min",
              "value": 0.0
            }
          ]
        },
        {
          "station_id": "postal_CH8400",
          "date": "2019-04-16T13:00:00Z",
          "parameters": [
            {
              "parameter": "t_2m:C",
              "value": 13.7
            },
            {
              "parameter": "precip_1h:mm",
              "value": 0.00
            },
            {
              "parameter": "sunshine_duration_1h:min",
              "value": 0.0
            }
          ]
        },
        {
          "station_id": "postal_CH8000",
          "date": "2019-04-16T14:00:00Z",
          "parameters": [
            {
              "parameter": "t_2m:C",
              "value": 12.7
            },
            {
              "parameter": "precip_1h:mm",
              "value": 0.00
            },
            {
              "parameter": "sunshine_duration_1h:min",
              "value": 0.0
            }
          ]
        },
        {
          "station_id": "postal_CH3000",
          "date": "2019-04-16T15:00:00Z",
          "parameters": [
            {
              "parameter": "t_2m:C",
              "value": 9.2
            },
            {
              "parameter": "precip_1h:mm",
              "value": 0.04
            },
            {
              "parameter": "sunshine_duration_1h:min",
              "value": 0.0
            }
          ]
        }
      ]
    }
    If you like to work with csv, just change the output format: https://api.meteomatics.com/__replace__0T12ZPT3H:PT1H/t_2m:C,precip_1h:mm,sunshine_duration_1h:min/postal_CH9000+postal_CH8400+postal_CH8000+postal_CH3000/csv?route=true
    station_id;validdate;t_2m:C;precip_1h:mm;sunshine_duration_1h:min
    postal_CH9000;2019-04-16T12:00:00Z;12.3;0.00;0.0
    postal_CH8400;2019-04-16T13:00:00Z;13.7;0.00;0.0
    postal_CH8000;2019-04-16T14:00:00Z;12.7;0.00;0.0
    postal_CH3000;2019-04-16T15:00:00Z;9.2;0.04;0.0
    
    You can also specify the starting and ending point of your route and the increments in-between to get the data along a line https://api.meteomatics.com/__replace__0T12ZPT1H:PT5M/t_2m:C,precip_10min:mm,wind_speed_10m:ms,elevation:m/47,9_45,7:13/json?route=true or if you like a route consisting of several lines (s. Polylines): https://api.meteomatics.com/__replace__0T12ZPT1H:PT20M,__replace__0T13ZPT2H:PT30M/t_2m:C,wind_speed_10m:ms/47,9_45,7:4+45,8:6/xml?route=true

    Other Examples

    A shipping route example is shown below. It starts in Southhampton, followed by Cherbourg, then Queenstown, and a final stop in New York. Along the route the significant wave height was examined where the red color corresponds to high waves and blue to low wave heights. https://api.meteomatics.com/__replace__0T14:00:00ZP8D:PT1H/significant_wave_height:m,wind_speed_10m:ms,wind_dir_10m:d/50.8978,-1.4241+50.8943,-1.4072+...+40.6719,-74.0826+40.6637,-74.08964/xml?route=true
    <?xml version="1.0" encoding="UTF-8"?>
    <meteomatics-api-response version="3.0">
     <user>meteomatics</user>
     <dateGenerated>2019-05-02T11:42:57Z</dateGenerated>
     <status>OK</status>
     <data>
     <location lat="50.8978" lon="-1.4241" date="2019-04-10T14:00:00Z">
     <parameter name="significant_wave_height:m">-999</parameter>
     <parameter name="wind_speed_10m:ms">4.3</parameter>
     <parameter name="wind_dir_10m:d">46.5</parameter>
     </location>
     <location lat="50.8943" lon="-1.4072" date="2019-04-10T15:00:00Z">
     <parameter name="significant_wave_height:m">-999</parameter>
     <parameter name="wind_speed_10m:ms">4.0</parameter>
     <parameter name="wind_dir_10m:d">47.0</parameter>
     </location>
     ...
     <location lat="40.6719" lon="-74.0826" date="2019-04-18T18:00:00Z">
     <parameter name="significant_wave_height:m">-999</parameter>
     <parameter name="wind_speed_10m:ms">5.9</parameter>
     <parameter name="wind_dir_10m:d">134.8</parameter>
     </location>
     <location lat="40.6637" lon="-74.0896" date="2019-04-18T19:00:00Z">
     <parameter name="significant_wave_height:m">-999</parameter>
     <parameter name="wind_speed_10m:ms">5.5</parameter>
     <parameter name="wind_dir_10m:d">115.2</parameter>
     </location>
     </data>
    </meteomatics-api-response>
    This example represents the highway A1 between St. Gallen and Bern. The temperature along the route is shown in the figure where red corresponds to high values and green to low temperatures. https://api.meteomatics.com/__replace__0T06:30:00Z,__replace__0T06:32:10Z,...,__replace__0T09:32:00Z,__replace__0T09:35:00Z,__replace__0T09:43:00Z/t_2m:C,wind_speed_10m:ms/47.43185,9.37355+47.42024,9.33235+...+46.99636,7.50299+46.95326,7.4563/xml?route=true
    <?xml version="1.0" encoding="UTF-8"?>
    <meteomatics-api-response version="3.0">
     <user>meteomatics</user>
     <dateGenerated>2019-05-02T11:54:37Z</dateGenerated>
     <status>OK</status>
     <data>
     <location lat="47.4318" lon="9.37355" date="2019-04-25T06:30:00Z">
     <parameter name="t_2m:C">13.5</parameter>
     <parameter name="wind_speed_10m:ms">4.6</parameter>
     </location>
     <location lat="47.4202" lon="9.33235" date="2019-04-25T06:32:10Z">
     <parameter name="t_2m:C">12.8</parameter>
     <parameter name="wind_speed_10m:ms">1.8</parameter>
     </location>
     ...
     <location lat="46.9964" lon="7.50299" date="2019-04-25T09:35:00Z">
     <parameter name="t_2m:C">13.2</parameter>
     <parameter name="wind_speed_10m:ms">4.6</parameter>
     </location>
     <location lat="46.9533" lon="7.4563" date="2019-04-25T09:43:00Z">
     <parameter name="t_2m:C">16.6</parameter>
     <parameter name="wind_speed_10m:ms">6.5</parameter>
     </location>
     </data>
    </meteomatics-api-response>

    Polygon Queries

    The polygon query facilitates the selection of arbitrary areas all around the globe. You can query any weather parameter for the selected polygon and obtain mean, median, minimum or maximum values. The query can be either performed for a single point in time or for a time range (see time description). In order to define the polygon, you need to provide the desired vertices (latitude, longitude). You can decide how many vertices are used. Currently available output formats are csv, json and xml.

    The basic structure of the query is:
    api.meteomatics.com/validdatetime/parameters/lat1,lon1_lat2,lon2_..._latN,lonN:aggregate/format?optionals

    Available aggregate options are:

    Identifier Description
    min Find the minimum value
    max Find the maximum value
    mean Compute the mean
    median Compute the median
    mode Compute the mode (most frequent value)

    Examples:

    The following examples demonstrate different applications of the polygon query:

    In the first example a polygon is selected that encompasses the canton of Thurgau. The chosen parameters are temperature, surface pressure and wind speed. This query computes the mean hourly values for the entire polygon from today at 12 UTC until tomorrow 12 UTC. The output format is csv:
    https://api.meteomatics.com/__replace__0T12ZP1D:PT1H/t_2m:C,sfc_pressure:hPa,wind_speed_10m:ms/47.376,8.94493_47.4838,9.0136_47.4903,9.4559_47.6626,9.15642_47.6839,8.67025:mean/csv

    validdate;t_2m:C;sfc_pressure:hPa;wind_speed_10m:ms
    2019-05-15T12:00:00Z;9.7;959.7;8.3
    2019-05-15T13:00:00Z;9.9;959.4;8.5
    2019-05-15T14:00:00Z;9.8;959.1;8.6
    2019-05-15T15:00:00Z;9.4;959.0;8.3
    2019-05-15T16:00:00Z;8.6;959.1;7.9
    2019-05-15T17:00:00Z;7.7;959.4;7.3
    2019-05-15T18:00:00Z;6.7;959.0;6.5
    2019-05-15T19:00:00Z;5.6;959.2;5.5
    2019-05-15T20:00:00Z;5.0;959.1;5.1
    2019-05-15T21:00:00Z;4.5;959.0;5.1
    2019-05-15T22:00:00Z;4.2;958.5;4.7
    2019-05-15T23:00:00Z;4.0;957.9;4.7
    2019-05-16T00:00:00Z;4.0;957.4;4.5
    2019-05-16T01:00:00Z;4.2;956.8;4.8
    2019-05-16T02:00:00Z;4.1;956.2;4.8
    2019-05-16T03:00:00Z;4.1;955.6;4.8
    2019-05-16T04:00:00Z;4.0;955.8;4.7
    2019-05-16T05:00:00Z;4.0;955.7;4.5
    2019-05-16T06:00:00Z;4.4;955.5;4.5
    2019-05-16T07:00:00Z;5.3;955.0;4.4
    2019-05-16T08:00:00Z;6.2;954.5;4.4
    2019-05-16T09:00:00Z;7.2;954.0;4.1
    2019-05-16T10:00:00Z;8.3;953.7;3.6
    2019-05-16T11:00:00Z;9.2;953.3;3.3
    2019-05-16T12:00:00Z;10.1;952.8;2.7
    

    The second example demonstrates the selection of two polygons for the same parameters as in the first example. An aggregation method has to be supplied for each polygon. The commands for the single polygons are connected by a + sign. The polygon of the first example is selected two times, but each with a different aggregation method:
    https://api.meteomatics.com/__replace__0T12ZP1D:PT1H/t_2m:C,sfc_pressure:hPa,wind_speed_10m:ms/47.376,8.94493_47.4838,9.0136_47.4903,9.4559_47.6626,9.15642_47.6839,8.67025:mean+47.376,8.94493_47.4838,9.0136_47.4903,9.4559_47.6626,9.15642_47.6839,8.67025:max/csv

    station_id;validdate;t_2m:C;sfc_pressure:hPa;wind_speed_10m:ms
    polygon1;2020-05-07T12:00:00Z;17.0;961.8;3.2
    polygon1;2020-05-07T13:00:00Z;17.9;961.4;2.8
    polygon1;2020-05-07T14:00:00Z;18.4;961.0;2.3
    polygon1;2020-05-07T15:00:00Z;18.6;960.7;1.9
    polygon1;2020-05-07T16:00:00Z;18.5;960.5;1.7
    

    In the third example two polygons, in this case rectangles, are selected that are located in the Netherlands/Germany and Switzerland. Note that you can unite two polygons with U. The chosen parameter is the elevation of the terrain and the aggregation method is min. So, the result of this query is the minimum elevation within the combined polygons. The output format is xml. https://api.meteomatics.com/__replace__0T12Z/elevation:m/52.2,6.6_52.2,7.6_53.2,7.6_53.2,6.6U45.9,7.56_45.9,7.92_46.15,7.92_46.15,7.65:min/xml

    <?xml version="1.0" encoding="UTF-8"?>
    <meteomatics-api-response version="3.0">
      <user>meteomatics</user>
      <dateGenerated>2019-05-15T12:33:30Z</dateGenerated>
      <status>OK</status>
      <data>
        <parameter name="elevation:m">
          <location station_id="polygon1">
            <value date="2019-05-15T12:00:00Z">-5.0</value>
          </location>
        </parameter>
      </data>
    </meteomatics-api-response>

    The fourth example shows how to cut out one polygon from another. The vertices of the larger polygon are defined first and then those of the cutout polygon (turquoise colored rectangle). The two commands are separated by D, denoting difference. So, the second polygon is excluded from the first polygon. In this example, Mount Kenya is excluded from the selection. Also, additional polygons could be cut out from the surrounding polygon. The result of this query is the maximum elevation of the area around Mount Kenya. The file format is csv. https://api.meteomatics.com/__replace__0T12Z/elevation:m/0.3873,36.9388_-0.791,36.9388_-0.791,37.837_0.3873,37.837D0.0385,37.208_-0.3214,37.208_-0.3214,37.56_0.0385,37.56:max/csv

    validdate;elevation:m
    2019-05-15T12:00:00Z;3031.0
    

    Meta Requests

    Get Latest Initial Time

    You can find out when the data was computed (which model run the data originated from) using this query:
    https://api.meteomatics.com/get_init_date?model=<model>&valid_date=<validdatetime>&parameters=<parameter_list>
    https://api.meteomatics.com/get_init_date?model=ecmwf-ifs&valid_date=__replace__0T19:00:00ZP1D:PT6H&parameters=t_2m:C,relative_humidity_2m:p Reply:
    validdate;initdate_t_2m:sql;initdate_relative_humidity_2m:sql
    2017-06-22T19:00:00Z;2017-06-21T12:00:00Z;2017-06-21T12:00:00Z
    2017-06-23T01:00:00Z;2017-06-21T12:00:00Z;2017-06-21T12:00:00Z
    2017-06-23T07:00:00Z;2017-06-21T12:00:00Z;2017-06-21T12:00:00Z
    2017-06-23T13:00:00Z;2017-06-21T12:00:00Z;2017-06-21T12:00:00Z
    2017-06-23T19:00:00Z;2017-06-21T12:00:00Z;2017-06-21T12:00:00Z

    Get Available Time Range

    The valid dates that are available within the API can be queried with using:
    https://api.meteomatics.com/get_time_range?model=<model>&parameters=<parameter_list>
    Example: https://api.meteomatics.com/get_time_range?model=ecmwf-ifs&parameters=global_rad:W,t_2m:C Response:
    parameter;min_date;max_date
    global_rad:W;2013-12-30T00:00:00Z;2017-07-01T12:00:00Z
    t_2m:C;2013-12-30T00:00:00Z;2017-07-01T12:00:00Z

    Get Color Maps

    The colormaps described here can be queried by using: https://api.meteomatics.com/get_colormap?paramter=<parameter>&style=<style>&format=<format> The parameters of a get_colormap request a as follows:
    Option Description Example
    <parameter> A weather parameter. Please refer to Available Parameters for a sorted list of valid parameters. fresh_snow:cm
    <style> The colormap you want to get the numerical values for. The list of available colormaps is here. If style= is omitted from a get_colormap request, then a default value for <style> is provided depending on the requested parameter. jet_segmented
    <format> The output data format. CSV is the only available output format. csv
    Example of a get_colormap request with all the three parameters explicitly defined: https://api.meteomatics.com/get_colormap?parameter=fresh_snow:cm&style=jet_segmented&format=csv Example of a get_colormap request with only two parameters explicitly defined. In this case,<style> is automatically set to jet: https://api.meteomatics.com/get_colormap?parameter=fresh_snow:cm&format=csv Example of generated csv file: Value;Hex Color 160;#870000FF 156;#9B0F14FF 152;#AC1E32FF ... 12;#1928B9FF 8;#0519A0FF 4;#000A6EFF

    Find Station

    You can get a list of available weather stations, such that you can decide which one you are interested in:
    https://api.meteomatics.com/find_station?<list of conditions>
    You will get a sorted list of stations matching your conditions. Available conditions:
    Identifier Description Example
    location Coordinates: location=<lat>,<lon>, or bounding box location=<lat_max>,<lon_min>_<lat_min>,<lon_max> location=47.3,9.3, location=47.3,9.3_40,10, location=germany
    elevation in meters ASL: elevation=<elevation> elevation=2500
    parameters parameters=<comma separated parameter list> parameters=t_2m:C,wind_speed_10m:ms
    startdate the earliest time you are interested in: startdate=<iso timestamp> startdate=2017-10-01T00Z
    enddate the latest time you are interested in: enddate=<iso timestamp> enddate=2017-11-01T00Z
    Example: https://api.meteomatics.com/find_station?location=47.3,9.3&elevation=2500 Response:
    Station Category;Station Type;ID Hash;WMO ID;Alternative IDs;Name;Location Lat,Lon;Elevation;Start Date;End Date
    SYNOP;SYNA;1723840649;066800;;Säntis;47.25,9.35;2500m;2017-01-01T00:00:00Z;2017-11-23T07:00:00Z
    SYNOP;SYNO;625541767;066860;;Vorab-Talstation;46.88,9.18;2566m;2017-01-01T00:00:00Z;2017-11-23T07:00:00Z
    SYNOP;SYNO;1550441974;067850;;Crap Sogn Gion;46.83,9.22;2226m;2017-01-01T00:00:00Z;2017-11-23T07:00:00Z
    SYNOP;SYNO;2311361043;067800;;Weissfluhjoch;46.83,9.82;2667m;2017-01-01T00:00:00Z;2017-11-23T07:00:00Z
    ...

    Show User Statistics

    You can check how many queries you already sent and how your limits are defined by calling https://api.meteomatics.com/user_stats The same in a machine readable format: https://api.meteomatics.com/user_stats_json

    Footnotes

    1. Representational state transfer: http://en.wikipedia.org/wiki/Representational_state_transfer
    2. ISO-8601 date format: http://www.iso.org/iso/catalogue_detail?csnumber=40874, http://en.wikipedia.org/wiki/ISO_8601
    3. Grid Analysis and Display System (GrADS): http://en.wikipedia.org/wiki/GrADS