This document provides an overview of the Observations API, designed to retrieve and analyze observation data through a RESTful interface. The API is part of the Environmental Data Retrieval (EDR) system, following OGC standards for data queries and hosted on KNMI's Dataplatform (KDP). The API is restricted to NMS users and requires authentication which can be requested by contacting EMADDC and signing up at KDP.
Features
Supported Data Output Formats
- CoverageJSON: A JSON format for representing coverage data.
- CSV: Tabular data format.
Query Capabilities
-
Metadata Retrieval
Access collection-level metadata, including spatial and temporal extents, available parameters, and data queries.
-
Data Queries
Request observation data filtered by geographic areas, time windows, and additional parameters.
Retrieved Parameters
The API provides access to the following parameters:
- 4D-Position
- Wind Speed and Direction
- Temperature
Summary of Limitations
-
Bounding Box:
- Spatial queries must define a valid bounding box in WKT geometries format.
- The maximum area per request is restricted to bounding box with 10 degrees latitude by 10 degrees longitude.
-
Time Window:
- Data is available for a rolling two-week window from the current date.
- The datetime parameter must be a valid ISO8601 string and specify a time range within a 5 minutes window.
-
Data Availability:
- Data may not be available for all requested parameters or time intervals due to observational gaps.
- Returned parameters include empty value if data did not pass quality control checks (qc_flag ≠ 0).
- Quality control flags (qc_flag) and whitelist flags are included for retrieved parameters.
- Only data that has successfully passed input quality control (qc_flag = 0), is non-duplicate, and is not considered an outlier, will be included in the returned data.
In cases where wind or temperature data is deemed invalid and does not meet EMADDC output quality standards, that value will be represented as empty (null in json). If both values are invalid, the entire observation will not be included in the results. This process is consistent with the data provided in current EMADDC products (files).
Data Formats
Supported output formats:
- CSV (newly added). A compatible CSV reader can be found here.
- CovJSON Designed for detailed coverage representation. A compatible CovJSON reader can be found here.
Observation Parameters
| Description |
Parameter |
Units |
Source |
Remark |
| Date time |
dtg |
- |
EMADDC |
Example: 2024-12-11 01:00:04.047 |
| Latitude (high accuracy) |
lat |
deg |
Radar / ADS-B |
Add offset to get DB value |
| Longitude (high accuracy) |
lon |
deg |
Radar / ADS-B |
Add offset to get DB value |
| Observation ID |
obs_id |
- |
EMADDC |
Add offset to get DB value |
| Comm-B Data Selector (BDS) code |
bds |
- |
BDS 2.X |
|
| Anonymous Aircraft Mode-S ID (‘M’+24-bit) |
Mid |
Mxxxxxx |
BDS 2.X |
|
| Wind Speed |
wspd |
kts |
EHS: Derived MRAR: BDS 4.4 |
Caution: BUFR output of wspd is in m/s |
| Wind Direction |
wdir |
deg |
EHS: Derived MRAR: BDS 4.4 |
|
| Temperature |
temp |
Kelvin |
EHS: Derived MRAR: BDS 4.4 |
|
| Flight Phase |
phase |
3, 5, 6 |
Calculated |
See BUFR detailed phase of flight definition below |
| Roll Angle |
ra |
deg (- left turn) |
BDS 5.0 |
|
| Data Source |
source |
- |
Filename |
|
| System Identification Code |
sic |
- |
Station ID |
|
|
Whitelisted
|
wl_flag
|
-
|
Calculated
|
0 = wind and temp whitelisted
1 = wind not whitelisted temp whitelisted
2 = wind whitelisted temp not whitelisted
3 = wind not whitelisted temp not whitelisted
4 = whitelisting not performed
|
|
QC Flag
|
qc_flag
|
-
|
Calculated
|
For now qc_flag = 0
|
Endpoints
1. Collection Metadata
- Path: /v1/collections/observations/
- Description: Retrieve metadata for the “observations” collection. Includes spatial coverage, temporal range, and parameter details.
Example Request
curl --request GET 'https://api.dataplatform.knmi.nl/emaddc-edr/v1/collections' \
--header 'Authorization: [your api key]'
Example Response
Download example response: file
2. Query Observation Data by Area
- URL: /v1/collections/observations/area
- Method: GET
- Description: Retrieve observation data for a specified area and time range.
Query Parameters
| Parameter |
Type |
Required |
Description |
| coords |
WKT |
Yes |
The area of interest, defined as a WKT polygon. |
| datetime |
String |
Yes |
Time range in ISO8601 format (e.g., 2024-01-01T00:00:00Z/2024-01-31T23:59:59Z). |
| z |
String |
No |
Minimum and maximum flight level (leave empty for all flight levels) |
| parameter-name |
String |
No |
A comma-separated list of observation parameters to include in the results (e.g., temp,wspd). |
| f |
String |
No |
Output format (CoverageJSON, CSV) |
Example Request CoverageJSON
curl --request GET 'https://api.dataplatform.knmi.nl/emaddc-edr/v1/collections/observations/area?coords=POLYGON%28%285.0%2052.0,%206.0%2052.0,%206.0%2051.0,%205.0%2051.0,%205.0%2052.0%29%29&datetime=2024-12-01T01:00:00Z/2024-12-01T01:01:20Z&f=CoverageJSON' \
--header 'Authorization: [your api key]'
Example Response
Download the example response file
Example Request CoverageJSON
curl --request GET 'https://api.dataplatform.knmi.nl/emaddc-edr/v1/collections/observations/area?coords=POLYGON%28%285.0%2052.0,%206.0%2052.0,%206.0%2051.0,%205.0%2051.0,%205.0%2052.0%29%29&datetime=2024-12-09T01:00:00Z/2024-12-09T01:05:00Z&f=csv' \
--header 'Authorization: [your api key]'
Example Response
dtg,lat,lon,fl,obs_id,bds,Mid,wspd,wdir,temp,phase,ra,source,sic,wl_flag,qc_flag
2024-12-09 01:01:11.531,51.5777,5.99918,381.0,87191,56,xx,16.8637,54.5369,213.671,0,-0.276,xx,12,0,0
2024-12-09 01:01:11.680,51.5768,5.99913,381.0,87192,56,xx,16.8637,54.5369,213.837,0,-0.276,xx,23,0,0
2024-12-09 01:01:12.805,51.5776,5.99408,381.0,87217,56,xx,16.8583,54.5498,213.905,0,0.0,xx,20,0,0
2024-12-09 01:01:12.930,51.5783,5.99258,381.0,87220,56,xx,16.2681,54.0466,213.905,0,0.0,xx,2,0,0
Follow these steps to request an API key:
- Register van an account at the KNMI Dataplatform (KDP) via https://developer.dataplatform.knmi.nl/register/
- Send an email to opendata@knmi.nl to request acces to the EMADDC EDR API and provide an use case. Describe your use case to help KNMI understand how the API is used.
- You will receive an email with the API key.
- Use this key in your request Authorization header.
Elevate your data experience with the EMADDC EDR API!