API Request

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/<time>/<parameters>/<location>/<format>?<optionals>

If you are sending a POST request, which is recommended for large URL lengths (>1000 characters), follow this notation:

URL: https://api.meteomatics.com/<time>/
Post-Body: <parameters>/<location>/<format>?<optionals> in plain text

Note:

Required Parameters

The following table describes all required parameters for the URL:

Option Description Value Example
time A date or date range to retrieve the weather forecast for. (see separate table with 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, wms, etc. (see a full list of supported formats below). json

Time Description

Time is entered in ISO-8601-format2. The standard time point is in UTC and is entered as „2015-01-20T18Z“ for 20th January 2015, 18:00 UTC. For time periods enter a start point, a duration and the time interval between the time steps. The duration and the interval starts with the capital letter P. For example a period of 10 days with a step size of 1 hour looks like: „2017-05-28T13:00:00ZP10D:PT1H“. Alternatively enter an end time point instead of a duration. Start and end time point are separated with two hyphens, the time interval starts with a capital letter P. For example a period between two dates with step size of 1 day looks like: 2017-05-28T13:00:00Z—2017-05-30T13:00:00Z:P1D.

You may also combine multiple time points and spans into a comma-separated sorted list, for example 2018-10-20T18Z,2018-10-21T18Z,2018-10-22T18Z if you are interested specifically in fetching data for 18Z on the 20th, 21st and 22nd of October. You can mix time spans and time points as you like, e.g. as 2018-10-20T18Z,2018-10-21T18ZPT2H:PT20M, as long as the resulting list of times is non-decreasing.

There are shortcuts available for an easier access of near time data. Shortcuts always expand based on UTC: now expands to a complete date and time in the format YYYY-MM-DDTHH:MM:SSZ, it can be shifted by hours, minutes or seconds by inputting shortcuts such as now+2H, now+30M, and now+600S. The shortcuts yesterday, today and tomorrow expand to dates in the format YYYY-MM-DD; they can be shifted by years, months, or days with shortcuts such as yesterday-1Y, today-3M, and tomorrow+2D. These shortcuts may also be used in a time list, say yesterdayT18Z,todayT18Z,tomorrowT18Z.

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

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/2017-10-25T12: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 (see https://shop.meteomatics.com/api.html):

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

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. You can choose different color maps according to Available Colormaps
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
png Default, uses the Jet colormap and relative scaling (smallest value within the image corresponds to blue, largest value in the image corresponds to red). Please note that for WMS, the default colormap is according to png_default and not Jet.
png_default Uses a recommended colormap and fixed parameter-dependent scaling. That is the default for WMS.
png_jet Colormap with fixed parameter-dependent scaling that goes from blue to red with green in between. Exists as an inverted variant under png_jet_inverted. elevation:m
png_jet_segmented A segmented version of jet with 40 steps. Exists as an inverted variant under png_jet_segmented_inverted. elevation:m
png_blue_to_red Colormap with fixed parameter dependent scaling going from blue to white to red. Also exists as an inverted version called png_red_to_blue. t_2m:C
png_blue_magenta Colormap with custom markings for precipitation. It starts with a light blue, transitions into to blue and then goes into magenta. The inverted version is png_magenta_blue without custom markers. precip_5min:mm
png_blues Colormap with fixed parameter dependent scaling, where the smallest value corresponds to white and the largest one to blue. Has an inverted version accessible through png_blues_inverted. relative_humidity_2m:p
png_gray Colormap with fixed parameter-dependent scaling, where the smallest value corresponds to black and the largest value to white. Has an inverted version called png_gray_inverted. medium_cloud_cover:p
png_periodic Periodic colormap with fixed parameter dependent scaling. Best used for periodic quantities like directions. The inverted version can be accessed through png_periodic_inverted. wind_dir_10m:d
png_plasma Colormap with fixed parameter dependent scaling that goes from purple to yellow. Also exists as an inverted version under png_plasma_inverted. global_rad:W
png_prism Colormap with fixed parameter dependent scaling, but without a one-to-one correspondence between values and colors. Inverted variant: png_prism_inverted. wind_dir_10m:d
png_reds Colormap with fixed parameter dependent scaling, where the smallest value corresponds to white and the largest one to red. Has an inverted version accessible through png_reds_inverted. global_rad:W
png_seismic Colormap with fixed parameter dependent scaling, similar to png_blue_to_red but with stronger colors. Inverted version: png_seismic_inverted. t_2m:C
png_viridis Colormap with fixed parameter-dependent scaling, where the smallest value corresponds to blue and the largest value to yellow. The inverted version is png_viridis_inverted. elevation:m

Optional Parameters

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

Identifier Description
mix Intelligent mix of various models by Meteomatics
mix-radar Composite of precipitation radar from various sources (e.g. NOAA, DWD, ...)
mix-obs Observational weather stations' data. (Some restrictions to formats might apply.)
cmc-gem Global Environmental Multiscale model by the Canadian Meteorological Centre
ecmwf-cams Copernicus Atmosphere Monitoring Service by the European Centre for Medium-Range Weather Forecasts
ecmwf-ens Ensemble model data from the European Centre for Medium-Range Weather Forecasts
ecmwf-ens-cluster Ensemble cluster model data from the European Centre for Medium-Range Weather Forecasts
ecmwf-ens-tc Ensemble model data for Tropical Cyclones from the European Centre for Medium-Range Weather Forecasts
ecmwf-era5 ERA5 reanalysis model data from the European Centre for Medium-Range Weather Forecasts
ecmwf-era-interim ERA-Interim reanalysis model data from the European Centre for Medium-Range Weather Forecasts
ecmwf-ifs High resolution Integrated Forecast System by the European Centre for Medium-Range Weather Forecasts
ecmwf-mmsf 7 month seasonal forecast by the European Centre for Medium-Range Weather Forecasts
ecmwf-vareps 46 days long-range ensemble forecast by the European Centre for Medium-Range Weather Forecasts
ecmwf-wam Oceanic model forecast by the European Centre for Medium-Range Weather Forecasts
fmi-silam System for Integrated modeLling of Atmospheric coMposition by the Finnish Meteorological Institute
knmi-hirlam High Resolution Limited Area Model from the Netherland Weather Service
meteosat-msg Meteosat 2nd Generation imagery for Europe
mf-arome European model by Meteo France
mm-heliosat Satellite-based cloud and radiation forecast for Europe by Meteomatics
mm-lightning Lightning measurements and nowcast
mm-swiss1k 1km model for Switzerland by Meteomatics
mm-mos MOS (Model Output Statistics) based on observational weather stations' data. (Available Parameters)
mm-tides Tidal amplitude simulation
nasa-srtm 90m resolution topography by NASA
ncep-gfs Global Forecasting System by the National Centers for Environmental Prediction
ncep-gfs-ens Ensemble Model of Global Forecasting System by the National Centers for Environmental Prediction
noaa-hycom NOAA Hybrid Coordinate Ocean Model
noaa-swpc NOAA Geomagnetic Activity Observation and Forecast
ukmo-euro4 4km European model by the UK MetOffice

Examples:

https://api.meteomatics.com/insert_current_dateT00ZP2D:PT1H/t_2m:C/50,10/html?model=ecmwf-ifs

https://api.meteomatics.com/insert_current_dateT00ZP2D:PT1H/t_2m:C/50,10/html?source=ukmo-euro4

Interpolation Selection

This section describes the different options to select specific interpolations:

temporal_interpolation parameter:

Identifier Description
best The best suiting interpolation is chosen for each parameter (default).
none No temporal interpolation is applied, missing values are replaced by -999 (this is currently only supported in source mix-obs).

Example:

https://api.meteomatics.com/2017-01-23T00ZPT3H:PT5M/t_2m:C/47.43,9.4/csv?model=mix-obs&temporal_interpolation=none

Behavior on Invalid Data

This section discribes 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/insert_current_dateT00ZP2D:PT1H/t_2m:C/47.43,9.4/csv?model=mix-obs&on_invalid=fill_with_invalid

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/insert_current_dateT14: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/insert_current_dateT00:00:00Z/gh_500hPa:m/72.0000,-14.0000_32.0000,40:100x100/png?model=ecmwf-ens-cluster&cluster_select=cluster:1

Route Queries

If you are interested in querying weather data along a route, you will need provide a list of times and locations (which may not be in grid format) of equal length according to the above rules and the optional ...&route=true. The currently available formats are csv, json and xml, but please note that for xml and json the file format will have a hierarchy differing from non-route queries. For example responses please refer to API-Response.

Examples:

https://api.meteomatics.com/todayT12ZPT1H:PT5M/t_2m:C,precip_10min:mm,wind_speed_10m:ms,elevation:m/47,9_45,7:13/json?route=true

https://api.meteomatics.com/todayT12ZPT1H:PT20M,todayT13ZPT2H:PT30M/t_2m:C,wind_speed_10m:ms/47,9_45,7:4+45,8:6/xml?route=true

Meta Requests

Get latest init 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=<valid_dates>&parameters=<parameter_list>

Example:

https://api.meteomatics.com/get_init_date?model=ecmwf-ifs&valid_date=insert_current_dateT19: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

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): https://en.wikipedia.org/wiki/GrADS

News