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 versionInsert the service version (current service version is "v2"). The service version will be updated over time and the service is documented here: OpenAPI Specification (climateData)
Service name

The name for this service is "climateData"

CollectionThere are six collections available currently: station, stationValue, countryValue, municipalityValue, 10kmGridValue and 20kmGridValue
Static query partscollections 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 authorizationAPI-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


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

  • ?api-key=[YourAPIKey]


2. If you have already used a "?" sign earlier in your query:

  • &api-key=[YourAPIKey]

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/climateData/collections/stationValue/items?api-key={INSERT_YOUR_API_KEY_HERE}

Description: Returns all station values from the climatedata service. 


2. If you have already used a "?"

Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?limit=1&api-key={INSERT_YOUR_API_KEY_HERE}

Description: Returns 1 station value from the climatedata 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/climateData/collections

Description: Will return all available collections within the service name

We currently have two available collections:

  • station
  • stationValue
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/climateData/collections/stationValue/items

Description: Will return up to 1000 (the default limit) random objects from the "stationValue" collection


Example: https://dmigw.govcloud.dk/v2/climateData/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.
Make sure to read the query primer to make use of the below parameters.

You can see the request types and examples below for descriptions, syntax, examples, and help

limit

Specify a maximum number of objects (e.g.  station values) 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/climateData/collections/stationValue/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 objects 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/climateData/collections/stationValue/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/climateData/collections/stationValue/items?stationId=05185

Description: Returns station values 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


Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?datetime=2018-02-12T00:00:00Z/2018-03-18T00:00:00Z

Description: Returns station values within the dates UTC 2018-02-12 at midnight and UTC 2018-03-18 at midnight. Both dates are inclusive.


Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?datetime=2019-01-01T00:00:00+02:00/2020-01-01T00:00:00+02:00

Description: Returns station values within the dates 2019-01-01 at midnight and 2020-01-01 at midnight in Danish summer timezone. Both dates are inclusive.


Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/datetime=items?2019-01-01T00:00:00%2B02:00/..

Description: Returns station values from the date 2019-01-01 at midnight (Danish summer timezone) and after


Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?datetime=../2019-01-01T00:00:00+02:00

Description: Returns station values before or matching the date 2019-01-01 at midnight (Danish summer timezone).


Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?datetime=2019-01-01T00:00:00+02:00

Description: Returns station values matching the date 2019-01-01 at midnight (Danish summer timezone)


Example: https://dmigw.govcloud.dk/v2/climateData/collections/station/items?status=Active&datetime=2020-11-01T00:00:00Z/2020-12-01T00:00:00Z

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: %2B

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:

  • Latitude is a decimal number between -90.0 and 90.0.
  • Longitude is a decimal number between -180.0 and 180.0.

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/climateData/collections/stationValue/items?bbox=7,54,16,58

Description: Returns station values 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)

Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?bbox=8.351697,55.421038,8.542584,55.511345

Description: Returns station values 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

Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?bbox=7,54,16,58&bbox-crs=http://www.opengis.net/def/crs/OGC/1.3/CRS84

Description: Returns station values 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

You can read the specification here. Link to CRS84

parameterIdNarrow the search to a specific parameter idparameterId=SOME_ID

Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?parameterId=mean_temp

Description: Returns station values having the parameter ID "mean_temp" (Mean temperature)

Can only be used for the stationValue collection

Overview of available parameters can be found here

timeResolutionNarrow the search to a specific time resolutiontimeResolution=SOME_VALUE

Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?timeResolution=hour

Description: Returns station values with hourly time resolution. Can also be day, month or year.

Can only be used for the stationValue collection


sortorderSorts 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=timeFrom,DESC

Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?bbox=7,54,16,58&sortorder=timeFrom,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 stationValue collection

qcStatusNarrow the search to given qcStatusqcStatus=SOME_VALUE

Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?qcStatus=manual

Description: Returns station values that have been manually quality controlled. Station values that have not been quality controlled (yet) will not be returned.


Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?qcStatus=manual&validity=true

Description: Returns only station values that have been manually quality controlled and are considered valid by DMI's climatologists.

You can read more about climate data quality control here.

See also validity below.

validityNarrow the search to given validityvalidity=SOME_VALUE

Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?validity=true

Description: Returns only station values that are considered valid by DMI's climatologists.


Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?qcStatus=manual&validity=true

Description: Returns only station values that have been manually quality controlled and are considered valid by DMI's climatologists.


Validity is only used for climate data for Greenland. You can read more about climate data quality control for Greenland here and the validity property in the schema documentation.

statusNarrow the search to only allow stations having a specific statusstatus=SOME_VALUE

Example: https://dmigw.govcloud.dk/v2/climateData/collections/station/items?status=Active&datetime=2020-11-02T00:00:00Z/..

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/climateData/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.

municipalityId

Narrows the search to a municipality

municipalityId=0147

Example: https://dmigw.govcloud.dk/v2/climateData/collections/municipalityValue/items?municipalityId=0147

Description: Returns municipality values identified by their municipality id's. The numbers must be a valid danish municipality number prefixed with "0", fx. "0147" for Frederiksberg, which municipality number is 147 .

Municipality id's without prefixed "0" can be found

here

cellIdNarrows the search to a specific cellIdcellId=10km_635_54

Example:

https://dmigw.govcloud.dk/v2/climateData/collections/10kmGridValue/items?cellId=10km_635_54

or

https://dmigw.govcloud.dk/v2/climateData/collections/20kmGridValue/items?cellId=20km_612_68

Description: Returns 10km grid values or 20km grid values having the given cellId.

The 10km cells are based on the Danish national grid (det danske kvadratnet), and so the 10km cell ID's follow this standard. While 20km cells are not part of this standard, they use the same convention, ex. "20km_102_75".
Narrow search examplesHere are some narrow/complex examples showcasing the use of most parameters in combination

Example: https://dmigw.gocloud.dk/v2/climateData/collections/stationValue/items?datetime=2018-02-12T00:00:00Z/2018-03-18T12:31:12Z&limit=100&offset=1000&bbox=7,54,16,58

Description: Returns station values 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.


Example: https://dmigw.govcloud.dk/v2/climateData/collections/stationValue/items?datetime=2018-02-12T00:00:00Z/2018-03-18T12:31:12Z&limit=20000&stationId=06149&parameterId=temp_dry&sortorder=timeFrom,DESC

Description: Returns station values 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 "timeFrom" time in descending order



Example: https://dmigw.govcloud.dk/v2/climateData/collections/station/items?type=Pluvio&datetime=2020-11-01T00:00:00Z/2020-12-01T00:00:00Z&status=Active&bbox=7,54,16,58

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)



  • No labels