Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added docs on request offset maximum

Table of contents

Table of Contents
maxLevel3


Introduction to requests

For DMI's Open Data services, an HTTP request consists of five parts that are separated with slash (server_name/service_name/service_version/schema/query). These five parts are described in the table below:

Base requestServer name

Server name is generic and is not expected to change over time. The server name is: dmigw.govcloud.dk

Service nameThe service name for this service is "metObs", which stands for "Meteorological Observation".
Service version

Insert the service version (current service version is "v1"). The service version will be updated over time and is documented in the OpenAPI Specification (metObs) for the observation service.

Schema

This part of the request is where you specify, which data source your query draws data from. The meteorological observation service provides access to more than one schema.

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

The underlying data in the different schemas of the service can be found under About meteorological observations.

Your queryQuery

The query is where you make a specific search for data . Please see the request types and examples below for descriptions, syntax, examples, and help.

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

Green row = Base Request

Grey rows = API key identification, so your request can be authorized

Blue rows = General query syntax

Yellow rows = Key value pair queries


NameDescriptionQuery syntaxRequest examples
Help
Base request

Query for all data in a specific table.

Default limit: 1000 objects

Default sortOrder: Descending for timeObserved (i.e. the most recent observations are shown first). Secondary default sort is descending for timeCreated.


[Server Name]/[Service Name]/[Service Version]/[Schema]/

Example: https://dmigw.govcloud.dk/metObs/v1/observation

Description: The example query searches for all data in the schema with the name "observation" with a default limit of 100 observations. If you start with the base request, you can more specifically search for data by adding a query after the base request (see blue, yellow and red rows below).


Note: If a new version of the service is released, use this instead of the version in the example URL.

Remember to add API KEY in order to get authorized - see grey row below!


If the example is used without an [API Key], it will return the error message "Unauthorized". Please end your request with your [API Key] in order to get authorized (see grey row at the bottom of this table).

End query with your API KeyThe 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/metObs/v1/observation?api-key={insert your api key}

Description: Returns all observations from the metObs service. 


2. If you have already used a "?"

Example: https://dmigw.govcloud.dk/metObs/v1/observation?parameterId=pressure&api-key={insert your api key}

Description: Returns all observations of "pressure" from the metObs service. 


Get your own API Key: Go to User Creation & Access Management.


Start query
Begin you query with a "?" sign (apart from when you make the simple queries - see yellow rows)

[Base request]

AND

?

Example: https://dmigw.govcloud.dk/metObs/v1/observation?

Description: This request does not do anything in itself. You are required to specify your query after the question mark.

Remember to add API KEY in order to get authorized - see grey row above
Parameter

Returns observations for a specific parameter


parameterId=

Example: https://dmigw.govcloud.dk/metObs/v1/observation?parameterId=pressure

Description: Returns all observations of "pressure"

Overview of parameters can be found here

Overview of codes can be found here

Remember to add API KEY in order to get authorized - see grey row above

Station

Search for a specific station using the stationID

stationId=

Example: https://dmigw.govcloud.dk/metObs/v1/observation?stationId=06156

Description: Returns all observations for the station with the stationId "06156"

Overview of stations can be found here

Remember to add API KEY in order to get authorized - see grey row above

AndSeparate different parts of the query with an "&" sign

&

Example: https://dmigw.govcloud.dk/metObs/v1/observation?parameterId=pressure&stationId=06156

Description: Combines the two previous examples to return all observations of "pressure" for the station with the stationId "06156"

Remember to add API KEY in order to get authorized - see grey row above
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: 300.000 is the maximum limit you can request (so you cannot ask for more than 300.000 observations)

limit= 

Example: https://dmigw.govcloud.dk/metObs/v1/observation?limit=100

Description: Returns a maximum of 100 observations with the default sort order.



Remember to add API KEY in order to get authorized - see grey row above

If more than 300.000 observations are needed use either the offset to request the next set of observations or use the bulk download service.

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=

Example: https://dmigw.govcloud.dk/metObs/v1/observation?limit=100&offset=1000

Description: Returns a maximum of 100 observations beginning with object number 1000 (skipping object 0 through 999) with the default sort order.


 

Remember to add API KEY in order to get authorized - see grey row above

Using limit and offset client can page through the objects returned - page size is set by the limit parameter.

From

Returns only objects with a "timeObserved" equal to or after a given timestamp (formatted in epoch microseconds)

from=

Example: https://dmigw.govcloud.dk/metObs/v1/observation?from=1562056860140000

Description: Returns all observations with a "timeObserved" equal to or after the timestamp "1562056860140000"



EPOCH-converter: https://www.epochconverter.com/

Remember to add API KEY in order to get authorized - see grey row above

ToReturns only objects with a "timeObserved" before (not including) a given timestamp (formatted in epoch microseconds)to=

Example: https://dmigw.govcloud.dk/metObs/v1/observation?to=1562056860190000

Description: Returns all observations with a "timeObserved" before (not including) the timestamp "1562056860190000"

EPOCH-converter:
https://www.epochconverter.com/

Remember to add API KEY in order to get authorized - see grey row above

Latest

Returns only the latest object.

Most users will combine the "Latest" filtering with other query filters such as a specific "Parameter" and a specific "Station".

latest

Only latest

Example: https://dmigw.govcloud.dk/metObs/v1/observation?latest=&api-key=[Insert your API key]

Description: Returns only the latest observation based on a primary sorting by "timeObserved" and a secondary sorting by "timeCreated"


Latest combined with parameter and station

Example: https://dmigw.govcloud.dk/metObs/v1/observation?latest=&parameterId=pressure&stationId=06156&api-key=[Insert your API key]

Description: Returns only the latest observation of pressure for the station with the stationId 06156 based on a primary sorting by "timeObserved" and a secondary sorting by "timeCreated"


Remember to add API KEY in order to get authorized - see grey row above
Latest 10 minutesReturns only objects with a "timeObserved" within the latest 10 minutes.

latest-10-minutes

Example: https://dmigw.govcloud.dk/metObs/v1/observation?latest-10-minutes

Description: Returns only the observations with a "timeObserved" within the latest 10 minutes



In order to receive all observations a limit may need to be added to the request. Please see the row about limits. 

Remember to add API KEY in order to get authorized - see grey row above

Latest hourReturns only objects with a "timeObserved" within the latest hour.

latest-hour

Example: https://dmigw.govcloud.dk/metObs/v1/observation?latest-hour&limit=99999

Description: Returns only the observations with a "timeObserved" within the latest hour



In order to receive all observations a limit may need to be added to the request. Please see the row about limits. 

Remember to add API KEY in order to get authorized - see grey row above

Latest dayReturns only objects with a "timeObserved" within the latest day.latest-day

Example: https://dmigw.govcloud.dk/metObs/v1/observation?latest-day&limit=99999

Description: Returns only the observations with a "timeObserved" within the latest day

In order to receive all observations a limit may need to be added to the request. Please see the row about limits. 

Remember to add API KEY in order to get authorized - see grey row above

Latest monthReturns only objects with a "timeObserved" within the latest month.latest-month

Example: https://dmigw.govcloud.dk/metObs/v1/observation?latest-40-months&limit=99999

Description: Returns only the observations with a "timeObserved" within the latest month

In order to receive all observations a limit may need to be added to the request. Please see the row about limits. 

Remember to add API KEY in order to get authorized - see grey row above

Combined query exampleIf you want to combine queries


Example: https://dmigw.govcloud.dk/metObs/v1/observation?parameterId=temp_dry&stationId=06184&limit=99

Description: Returns the latest 99 observations for the specified parameter and station.

Remember to add API KEY in order to get authorized - see grey row above
StationsReturns all stations


Example: https://dmigw.govcloud.dk/metObs/v1/station

Description: Returns all stations

Remember to add API KEY in order to get authorized - see grey row above
Filter stations by typeReturns all stations with given type


Example: https://dmigw.govcloud.dk/metObs/v1/station?type=Manual%20snow

Description: Returns all stations with type 'Manual snow'

Remember to add API KEY in order to get authorized - see grey row above
Filter stations by countryReturns all stations with given country


Example: https://dmigw.govcloud.dk/metObs/v1/station?country=DNK

Description: Returns all stations with country DNK (Denmark)

Remember to add API KEY in order to get authorized - see grey row above
1 or 2 key value pairs

You can combine up to 2 key value pairs in your query

Key: The key in the observation you are searching for. You can view the possible keys in the OpenAPI Specification (metObs).

Value: The value that you are searching for 

[Base request]

AND

/[key1]/[value1]/[key2]/[value2]

Single key value pair:

Example: https://dmigw.govcloud.dk/metObs/v1/observation/parameterId/cloud_height

Description: Returns all observations of cloud height across all stations.


Double key value pair:

Example: https://dmigw.govcloud.dk/metObs/v1/observation/parameterId/cloud_height/stationId/06188

Description: Returns all observations of cloud height for the station with the stationId 06188.

Remember to add API KEY in order to get authorized - see grey row above