Maritime Warnings

Technical documentation

Introduction

The KNMI publishes public maritime warning datasets that describe hazardous weather conditions for maritime areas in and around the Netherlands. These datasets are intended for professional and semi-professional users such as shipping, offshore operations, water authorities, app developers and other data integrators.

This documentation covers the maritime wind warning datasets for:

Coastal districts (Kustdistricten)
North Sea districts (Noordzee districten)

The warnings are published as machine-readable JSON, with geometries describing fixed maritime areas. At this stage, only wind-related warnings are included.

The datasets are authoritative, operational KNMI products and are updated whenever the warning status changes.

Issuance times and validity

A dataset is published whenever the warning status changes. In addition, a daily automatic heartbeat product is issued every day at approximately 08:30 UTC to confirm that the service is operational, even when no warnings are active. Each publication represents the current operational state of the warnings at the time of issuance. All times in the dataset are in UTC. The start time of a warning is defined by the field onset. For coastal districts, warnings generally refer to hazardous conditions expected within 6–9 hours ahead. For North Sea districts, warnings refer to hazardous conditions expected within 9–12 hours ahead.

The field expires is included mainly for administrative and technical purposes. It should not be interpreted as the precise end time of the hazardous conditions and should therefore not be used operationally as the validity end of the warning.

Scope of the datasets

The maritime warning datasets:

describe forecast-based warnings, not observations
are issued for predefined, fixed geographical areas
may contain zero active warnings, which is a valid state
are independent from CAP and MeteoAlarm, but conceptually aligned

Spatial model

Spatial mode: fixed-areas
Areas are predefined and stable over time
Each area is represented by a Polygon or MultiPolygon
Coordinates use WGS84 (EPSG:4326) longitude/latitude

This ensures spatial consistency and predictable area identifiers.

Geographical districts

Coastal districts

Coastal districts highlighted on the map.

North Sea districts

North sea districts highlighted on the map.

How to use this dataset

Important notes:

An empty warnings array means no active warnings
The field num_warnings shows the total number of active warnings in the dataset
Each publication represents the complete current state of the dataset; consumers should process the entire most recent document rather than assuming incremental updates.
Area identifiers are stable (fixed areas) and suitable for caching
A document is published whenever the warning status changes.
In addition, a daily automatic heartbeat product is issued every day at approximately 08:30 UTC to confirm that the service is operational, even when no warnings are active.
Each publication represents the current operational state of the warnings at the time of issuance.
All times in the dataset are in UTC.
The start time of a warning is defined by the field onset.
For coastal districts, warnings generally refer to hazardous conditions expected within 6–9 hours ahead.
For North Sea districts, warnings refer to hazardous conditions expected within 9–12 hours ahead.
The field expires is included mainly for administrative and technical purposes. It should not be interpreted as the precise end time of the hazardous conditions and should therefore not be used operationally as the validity end of the warning.

Element description

Below is a description of each element in the JSON document, in the order in which they appear:

Element	Description
metadata	Object containing product-level metadata such as source, product type, schema version and generation timestamp.
domain	Indicates the domain of the document. For this dataset, this is always `maritime`.
spatial_mode	Defines how spatial data is represented. In this dataset this is `fixed-areas`, meaning predefined areas are used.
num_warnings	Total number of active warnings (that is, excluding cancelled) present in the dataset at the time of publication.
areas	Array containing all predefined maritime areas, each including geometry and associated warnings.

metadata object

Field	Description
source	Originating organisation of the dataset (i.e. KNMI).
product	Name of the product (i.e. Maritime Warnings).
schema_version	Version of the JSON schema used for this dataset.
generated	Timestamp indicating when the dataset was generated (UTC).
publication_type	Value indicating whether the file was created by a meteorologist ("manual") or the timed daily heartbeat trigger ("heartbeat")

areas object

Field	Description
id	Unique and stable identifier of the area.
name_nl	Name of the area in Dutch.
name_en	Name of the area in English.
area_category	Category of the area (e.g. coastal, north-sea).
geometry	GeoJSON geometry defining the spatial extent of the area.
warnings	Array of warnings for this area (may be empty).

warnings object

Field	Description
author	Role or function that issued the warning (e.g. Noordzeemeteoroloog).
domain	Domain of the warning (`maritime`).
probability	Probability (%) that the hazardous condition will occur (100 for maritime, used for administrative and technical purposes.).
description_nl	Description of the warning in Dutch.
description_en	Description of the warning in English.
headline_nl	Short headline in Dutch (optional, not used for maritime warnings).
headline_en	Short headline in English (optional, not used for maritime warnings).
authority	Authority issuing the warning (i.e. KNMI).
level	Severity level of the warning (e.g. 1 = potentially dangerous/code yellow, 2 = dangerous/code orange, 3 = very dangerous/code red).
phenomenon	Type of hazard (e.g. wind).
onset	Start time of the expected hazardous conditions (UTC).
expires	Administrative expiration timestamp of the warning (UTC), Included mainly for administrative and technical purposes. It should not be interpreted as the precise end time of the hazardous conditions and should therefore not be used operationally as the validity end of the warning.
warning_type	Type of warning (always `current` for maritime warnings).
status	Current status of the warning (e.g. `active` or `cancelled`). Warning will be cancelled when the conditions are no longer hazardous.
published_warning_uuid	Unique identifier of the published warning instance.
event_uuid	Identifier linking different versions of the same warning event.
version_id	Incremental version number of the warning.
version_dt	Timestamp of the specific version (UTC).
area	GeoJSON geometry representing the affected area of the warning (may differ from the full area geometry).

Dataset structure

{
  "areas": [ ... ],
  "domain": "maritime",
  "metadata": { ... },
  "num_warnings": 0,
  "spatial_mode": "fixed-areas"
}