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 textNote:
- 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 |
|---|---|---|---|
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 dayOptions 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):
- 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. 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/todayT00ZP2D:PT1H/t_2m:C/50,10/html?model=ecmwf-ifs
https://api.meteomatics.com/todayT00ZP2D: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:
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:
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.
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:
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:
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>¶meters=<parameter_list>Example:
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>¶meters=<parameter_list>Example:
https://api.meteomatics.com/get_time_range?model=ecmwf-ifs¶meters=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:00ZFind 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
- Representational state transfer: http://en.wikipedia.org/wiki/Representational_state_transfer
- ISO-8601 date format: http://www.iso.org/iso/catalogue_detail?csnumber=40874, http://en.wikipedia.org/wiki/ISO_8601
- Grid Analysis and Display System (GrADS): https://en.wikipedia.org/wiki/GrADS