Page tree
Skip to end of metadata
Go to start of metadata

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 is documented in the OpenAPI Specification (lightningdata) for the observation service.

Service nameThe service name for this service is "lightningdata".
Collection

There are three collections available currently: station, observation and sensordata

The OpenAPI Specification (lightningdata) includes a section that describes which collections that are available for querying with the service. 

The underlying data in the different collections of the service can be found under About lightning data.

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]

1. If you have NOT already used a "?"

Example: https://dmigw.govcloud.dk/v2/lightningdata/collections/observation/items?api-key={INSERT_YOUR_API_KEY_HERE}

Description: Returns all observations from the lightningdata service. 


2. If you have already used a "?"

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

Description: Returns 1 observation from the lightningdata 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/lightningdata/collections

Description: Will return all available collections within the service name

We currently have three available collections:

  • station
  • observation
  • sensordata
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/lightningdata/collections/observation/items

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


Example: https://dmigw.govcloud.dk/v2/lightningdata/collections/station/items

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


Example: https://dmigw.govcloud.dk/v2/lightningdata/collections/sensordata/items

Description: Will return up to 1000 (the default limit) random objects from the "sensordata" 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.  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/lightningdata/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 use either the offset to request the next set of observations or use 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 is 0.

Max possible offset: 1.000.000, if exceeded the response will be a "400 Bad Request"

offset=SOME_INTEGER_VALUE

Example: https://dmigw.govcloud.dk/v2/lightningdata/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.

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/lightningdata/collections/observation/items?datetime=2018-02-12T00:00:00Z/2018-03-18T00:00:00Z

Description: Returns observations 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/lightningdata/collections/observation/items?datetime=2019-01-01T00:00:00+02:00/2020-01-01T00:00:00+02:00

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.


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

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


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

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


Example: https://dmigw.govcloud.dk/v2/lightningdata/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)


Example: https://dmigw.govcloud.dk/v2/lightningdata/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.

typeFilter observations by typetype=SOME_VALUE

Example: https://dmigw.govcloud.dk/v2/lightningdata/collections/observation/items?type=1

Description: Returns observations having type 1

Can only be used for the observation collection

Available types can be found 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/lightningdata/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)

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

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 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/lightningdata/collections/observation/items?bbox=7,54,16,58&bbox-crs=http://www.opengis.net/def/crs/OGC/1.3/CRS84

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

You can read the specification here. Link to CRS84

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:

  • latest (no interval constraint)
  • latest-10-minutes (within the last 10 minutes
  • latest-hour (within the last 60 minutes)
  • latest-day (within the last 24 hours)
  • latest-week (within the last 7 days)
  • latest-month (within the last month)

Example: https://dmigw.govcloud.dk/v2/lightningdata/collections/observation/items?period=latest

Description: Returns the latest observation (ONLY ONE)

Example: https://dmigw.govcloud.dk/v2/lightningdata/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/lightningdata/collections/observation/items?period=latest&stationId=20077

Description: Returns the latest observation for the station having the stationId 20077.

Can be used on the observation and sensordata collections

sortorderSorts returned objects.

Asking for results to be sorted should only be done when it is needed - response is generally faster when asking for results with no sorting.

Only for the observation and sensordata collections

sortorder=observed,DESC


Only for the station collection

sortorder=lastHeartbeat,DESC

Example: https://dmigw.govcloud.dk/v2/lightningdata/collections/observation/items?sortorder=observed,DESC

Description: Returns the response sorted by the observed time in descending order for the observation collection


Example: https://dmigw.govcloud.dk/v2/lightningdata/collections/observation/items?sortorder=lastHeartbeat,DESC

Description: Returns the response sorted by the received heartbeat-timestamp in descending order

Asking for results to be sorted should only be done when it is needed - response is generally faster when asking for results with no sorting


Can be used for the observation, sensordata and station collections

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

Example: https://dmigw.govcloud.dk/v2/lightningdata/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/lightningdata/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.

Narrow search examplesHere are some narrow/complex examples showcasing the use of most parameters in combination

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

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 100 objects skipping the first 1000.


Example: https://dmigw.govcloud.dk/v2/lightningdata/collections/observation/items?datetime=2018-02-12T00:00:00Z/2018-03-18T12:31:12Z&limit=20000&sortorder=observed,DESC

Description: Returns observations within the dates UTC 2018-02-12 at midnight and UTC 2018-03-18 at midnight (both dates are inclusive), returning a maximum of 20000 objects in total sorted by the "observed" time in descending order




  • No labels