ForsideVejrdataFrie data Dokumentation på engelsk APIsForecast Data STAC-API

Forecast Data STAC-API

Click here for Swagger - Interactive API explorer (external site)

To execute calls the service input your api-key by clicking the "Authorize" button in Swagger

Quick start examples

Example: https://dmigw.govcloud.dk/v1/forecastdata/collections/harmonie_dini_sf/items?api-key=<api-key> (external site)

Description: Will return up to 1000 (the default limit) STAC item objects from the HARMONIE DINI surface model each containing a single step in the forecast.

Example: https://dmigw.govcloud.dk/v1/forecastdata/collections/harmonie_ig_sf/items?api-key=<api-key> (external site)

Description: Will return up to 1000 (the default limit) STAC item objects from the HARMONIE IG surface model each containing a single step in the forecast.

The collection endpoints support a number of query parameters to filter or sort data. Make sure to read the query primer to make use of the below query parameters.

Example Response


		{
  "type": "FeatureCollection",
  "features": [
    {
      "stac_version": "1.0.0",
      "bbox": [
        7.0,
        53.0,
        16.0,
        60.0
      ],
      "geometry": {
        "coordinates": [
          [
            [
              7.0,
              53.0
            ],
            [
              16.0,
              53.0
            ],
            [
              16.0,
              60.0
            ],
            [
              7.0,
              60.0
            ],
            [
              7.0,
              53.0
            ]
          ]
        ],
        "type": "Polygon"
      },
      "collection": "wam_dw",
      "id": "WAM_DW_SF_2023-10-24T120000Z_2023-10-24T120000Z.grib",
      "asset": {
        "data": {
          "href": "https://dmigw.govcloud.dk/v1/forecastdata/download/WAM_DW_SF_2023-10-24T120000Z_2023-10-24T120000Z.grib",
          "title": "Forecast file download resource",
          "type": "application/x-grib",
          "roles": [
            "data"
          ]
        }
      },
      "type": "Feature",
      "properties": {
        "created": "2023-10-25T00:03:25.859Z",
        "datetime": "2023-10-24T12:00:00Z",
        "modelRun": "2023-10-24T12:00:00Z"
      }
    }
  ],
  "timeStamp": "2023-10-26T09:58:40Z",
  "numberReturned": 1,
  "links": [
    {
      "href": "https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?limit=1",
      "rel": "self",
      "type": "application/geo+json",
      "title": "This document"
    },
    {
      "href": "https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?limit=1&offset=1",
      "rel": "next",
      "type": "application/geo+json",
      "title": "Next set of results"
    }
  ]
}

API

/collections

Example: https://dmigw.govcloud.dk/v1/forecastdata/collections (external site).

Description: Will return all available collections in the API.

The Weather Model (HARMONIE) can be found in the collections:

/v1/forecastdata/collections/harmonie_dini_sf
/v1/forecastdata/collections/harmonie_dini_ml
/v1/forecastdata/collections/harmonie_dini_pl
/v1/forecastdata/collections/harmonie_ig_sf
/v1/forecastdata/collections/harmonie_ig_ml
/v1/forecastdata/collections/harmonie_ig_pl

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:

/v1/forecastdata/collections/wam_dw
/v1/forecastdata/collections/wam_natlant
/v1/forecastdata/collections/wam_nsb

for area Danish Waters, North Atlantic and North Sea-Baltic, respectively.

The Storm Surge Model (DKSS) can be found in the collections:

/v1/forecastdata/collections/dkss_nsbs
/v1/forecastdata/collections/dkss_idw
/v1/forecastdata/collections/dkss_ws
/v1/forecastdata/collections/dkss_if
/v1/forecastdata/collections/dkss_lf
/v1/forecastdata/collections/dkss_lb

for the area North Sea Baltic Sea, Inner Danish Waters, Wadden Sea, Roskilde/Isefjord, Limfjord and Little Belt, respectively.

/collections/<collection name>/items

Query parameters:

limit	Specify a maximum number of objects (e.g forecast files) you want to be returned. If a limit is not specified, the default limit is 1000. \n \nIf more than 300000 objects are needed then use either the offset to request the next set of observations or [link:/friedata/dokumentation/download-data|download] the data. \n \nPlease be advised that this is a "maximum" and the result size could be less than what is requested. \n \nMax possible limit: 300000 is the maximum limit you can request \n \nExample: \n \nReturns a maximum of 100 objects \n<ul><li>Request: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?limit=100&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?limit=100] (external site)</ul></li>

offset	Specify the number of objects that should be skipped before returning matching objects. Default: 0. Max possible offset: 1.000.000 \n \nUsing the limit and the offset parameters, a client can page through the objects returned - page size is set by the limit parameter. This will only work up to the maximum possible offset. \n \nIf datasets larger than maximum limit plus maximum offset are required then data should be retrieved using the download service or by splitting requests by the datetime parameter. \n \nExample: \n \nReturns a maximum of 100 objects skipping the first 1000 \n<ul><li>Request: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?limit=100&offset=1000&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?limit=100&offset=1000] (external site)</ul></li>

modelRun	Narrow the search to a specific model run, which means the beginning of a specific forecast. \n \nThese forecasts are run (ie. calculated) each day at the hours 00, 03, 06, 09, 12, 15, 18 and 21 in UTC depending on model. \n \nAPI only retain data covering the last 48 hours. Model runs that started more than 48 hours ago are therefore out of circulation. \n \nIf you want a filter to only include forecast step files from one specific forecast, you should use this filter. \n \nExample: \nReturns forecast files from a model run which begins at 03/01/2022 00:00:00 UTC. \n<ul><li>Request: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?modelRun=2022-03-01T00:00:00Z&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?modelRun=2022-03-01T00:00:00Z] (external site)</ul></li>

datetime	Narrow the search for forecast steps to a date range where both ends of the range are inclusive 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. \n \nThe plus sign "+" must be URL encoded: %2B (See [link:https://datatracker.ietf.org/doc/html/rfc3986|RFC3986] (external site)) Try one of the examples and observe the encoded "+" sign. \n \nThe API only retains data covering the last 48 hours. A WAM forecast covers 5½ days into the future. \n \nThe effective range of the datetime parameter for a WAM forecast model at any given time is therefore from 48 hours ago, until 132 hours into the future. \n \nExamples: \n \nReturns forecast files within the dates UTC 2018-02-12 at midnight and UTC 2018-03-18 at midnight. Both dates aree inclusive. \n<ul><li>Request:: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?datetime=2018-02-12T00:00:00Z/2018-03-18T00:00:00Z&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?datetime=2018-02-12T00:00:00Z/2018-03-18T00:00:00Z] (external site)</ul></li> \nReturns forecast files within the dates 2019-01-01 at midnight and 2020-01-01 at midnight in Danish summer timezone. Both dates are inclusive. \n<ul><li>Request:: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?datetime=2019-01-01T00:00:00%2B02:00/2020-01-01T00:00:00%2B02:00&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?datetime=2019-01-01T00:00:00%2B02:00/2020-01-01T00:00:00%2B02:00] (external site)</ul></li> \nReturns forecast files from the date 2019-01-01 at midnight (Danish summer timezone) and after \n<ul><li>Request:: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?datetime=2019-01-01T00:00:00%2B02:00/..&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?datetime=2019-01-01T00:00:00%2B02:00/..] (external site) </ul></li> \nReturns forecast files before or matching the date 2019-01-01 at midnight (Danish summer timezone). \n<ul><li>Request:: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?datetime=../2019-01-01T00:00:00%2B02:00&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?datetime=../2019-01-01T00:00:00%2B02:00] (external site) </ul></li> \nReturns forecast files matching the date 2019-01-01 at midnight (Danish summer timezone) \n<ul><li>Request:: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?datetime=2019-01-01T00:00:00%2B02:00&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?datetime=2019-01-01T00:00:00%2B02:00] (external site)</ul></li>

bbox	Narrow the search to only include objects within the specified bounding box. \n \nA bounding box (usually shortened to bbox) is an area defined by two longitudes and two latitudes, where: \nLatitude is a decimal number between -90.0 and 90.0. \nLongitude is a decimal number between -180.0 and 180.0. \n \nThey follow the standard format of: \nbbox = Southwesterly point (lon,lat) followed by northeasterly point (lon, lat) \n \nThis [link:https://boundingbox.klokantech.com/|bbox tool] (external site) may be useful. \n \nPlease use a decimal point as the decimal separator, e.g. 1.99 (and not 1,99) \n \nExamples: \n \nReturns forecast files spanning an area intersecting with the bounding box having the Southwesterly point of 7.0, 54.0 and northeasterly point of 16.0, 58.0 (which basically covers the area of Denmark) \n<ul><li>Request:: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?bbox=7,54,16,58&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?bbox=7,54,16,58] (external site) </ul></li> \nReturns forecast files spanning an area intersecting with the bounding box having the Southwesterly point of 8.351697,55.421038 and northeasterly point of 8.542584,55.511345 (which basically covers the area of the city of Esbjerg in Denmark) \n<ul><li>Request:: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?bbox=8.351697,55.421038,8.542584,55.511345&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?bbox=8.351697,55.421038,8.542584,55.511345] (external site)</ul></li>

bbox-crs	Specifies the coordinate reference system of the bbox parameter. This service only support the CRS84 coordinate reference system. \n \nExample:: \n \nReturns forecast files spanning an area intersecting the bounding box having the Southwesterly point of 7.0, 54.0 and northeasterly point of 16.0, 58.0 (which basically covers the area of Denmark) using the CRS84 coordinate reference system \n<ul><li>Request:: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?bbox=7,54,16,58&bbox-crs=http://www.opengis.net/def/crs/OGC/1.3/CRS84&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?bbox=7,54,16,58&bbox-crs=http://www.opengis.net/def/crs/OGC/1.3/CRS84] (external site)</ul></li>

sortorder	Sorts returned objects. Asking for results to be sorted should only be done when it is needed - responses are generally faster when asking for results with no sorting. \n \nExample:: \n \nReturns the response sorted by the forecasted time in descending order \n<ul><li>Request:: [link:https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?bbox=7,54,16,58&sortorder=datetime,DESC&api-key=|https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?bbox=7,54,16,58&sortorder=datetime,DESC] (external site)</ul></li>

Query example

Example:

Returns forecast files from the model run 01/03/2022 at 00:00:00 UTC and forecasted time step files part of that run for the timeframe of 24-48 hours, by requiring steps to be between 02/03/2022 at 00:00:00 UTC and 03/03/2022 at 00:00:00 UTC. Results should also cover an area that intersects with a bbox covering Denmark in the CRS84 coordinate system. Result shall be in descending datetime order, with offset 0.

Request: https://dmigw.govcloud.dk/v1/forecastdata/collections/wam_dw/items?modelRun=2022-03-01T00:00:00Z&datetime=2022-03-02T00:00:00Z/2022-03-03T00:00:00Z&offset=0&bbox=4,52,21,58&bbox-crs=http://www.opengis.net/def/crs/OGC/1.3/CRS84&sortorder=datetime,DESC (external site)

/download/<filename>

Link to the file can be found by querying using the /collections/<collection name>/items documented above. Link will be in the asset section of the features.

Example:

Downloads the file. File is in GRIB file format.

Request: https://dmigw.govcloud.dk/v1/forecastdata/download/WAM_DW_SF_2022-04-19T120000Z_2022-04-19T120000Z.grib (external site)

The download can be validated by comparing the “content-length” HTTP header in the response with the downloaded file length. If these do not match the file download has been interrupted and can be retried or resumed by using a GET request with a “Range” HTTP header (external site).

Response schema

Overall Structure

The API is a STAC API - Features service and follows this standard as documented here: https://api.stacspec.org/v1.0.0-beta.4/core/ (external site).

Data is returned in a FeatureCollection object that describes the returned data set. Data points are found in the features field which contains a number of Feature objects as described below.

FeatureCollection

Features are wrapped in a STAC Item FeatureCollection (external site) object, which includes:

Generic fields for every Feature object

These are STAC Items, as described by STAC Item Specification (external site) and the table below describes the returned data:
(Note that a STAC Item can be seen as an augmented GeoJson feature (external site))

Key	Not null	Data Type	Description
stac_version	yes	String	STAC version
bbox.0	yes	float	Southwesterly point longitude*
bbox.1	yes	float	Southwesterly point latitude*
bbox.2	yes	float	Northeasterly point longitude*
bbox.3	yes	float	Northeasterly point latitude*
geometry.coordinates	yes	GeoJson polygon	GeoJson polygon of the covered area*. See: [link:https://www.rfc-editor.org/rfc/rfc7946.html#section-3.1.6|https://www.rfc-editor.org/rfc/rfc7946.html#section-3.1.6] (external site)
collection	yes	String	Name of the collection (wam_dw, wam_nsb and wam_natlant). Each collection is the WAM model covering a specific area. dw = danish waters, nsb = north sea + baltic and natlant = north atlantic
id	yes	String	feature id (forecast file name)
asset.data.href	yes	string <uri>	The location of the forecast file, where it can be downloaded
asset.data.title	yes	String	The title of the ressource, always "Forecast file download resource"
asset.data.type	yes	String	The media type of the resource, always "application/x-grib" [link:https://en.wikipedia.org/wiki/GRIB|What is GRIB?] (external site)
asset.data.roles.0	yes	String	role is always "data"
type	yes	String	type is always "feature"
properties.datetime	yes	String	Timestep of the forecast in [link:https://datatracker.ietf.org/doc/html/rfc3339#section-5.6|RFC3339 5.6] (external site) format.
properties.created	yes	String	Creation time in database (in [link:https://datatracker.ietf.org/doc/html/rfc3339#section-5.6|RFC3339 5.6] (external site) format, e.g. "2020-07-10T07:59:38Z")
properties.modelRun	yes	String	The start time of the forecast, and time for which the forecast model was run. The field is in [link:https://datatracker.ietf.org/doc/html/rfc3339#section-5.6|RFC3339 5.6] (external site) format.

* forecast models are by their very nature models of a fictitious world with a fictitious geodetic datum, ie. not tied to any actual physical locations on earth. The coordinates returned by our service are therefore not WGS84, as required by the GeoJSON specification: RFC 7946 section 4 (external site). The coordinate system used by our forecast models also use the IERS Reference Meridian, so the coordinates could be interpreted as WGS84 in order to use the data in the physical world, when taking into account the inherent uncertainty of the model. However, it is up to the end user how they want to interpret the model in the physical world.