Table of contents:
Introduction to Requests
For DMI's Open Data services, an HTTP request consists of four mandatory parts that are separated with a slash (server_name/service_version/service_name/collections/collection/items?API-Key). These four parts and other elements are described in the table below:
| Base request (Mandatory) | Server name | Server name is static and is not expected to change over time. The server name is: dmigw.govcloud.dk |
| Service version | Insert the service version (current service version is "v2"). The service version will be updated over time and the observation service is documented her: OpenAPI Specification (metObs) | |
| Service name | The name for this service is "metObs", which stands for "Meteorological Observation". | |
| Collection | There are two collections available currently: station and observation | |
| Static query parts | collections and items | The base request contains two parts that are dictated by the OGC specification Those are simply used as is. server_name/service_version/service_name/collections/collection/items |
| Identification needed for authorization | API-Key | The API key is a unique key, given to your user's application, which has to be included in your request to allow for authorization. The API key can be used by multiple users of the same application. Please go to User Creation & Access Management to learn more about how you register and receive an API Key. |
Request Types and Examples
Please, make sure to read the query primer to maximize your use of the below parameters.
Red rows = API key identification, so your request can be authorized
Green rows = Base Request
Blue rows = Parameters and general query syntax
Yellow rows = Narrow/complex search examples
| Name | Description | Query syntax | Request examples | Help |
|---|---|---|---|---|
| Include your API-Key in the request | The API-Key is a unique key, given to your user's application, which has to be included in your request to allow for authorization. Please go to User Creation & Access Management to learn more about, how you receive an API Key. | Add the API key at the end of your request: 1. If you have not already used a "?" sign earlier in your query
2. If you have already used a "?" sign earlier in your query:
You can also add the API key to your request header like this: X-API-Key: [YourAPIKey] Please note that the brackets in the above examples should not be included in the request, they indicate where your changes should be. | 1. If you have NOT already used a "?" Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items?api-key={INSERT_YOUR_API_KEY_HERE} Description: Returns all observations from the metObs service. 2. If you have already used a "?" Description: Returns 1 observation from the metObs service. Get your own API Key: Go to User Creation & Access Management. | Remember to add API KEY in order to get authorized |
| Remember to include the API KEY in order to get authorized All examples below are assuming that you are including the API key and as such it is omitted | ||||
| Select collection | One essential step for using the API is to select the collection. You can always explore the available collections by using the example here. | [Server Name]/[Service Version]/[Service name]/collections | Example: https://dmigw.govcloud.dk/v2/metObs/collections Description: Will return all available collections within the service name | We currently have two available collections:
|
| Base request | Query for objects within a specific collection. This forms the basic request. You should use the below query parameters to further narrow your search. | [Server Name]/[Service Version]/[Service name]/collections/[collection]/items | Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items Description: Will return up to 1000 (the default limit) random objects from the "observation" collection Example: https://dmigw.govcloud.dk/v2/metObs/collections/station/items Description: Will return up to 1000 (the default limit) random objects from the "station" collection | Make sure to read the query primer to make use of the below parameters |
Always make sure you have a proper base request. You can see the request types and examples below for descriptions, syntax, examples, and help | ||||
| limit | Specify a maximum number of objects (e.g. observations) you want to be returned Note: If a limit is not specified, the default limit is returned Default limit: 1000 objects Max possible limit: 300000 is the maximum limit you can request | limit=SOME_INTEGER_VALUE | Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items?limit=100 Description: Returns a maximum of 100 objects | Please be advised that the default limit is 1000 and you should actively adjust it if you need more or less data. If more than 300000 objects are needed then use either the offset to request the next set of observations or the bulk download service. Please be advised that this is a "maximum" and the result size could be less than what is requested |
offset | Specify the number of objects that should be skipped before returning matching objects. Default: 0 Max possible offset: 500.000 | offset=SOME_INTEGER_VALUE | Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items?limit=100&offset=1000 Description: Returns a maximum of 100 objects skipping the first 1000 | Using 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. If datasets larger than maximum limit plus maximum offset are required then data should be retrieved using the bulk download service or by splitting requests by the datetime parameter. |
| stationId | Narrow the search to a specific station ID | stationId=SOME_ID | Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items?stationId=05185 Description: Returns observations for the station with the id "05185" | Overview of stations can be found here |
| datetime | Narrow the search 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, both ends of the range are inclusive | datetime=START_DATE/END_DATE datetime=../END_DATE datetime=START_DATE/.. datetime=DATE | Description: Returns observations within the dates UTC 2018-02-12 at midnight and UTC 2018-03-18 at midnight. Both dates are inclusive. Description: Returns observations within the dates 2019-01-01 at midnight and 2020-01-01 at midnight in Danish summer timezone. Both dates are inclusive. Description: Returns observations from the date 2019-01-01 at midnight (Danish summer timezone) and after Description: Returns observations before or matching the date 2019-01-01 at midnight (Danish summer timezone). Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items?datetime=2019-01-01T00:00:00+02:00 Description: Returns observations matching the date 2019-01-01 at midnight (Danish summer timezone) Description: Returns stations having the status "Active" at some time in the month of November 2020 (but not necessarily the whole month). | 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) You can read more about how to deal with the status and the datetime parameter in the context of station here. |
| bbox | Narrow the search to only include objects 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) | bbox=LON1,LAT1,LON2,LAT2 | Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items?bbox=7,54,16,58 Description: Returns observations within 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) Description: Returns observations within 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) | This bbox tool may be useful. Please use a decimal point as the decimal separator, e.g. 1.99 (and not 1,99) |
| bbox-crs | Change the coordinate reference system. We only support the CRS84 coordinate reference system. The best option is to omit this parameter. | bbox-crs=SOME_VALUE | Description: Returns observations within 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 | |
| period | Narrow the search to a predetermined date range. Most users will combine the "period" filtering with other query filters such as a specific bbox or a specific station. Some intervals will need some adjustment depending on the context and in some edge cases, e.g.: subtracting a month from 31th March will result in an invalid date 31th February, hence it will be adjusted to 28th/29th February respectively. | period=PREDETERMINED_VALUE Available values:
| Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items?period=latest Description: Returns the latest observation (ONLY ONE) Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items?period=latest-10-minutes Description: Returns the latest observations within the last 10 minutes. Latest combined with parameter and station Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items?period=latest&stationId=05185 Description: Returns the latest observation for the station having the stationId 05185. | Can only be used for the observation collection |
| parameterId | Narrow the search to a specific parameter id | parameterId=SOME_ID | Example: https://dmigw.govcloud.dk/v2/metObs/collections/observation/items?parameterId=pressure_at_sea Description: Returns observations having the parameter ID "pressure_at_sea" (Atmospheric pressure reduced to mean sea level) | Can only be used for the observation collection Overview of available parameters can be found here |
| 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. | sortorder=observed,DESC | Description: Returns the response sorted by the observed time in descending order | 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 Can only be used for the observation collection |
| status | Narrow the search to only allow stations having a specific status | status=SOME_VALUE | Description: Returns stations having the status "Active" on the second of November 2020 or after. This could also be considered "the list of all active stations" if the datetime parameter is set to the current date. Example: https://dmigw.govcloud.dk/v2/metObs/collections/station/items?status=Active Description: Returns stations having the status "Active" at some time. This means that this also returns stations that have been active at some earlier time but no longer are. Also see "validFrom" and "validTo" fields. | Can only be used for the station collection Available status values can be found here You can read more about how to deal with the status and the datetime parameter in the context of stations here. |
| type | Narrow the search to only allow stations having a specific type | type=SOME_VALUE | Example: https://dmigw.govcloud.dk/v2/metObs/collections/station/items?type=Synop Description: Returns stations having the type "Synop" (Weather stations that register a wide variety of meteorological parameters) | Can only be used for the station collection Available type values can be found here |
| Narrow search examples | Here are some narrow/complex examples showcasing the use of most parameters in combination | Description: Returns observations within the dates UTC 2018-02-12 at midnight and UTC 2018-03-18 at midnight (both dates are inclusive), and within 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), returning a maximum of a 100 objects skipping the first 1000. Description: Returns observations within the dates UTC 2018-02-12 at midnight and UTC 2018-03-18 at midnight (both dates are inclusive), and limited to the station having the id "06149" and the parameter having the id "temp_dry", returning a maximum of 20000 objects in total sorted by the "observed" time in descending order Description: Returns stations having the type "Pluvio" and was "Active" sometime in the month of November 2020 (but not necessarily the whole month) and is within 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) | ||