In Q2 2024, DMI will migrate its forecast models to a new super computer and upgrade our weather model HARMONIE. This will introduce some breaking changes, read the full announcement here.
Our forecast data EDR API is an API created to make it easier to get specific parts of forecast data. The underlying data is exactly the same as the Forecast Data STAC-API (except that HARMONIE ML forecasts are not included). However with this API, it is possible to get smaller parts of forecast data without having to get whole forecast files.
Click here for Swagger - Interactive API explorer
To execute calls the service input your api-key by clicking the "Authorize" button in Swagger
| Getting a parameter for a specific point |
Description: Returns the temperature-0m parameter for the position closest to CRS84 coordinate 12.561E 55.715N. For the specific location returned look into the response. The default format is CoverageJSON. The model queried is the latest harmonie_dini_sf.
Description: Returns the temperature-0m parameter for the position closest to CRS84 coordinate 12.561E 55.715N. For the specific location returned look into the response. Format here is GeoJSON - as requested by the f parameter. |
| Getting parameters for an area |
Description: Returns the water-temperature and salinity parameters for the area specified by the CRS84 bounding box with lower left at 11E, 55N and top right at 12E, 56N. Format is in CoverageJSON. |
| Listing which forecast models types are available |
Example: https://dmigw.govcloud.dk/v1/forecastedr/collections?api-key=<api-key> Description: Returns the a list of models that are available, including what area they cover, what CRS they are defined in, what parameters are available and their meaning, output formats and queries that can be executed (like /position and /cube above). |
| Listing which forecast models instances / runs are available |
Example: https://dmigw.govcloud.dk/v1/forecastedr/collections/dkss_nsbs/instances?api-key=<api-key> Description: Returns a list of model runs (instances). Each forecast is executed periodically and result is available for querying in this service. |
| Querying a specific model instance |
Description: Executes the query on a specific model run (instance). If instance is not used query will run on the latest available model (as in above queries). Note that the specific instance in the example above will not be available - query for currently available instances using the /instances endpoint |
| Specifying the range of forecast steps to return. |
Description: Limits the forecast steps returned to be within the given time range in the datetime argument. |
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
12.55015598605009,
55.70856572594708
]
},
"properties": {
"temperature-2m": 280.9348,
"wind-speed-10m": 6.067077938048905,
"wind-speed": 6.0671906,
"step": "2023-10-26T06:00:00.000Z",
"wind-dir-10m": 64.22486331026232
}
}
]
}
Example: https://dmigw.govcloud.dk/v1/forecastedr/collections
Description: Will return all available collections in the API.
The Weather Model (HARMONIE) can be found in the collections:
for the North Eastern Area (Denmark and surrounding area) in the collections starting with harmonie_dini and Greenland in the collections starting with harmonie_ig.
The Wave Model (WAM) can be found in the collections:
for area Danish Waters, North Atlantic and North Sea-Baltic, respectively.
The Storm Surge Model (DKSS) can be found in the collections:
for the area North Sea Baltic Sea, Inner Danish Waters, Wadden Sea, Roskilde/Isefjord, Limfjord and Little Belt, respectively.
WARNING: Deprecated, will be removed in the future
Please use /collections/<collection id>/instances/<instance id> instead
Where <collection Id> can be one of the collections listed above and <instance Id> is the id of the modelrun
This the applies to both the /collections/<collectionId>/<query> and /collections/<collectionId>/instance/<instanceId>/<query> endpoints
where <query> can either by cube or position.
| collection id |
The forecast model to query. Matches the names used in the forecastdata service except the ML models (harmonie_dini_ml and harmonie_ig_ml) models which are not included in this service. List of models/collections can be retrieved using https://dmigw.govcloud.dk/v1/forecastedr/collections Example: Returns data from the HARMONIE IG SF model. |
| instance Id |
Narrow the search to a specific model run, which means the beginning of a specific forecast. These forecasts are run (ie. calculated) each day at the hours 00, 06, 12 and 18 in UTC, and for HARMONIE also at 03, 09, 15 and 21 UTC. API only retain data covering the last 24 hours. Model runs that started more than 24 hours ago are therefore out of circulation. If instance id is not used the query will be executed on the latest complete model. Example: Returns data from the model run which begins at 14/03/2023 00:00:00 UTC. |
Where <query> can either by cube or position.
This the applies to both the /collections/<collection name>/<query> and /collections/<collection name>/instances/<instanceId>/<query> endpoints.
| parameter-name |
Specify which parameter names to return. Multiple parameter names are separated by comma. parameter-names are unique per collection and the available parameter-names can be shown using the /collections/{collectionId} endpoint. In addition to the parameter-names listed above, technical parameter names can be used for those parameters that are not defined/documented properly yet. For information on these, please see: parameters Examples: Return parameters temperature-0m, cloudcover and relative-humidity for the point closest to the CRS84 coordinates lon=12.561 lat=55.715.
Returns information on all collections (information can also be retrieved from a single collection using /collections/{collectionId}), including parameter-names and query metods and CRS. Technical parameter names are not included in this list - for a list of technical parameter names look here, here, here or here.
Return the parameter with technical parameter name of 0-6-5-0.0-103 from the model harmonie_dini_sf.
|
| datetime |
Narrow the search for forecast steps to a date range or a specific date. The range can be open on one side. If that is the case simply use ".." (double-dot) in stead of the an actual date for the open side. If only one date is supplied, then only exactly matching dates will be included. If both sides of the range are open, simply omit the datetime parameter. According to the OGC specification (which the EDR specification refers to) both ends of the range are inclusive
According to RFC3986 the plus sign "+" must be URL encoded: Try one of the examples and observe the encoded "+" sign. Danish summer time is UTC+2 (GMT+2)
Examples: Return forecast data (temperature-0m) for the forecast steps at UTC 2018-02-12 at midnight and UTC 2018-03-18 at midnight. Both dates are inclusive.
Return forecast data within the dates 2019-01-01 at midnight and 2020-01-01 at midnight in Danish summer timezone. Both dates are inclusive.
Return forecast data from the date 2019-01-01 at midnight (Danish summer timezone) and after
Return forecast data from before or matching the date 2019-01-01 at midnight (Danish summer timezone).
Return forecast data matching the date 2019-01-01 at midnight (Danish summer timezone) |
| bbox (/cube) |
Narrow the search to only include data within the specified bounding box. A bounding box (usually shortened to bbox) is an area defined by two longitudes and two latitudes, where:
They follow the standard format of: bbox = Southwesterly point (lon,lat) followed by northeasterly point (lon, lat) This bbox tool may be useful. Please use a decimal point as the decimal separator, e.g. 1.99 (and not 1,99) Note that for some models / data, the point might be within the bounding box but the parameter is undefined/null. An example would be the DKSS and WAM sea models, where their model area covers a land area but all values over land are empty. Example: Return forecast data from within the bounding box having the Southwesterly point of 11, 55 and northeasterly point of 12, 56 |
| coords (/position) |
Narrow the search to only include data from the point closest to the specified coords. The service currently only supports querying for a single position using longitudes and latitudes, where:
They follow the standard format of: coords = POINT(longitude latitude) Note that this returns the closest point and that the point therefore can have a different geography than the given point. Example: the given point is over sea and returned point is over land. Suggest using a bbox query for returning multiple points to determine most suitable point (or interpolating from several points). Please use a decimal point as the decimal separator, e.g. 1.99 (and not 1,99) Not that longitude and latitude are seperated by space and not comma. Note that for some models / data, the point might returned with parameters undefined/null. An example would be the DKSS and WAM sea models, where their model area covers a land area but all values over land are empty. For more specific details on the geography, please use “land-percent” (for HARMONIE based models). Example: Return forecast data from the point closest to 12.561, 55.715. Depending on model queried and coordinates used the point might be considered far from the returned point - the service will still return the closest match. |
| crs |
Specify the coordinate reference system - this applies to both what CRS the bbox and coords coordinates are in, but also the data returned from the query. For detailed information on CRS see here. For DKSS and WAM only crs84 is supported, for HARMONIE DINI/IG crs84 is supported for position queries and when GeoJSON is used as output format. For area queries in CoverageJSON only crs=native is supported. Note that the native CRS for harmonie_dini and harmonie_ig are different. Examples: Return forecast data as CoverageJSON with coords coordinates and return data in CRS84 coordinate reference system.
Return forecast data as CoverageJSON with coords coordinates and return data in the harmonie_dini_sf native coordinate reference system. |
| f |
Specify the return format - either CoverageJSON (default) or GeoJSON. Some queries cannot be returned as CoverageJSON (see here) and will return an HTTP error, whereas GeoJSON is valid for all queries. Examples: Return forecast data as CoverageJSON.
Return forecast data as GeoJSON. |
This is an experimental endpoint that returns data for a list of parameters in GRIB format. It is not possible to filter by area - the entire model area is always returned.
Return format is GRIB v1 or GRIB v2 depending on which collection is queried - Harmonie is GRIB v2, other collections are GRIB v1.
The model data returned is the same as can be downloaded (but not filtered) in the forecast data STAC-API but allows for smaller download sizes due to parameter filtering.
| parameter-name | Same as parameter-name in /cube or /position |
| datetime | Same as datetime in /cube or /position |
No other query selection parameters are supported, the entire GRIB message is returned.
There is also a /collections/<collection name>/instances/<instanceId>/grib endpoint for querying a specific model run.
Examples:
Return complete forecast for the parameter temperature-2m
Return 3 hours of forecast for the parameters temperature-2m and temperature-50m
This is an experimental endpoint that works the same as the …/cube endpoint but is less strict in what it can return. The EDR specification limits what can be returned when the data returned it not in the queried CRS. For models that are not natively CRS84 (DINI and IG) this limits the amount of data that can be returned.
This endpoint allows querying with CRS84 and get data in a grid that is not aligned with CRS84. This is useful for NetCDF formats where the projection information is encoded into the returned data.
To avoid doing the projection two special “parameter-names” have been introduced: latitude and longitude, which specify the CRS84 latitude and longitude for each point returned. These do not change, so please query only for these once with one timestep and cache the reponse to save response time and bandwidth.
There is also a /collections/<collection name>/instances/<instanceId>/bbox endpoint for querying a specific model run.
Examples:
Return complete forecast for the parameter temperature-2m, for the CRS84 bounding box with southwesterly point (10, 51) and northeasterly point (20, 60)
Return a single forecast step for temperature-2m with the latitude and longitude “parameters”. Please cache latitude and longitude and reuse those for queries that use the same bbox. Note that some values are null because they are outside the given bbox.
The API is a OGC EDR API - Features service and follows this standard as documented here: https://ogcapi.ogc.org/edr/
The service response is CoverageJSON (the default), GeoJSON or NetCDF and can be specified using the f parameter. Each format has its advantages; CoverageJSON is much more compact than GeoJSON for large amounts of data whereas GeoJSON is a simpler format with many supporting tools. NetCDF is the most compact but is a binary format.
The standard for CoverageJSON is maintained here: https://github.com/opengeospatial/CoverageJSON and GeoJSON is documented in https://www.rfc-editor.org/rfc/rfc7946. These references should be used to understand the format in general and below are important points relevant to this service only.
https://covjson.org/ also includes links to other CoverageJSON related resources.
CoverageJSONs efficient grid format describes data as a n-dimentional grid. This service currently always returns a 3 dimentional grid with axes for time (t) and a 2d-space (x,y) for all queries. For /position queries there is only 1 x and 1 y value.
The harmonie_dini and harmonie ig have a lambert coordinate system and when returning data with CRS=native, we are currently not able to return the CRS for the x and y coordinates, because we cannot encode the lambert/rotated grid CRS parameters in a format required by CoverageJSON. Therefore the x and y axis are missing from the references section:
"referencing" : [ { "coordinates" : [ "t" ], "system" : { "type" : "TemporalRS", "calendar" : "Gregorian" }} ] |
The x and y coordinates have to be interpreted as being in a lambert grid - see CRS. When returning data with CRS=crs84 and for models already in CRS84, x and y axis are referenced correctly:
"referencing": [ { "coordinates": [ "t" ], "system": { "type": "TemporalRS", "calendar": "Gregorian" } }, { "coordinates": [ "x", "y" ], "system": { "type": "GeographicCRS", "id": "http://www.opengis.net/def/crs/OGC/1.3/CRS84" } }] |
Currently the z-axis is "encoded" within the parameter-name. For example, if a temperature is requested for a specific height, it will be returned through different parameter-names; example: temperature-0m, temperature-2m, temperature-50m, etc. It is expected that when support for the z-parameter is implemented this can be requested with parameter-name=temperature and z=0m,2m,50m and a z-axis will appear (making it a 4 dimentional grid).
The CoverageJSON "ranges" section holds the data returned. See data types and format in the /v1/forecastedr/collections/<collectionId> endpoint or here, here or here (depending on model). Special care should be taken with the wind u/v values as they may have to be rotated before use (see Rotation).
The GeoJSON format returns a GeoJSON feature collection with a GeoJSON feature for each point and step time. The step time is in a property called "step" and is a RFC3339 encoded timestamp for which forecast step this GeoJSON object is for. The data returned is in the GeoJSON properties values with parameter-name as key. Because GeoJSON objects do not have any grid like structure, all data can returned in a different CRS and therefore also be converted (rotated).
The CRS is not encoded inside the GeoJSON feature collection.
The NetCDF format is described here. It has much in common with the CoverageJSON format (so same limitations apply) in that is describes arrays of data, but is a binary format. It has support for describing the projections of the returned data so tooling should be able to correctly display the returned data - we have tested this with QGIS.
The EDR service has a concept of 'Instance', which is described in https://docs.ogc.org/is/19-086r5/19-086r5.html#toc26 . 'Instance' is in this service used to point to a specific forecast execution run. At DMI each forecast is executed periodically and sent to this service and a number of these forecasts are available for queries. If the instance is not part of the query (like https://dmigw.govcloud.dk/v1/forecastedr/collections/harmonie_dini_sf/position?...) the newest forecast model run is used and if instance is part of the query (like https://dmigw.govcloud.dk/v1/forecastedr/collections/harmonie_dini_sf/instances/2023-03-14T000000Z/position...) then that specific forecast model run is used. If the forecast model run is not available a HTTP client error 404 is returned.
The WAM and DKSS models are stored in CRS84 coordinates and it is therefore easy to receive, query and return CRS84 coordinates for those models. The HARMONIE DINI and HARMONIE IG use a lambert CRS (as described here) which means that they are best queried with the native CRS. It is not easy to use CRS84 with these models as coordinates have to be converted between CRS84 and native coordinates, and with CoverageJSON it is not possible to return gridded data in CRS84 format, as coordinates are no longer located in a regular grid when converted to CRS84. For GeoJSON output this is not a problem as there is no grid structure in GeoJSON, however, the payload size in GeoJSON is much larger than CoverageJSON - often more than 10 times larger.
So therefore, when querying HARMONIE-DINI and HARMONIE-IG with cube/bbox type, queries can only be done with native CRS. When doing so, convert input coordinates into native grid coordinates and when receiving result convert the native grid coordinates into the required format.
A special case is the /position query, which can be done for HARMONIE DINI and IG using CRS84 with CoverageJSON - since there is only one point in the grid returned.
The /collection/ and /collection/<collectionname> endpoints give information on the CRS and WKT for each model so it is known what CRS the model is in.
An experimental endpoint /bbox has been introduced to allow querying with CRS84 and filter data with CRS84 coordinates even if the underlying model is not CRS84. Also note the NetCDF format which has support for returning the projections parameters and the special longitude/latitude parameters which returns the CRS84 coordinates for clients that are not able to do this projection.
For the HARMONIE DINI/IG models the wind parameters in the models are in a u and a v component in the models and these u/v components are combined to give a wind direction and speed. However, since the CRS of HARMONIE DINI/IG is lambert, this means that these u/v vectors have to be projected. The service supports this conversion when requesting with CRS84 as the CRS. If requested that way, the u/v vectors are combined and returned as wind speed and wind direction.
When querying for the u/v parameters directly (wind-10m-u or wind-10m-v for example) with crs=CRS84, note that the returned values are not corrected with respect to CRS - they are still in native values.
This also means that the combined wind-speed and wind-direction parameters are not available when requesting with native crs - the conversion can be done after receiving the response by getting each layer and doing the lambert projection on the wind vectors.
Each model has a long list of available parameters, and for now not all are defined with names and description as they should be. We have therefore started with the most commonly used parameters and included those in the parameter-names lists and documentation. Until we have all parameters properly documented, you can still get all parameters available in the model by using the technical parameter-name. Please see the parameter pages (DKSS Parameters (Forecast Data EDR API), WAM Parameters (Forecast Data EDR API) and HARMONIE Parameters (Forecast Data EDR API) for a list of all parameters for all models with their technical parameter-name and descriptions.
For example the 2nd parameter in the HARMONIE_DINI_SF parameter table is a parameter with technical parameter-name 0-6-3-0.0-103. This means that this parameter-name can be retrieved by using parameter-name=0-6-3-0.0-103 in the request. This is a workaround and may be removed, when we get all parameters properly documented in the parameter lists.
Feedback and suggestions for the parameter lists are very welcome.