Technical documentation

Public Weather Warnings

This is the documentation for the datasets KNMI-public-weather-warnings and KNMI-public-weather-warnings-extended. For more information about the process behind the issued warnings, see here (in Dutch).

General documentation

The JSON schema belonging to this dataset is provided in a separate file: JSON schema.

KNMI Public Warnings provides structured information about current warnings and early indications of potentially dangerous weather. The dataset is intended for systems that need to ingest, process or display KNMI warning information in a consistent machine-readable form.

Each publication is a snapshot: one JSON file describes the complete current and future warning situation known at the time the file was generated. A snapshot can contain multiple warning sets. Each warning set concerns one weather phenomenon and contains one or more warning parts for specific areas, periods and severity levels. One incident can be linked to multiple warning sets and weather phenomena.

The dataset can contain both operational and test information. Consumers must inspect metadata.publication_type and each warning set's operational_status before deciding how to process or display a record. Only an Actual warning set represents real warning information that may require action. Exercise, System and Test records must not be presented as actual warnings. All records before 2026-11-02 contain test information.

Warning information includes Dutch and English meteorological texts, validity periods, affected areas, severity, probability ranges and optional enriched guidance. Areas are represented as GeoJSON-like Polygon or MultiPolygon objects using longitude-latitude coordinate pairs in WGS 84.

Filename structure and issuance time

Files follow the naming convention dataset_yyyy-MM-dd'T'HHmmssSSSSSS'Z'.json, where dataset is replaced by public_warnings for the KNMI-public-weather-warnings dataset and replaced by professional_warnings for the KNMI-public-weather-warnings-extended dataset.

A file is published whenever the status of a warning changes. Publications are ad-hoc, except for an automatically generated daily heartbeat at 05:30 UTC (publication_type = heartbeat), which generates a new file representing the current warning state to confirm that the publication chain is operational.

How to process each file in this dataset

Each file is a complete snapshot containing all warnings and early indications of potentially dangerous weather known at the file's generation time.

Treat each successively published file as a full replacement for the preceding snapshot, not as a list of incremental changes. A snapshot with an empty warnings array is a valid representation of a state with no warning sets.

The top-level JSON object contains publication metadata, two counters and an array of warning sets. A warning set represents one or multiple warnings for a dangerous weather event. Its parts array contains the individual warning areas, time periods, severity levels and probability ranges.

Process each snapshot as a complete state:

  1. Parse the file as JSON and validate it against the JSON schema.
  2. Check metadata.schema_version before applying version-specific processing rules.
  3. Inspect metadata.publication_type and warnings[].operational_status so test or exercise information is not presented as an actual warning.
  4. Confirm that num_warning_sets equals the number of objects in warnings.
  5. Confirm that num_warnings equals the sum of the lengths of all parts arrays.
  6. Build the replacement state completely before replacing the preceding successfully processed snapshot.
  7. Use warning_set_uuid and part_uuid as stable identities to relate objects across successive snapshots; use version_id and version_dt to detect updates.
  8. Use warning_type to distinguish warnings from early indications of potentially dangerous weather.
  9. Use phenomenon to group or filter warning sets by weather hazard.
  10. Use warning-part severity, color, probability and geometry to present the affected situation.
  11. Use publication_type and operational_status to separate operational warning information from heartbeats (automatically generated publication (daily at 05:30 UTC) that shows the current warning state to confirm that the publication chain is alive) and publications for test purposes.

metadata.publication_type has the following meanings:

Value Interpretation
manual Publication made by a meteorologist creating or updating warning information.
heartbeat Automatically generated publication (daily at 05:30 UTC) that shows the current warning state to confirm that the publication chain is alive.
test Publication used for system testing.

On WarningSet level, operational_status determines how an individual warning set must be handled:

Value Interpretation
Actual Real warning information intended for operational handling.
Exercise Information used for an exercise. (not in use)
System System-generated test information. (not in use)
Test Test information.
File format and schema

Refer to the JSON schema for more details.

Top-level snapshot

Property Type Description
metadata object Metadata for this publication.
num_warning_sets integer Declared number of warning sets.
num_warnings integer Declared number of warning parts.
warnings array Complete array of WarningSet objects.

Metadata

Property Type Description
metadata.schema_version string Version of the JSON structure.
metadata.generated_at string Generation time, formatted as ISO 8601 in UTC timezone.
metadata.producer object Information of the producer of the warnings (KNMI). Producer subproperties are id, name and contact.
metadata.domain string Domain of the warnings in the file, always equal to "public".
metadata.publication_type string 'manual' publication type are published by a meteorologist creating or updating a warning. 'heartbeat' publications are generated automatically on a schedule (daily, at 05:30 UTC) and show the current warning state. test publications are published to test the chain of applications.
metadata.snapshot_uuid UUID string Unique identifier of this publication.

WarningSet

Property Type Description
domain string Warning domain. Default: "public".
phenomenon string Weather phenomenon shared by the warning parts.
onset string Start of the warning set, described as the earliest part onset in ISO 8601 UTC.
expires string End of the warning set, described as the latest part expiry in ISO 8601 UTC.
texts object Dutch and English meteorological text containers.
warning_type string "warning" or "potentially-dangerous-weather".
status string Lifecycle state, distinguishing between active, expired and cancelled WarningSets.
operational_status string Operational or test handling.
incident object An incident such as a named storm can be linked to one or multiple WarningSets, such as a WarningSet for Rain, another WarningSet for Wind, etc.
parts array Individual warning parts.
warning_set_uuid UUID string Stable identifier used to track this WarningSet across snapshots.
version_id integer WarningSet version number.
version_dt string Publication time of this warningSet version in ISO 8601 UTC.

For more details, such as a full list of all possible phenomena, refer to the JSON schema.

Two warning sets with the same phenomenon must not overlap in time. This is a business rule and is not enforced by the JSON Schema.

WarningPart

Property Type Description
part_uuid UUID string Stable identifier of the warning part.
version_id integer Version number of the warning part.
version_dt string Time at which this warning part version was last updated, formatted in ISO8601 with UTC timezone.
severity string Moderate, Severe or Extreme.
color string Warning part colour: yellow, orange or red.
area object Polygon or MultiPolygon geometry described as GeoJSON in WGS 84.
area description object Description of area affected by warning part e.g. {"en": "parts of Gelderland", "nl": "delen van Gelderland"}
guidance object Enriched guidance by language.
onset string Start of warning part in ISO 8601 UTC.
expires string End of warning part in ISO 8601 UTC.
probability_percentage_range string Probability range: 10-30, 30-60, 60-90 or 90-100. The lower bound is inclusive and the upper bound is exclusive
certainty string Enriched certainty category. Possible <= 50%, Likely: >50%, Observed: 90-100%. Use probability_percentage_range for more detailed information.
status string Lifecycle state, used to distinguish between active, expired and cancelled WarningParts.
response_type string Enriched recommended-response category.

Note there is a one-to-one relationship between severity and color:

Severity Color
Moderate yellow
Severe orange
Extreme red

For more details, such as a full list of values for certain string fields, refer to the JSON schema.

List of phenomena and probability thresholds

The KNMI-public-weather-warnings-extended dataset contains all issued warnings ("warning_type": "warning") and it contains Potentially Dangerous Weather objects ("warning_type": "potentially-dangerous-weather") at lower probability than the KNMI-public-weather-warnings dataset (see table below). This dataset is intended for professional users, and some of the warnings it contains are not relevant to the general public. Some "potentially dangerous weather" objects have such a low probability of occurrence that the general public is not expected to take them into account when making decisions. However, these low-probability events may still be relevant to professional users, who may need to prepare for the possibility of severe weather even when it is unlikely to occur.

The dataset KNMI-public-weather-warnings, on the other hand, is filtered for use by the general public. Only relevant warnings for this audience are present and their content matches the other communication outlets of KNMI visible to the public e.g. website and app. Filtering is based on probability of occurrence and is only applicable to early warnings (warning_type equals potentially-dangerous-weather). Potentially dangerous weather warnings are defined as having an onset later than >48h ahead, or when onset of an event is within 48 hours, with small likelihood of occurrence. When warning_type equals warning, the warning is published to both the general and the extended dataset.

The following table lists the phenomena in English, Dutch, the corresponding phenomena in MeteoAlarm and the probability thresholds used for this filtering.

English Dutch MeteoAlarm CAP Probability threshold for potentially dangerous weather
Fog Mist Fog Yellow: N/A
Orange/red: ≥ 30%
Road ice Gladheid Snow or Ice Yellow: ≥ 60%
Orange/red: ≥ 30%
High temperature Hitte High temperature Yellow: ≥ 60%
Orange/red: ≥ 30%
Low temperature Kou Low Temperature Yellow: ≥ 60%
Orange/red: ≥ 30%
Rain Zware regen Rain Yellow: ≥ 30%
Orange/red: ≥ 10%
Snow Sneeuw Snow or Ice Yellow: ≥ 60%
Orange/red: ≥ 30%
Thunderstorm Onweersbuien Thunderstorm Yellow: ≥ 60%
Orange/red: ≥ 30%
Waterspouts Waterhozen Wind No thresholds specified
Wind Windstoten Wind Yellow: ≥ 60%
Orange/red: ≥ 30%
How warning sets and warning parts are related

A WarningSet groups one or more WarningPart objects for the same weather phenomenon for a specific weather event. Information that applies to the entire event is stored on the warning set (e.g. guidance); area-specific and time-specific information is stored on its warning parts.

Level Stable identity Version fields Validity
Snapshot metadata.snapshot_uuid metadata.generated_at Complete state at generation time.
Warning set warning_set_uuid version_id, version_dt Earliest onset through latest expires
Warning part part_uuid version_id, version_dt Part-specific onset through expires.

The ordering of the parts array may change. Consumers must use part_uuid, not array position, to relate a warning part across snapshots.

The warning-set onset is equal to or earlier than the first onset of its warning parts, and its expiration is equal to or later than the last expiration timestamp of its parts.

incident.incident_uuid can link warning sets for different phenomena to one incident, such as a named storm.

How lifecycle and versions should be interpreted

The lifecycle status values for warning sets and warning parts are:

Value Interpretation
active The warning set or warning part is active. This means the warning is upcoming OR ongoing.
cancelled It was cancelled by a meteorologist, or the probability fell below the threshold. (warning set or warning part must not be active.)
expired It was marked expired by a meteorologist. (the described weather no longer poses a threat)

A cancelled or expired warning set or warning part appears in a snapshot one more time.

Use the stable UUID to identify the logical object and version_id to distinguish revisions. Do not assume that array order represents recency.

The schema does not enforce that version IDs increase by one, that version dates are monotonic, or that warning-set and warning-part version changes occur together.

How text and guidance should be interpreted

texts contains meteorologist-authored information in Dutch and English.

Property Type Constraint Description
texts.nl.headline, texts.en.headline string Maximum 255 characters Short headline.
texts.nl.description, texts.en.description string 20 to 65,536 characters when present Concise meteorological summary.
texts.nl.detailed_description, texts.en.detailed_description string No length constraint in the schema Detailed meteorological description. Required for warnings, optional for potentially dangerous weather.

guidance is enriched information. A language-specific guidance object can contain optional impact and instruction strings, each of which may also be null.

How geometry should be interpreted

Each warning part contains an area described as a GeoJSON RFC 7946 Polygon or MultiPolygon in WGS 84. Coordinate positions are ordered as [longitude, latitude].

The Coordinates definition requires exactly two numeric items. The schema uses ge and le for intended coordinate bounds.

Any rings in the geometry are closed, polygons do not have holes and are counterclockwise.

The geometry type property has a default ("Polygon" or "MultiPolygon").

Example shape:

{
  "type": "Polygon",
  "coordinates": [[
    [3.2, 51.3],
    [6.1, 51.3],
    [6.1, 53.6],
    [3.2, 53.6],
    [3.2, 51.3]
  ]]
}
How to access the files using our APIs

We recommend subscribing to the Notification Service to be notified as soon as new files are published, so you can fetch them immediately.

You can also check for new files by polling. We recommend to keep track of the previous file you've processed. You can then check for new files using one of the following queries. Replace {latest_json_file} or {latest_xml_file} with the name of the file you've processed the latest.

JSON files: https://api.dataplatform.knmi.nl/open-data/v1/datasets/KNMI-public-weather-warnings/versions/1.0/files?begin={latest_json_file}&maxKeys=1000&sorting=asc&orderBy=filename

XML files: https://api.dataplatform.knmi.nl/open-data/v1/datasets/KNMI-public-weather-warnings/versions/1.0/files?begin={latest_xml_file}&maxKeys=1000&sorting=asc&orderBy=filename&end=public_warnings

CAP elements explained

This table explains the CAP elements you can encounter in KNMI's CAP XML files, following the MeteoAlarm CAP Profile v2.0 (September 2025). Elements are grouped by the CAP block they are in: alert (message level), info (content, one block per language) and area (inside info). parameter elements are MeteoAlarm-specific and consist of a valueName and a value.

alert block

CAP element Description
identifier Unique ID of this message. Format: WMO Object ID (2.49.0.0.528.0.NL) + creation time (UTC, YYYYMMDDHHMMSS) + warning part UUID + version number.
sender Email address of the originator, for technical inquiries.
sent Date and time the message was issued, with UTC offset, e.g. 2026-10-29T08:30:00+00:00.
status Handling of the message: Actual for use by everyone, or Test technical testing only.
msgType Nature of the message: Alert (new), Update (replaces earlier message) or Cancel (withdraws earlier message).
scope Intended distribution of the message. Always Public.
code Version of the MeteoAlarm CAP Profile the message follows, e.g. MCP:v2.0.
references The earlier message(s) that are updated, as sender,identifier,sent. Multiple messages are separated by whitespace. Only used in Update and Cancel messages.

info block (one for Dutch, nl-NL, and one for English, en-GB)

CAP element Description
language Language of this info block, as ISO 639 language + ISO 3166 country: nl-NL or en-GB.
category Type of event. For KNMI always Met (meteorological).
event Short name of the event, combining awareness level and type, e.g. Moderate High-Temperature.
responseType Recommended action, AllClear once the event no longer poses a threat.
urgency Time available to act: Immediate, Expected, Future or Past (no action required anymore).
severity Intensity of the event: Minor, Moderate, Severe or Extreme.
certainty Probability of the event occurring: Observed (100%), Likely (>50%) or Possible (≤50%).
eventCode Event according to the OASIS Event Terms List, as valueName OET:v1.0 and value OET-NNN (e.g. OET-218), when applicable.
onset Expected start of the event, with UTC offset.
expires Expected end of the event, with UTC offset.
senderName Human-readable name of the issuing authority. For KNMI always KNMI Royal Netherlands Meteorological Institute.
headline Short headline of the warning.
description Extended description of the event.
instruction Recommended action for the public. A pipe (\|) separates the individual advices.
web Link to a page with more information. For KNMI always the KNMI warnings page.
contact Contact information. For KNMI always the KNMI contact form.
parameter: awareness_level MeteoAlarm awareness level, formatted as code; colour; name: 1; green; Minor, 2; yellow; Moderate, 3; orange; Severe or 4; red; Extreme. Level 1; green; Minor is used to soft cancel a warning.
parameter: awareness_type MeteoAlarm awareness type, formatted as code; type, e.g. 1; Wind, 3; Thunderstorm, 5; High-Temperature, 10; Rain.
parameter: impacts Short statement on the expected impact. Can occur multiple times, each statement is one item in a list.
parameter: probability_percentage_range Probability of occurrence as a percentage range, e.g. 60-90. The lower bound is inclusive and the upper bound is exclusive.

area block

CAP element Description
areaDesc Human-readable description of the affected area, e.g. Parts of: Gelderland and Utrecht.
polygon Affected area as a whitespace-separated list of WGS 84 latitude,longitude pairs. The first and last pair are identical, the vertices run counter-clockwise, and each coordinate has at most six decimals.
Relation CAP XML and JSON files

KNMI also publishes warnings as CAP (Common Alerting Protocol) alerts in XML format in the KNMI-public-weather-warnings dataset. CAP files are not available for the KNMI-public-weather-warnings-extended dataset. KNMI adheres to the most recent MeteoAlarm CAP Profile, which itself is based on the international OASIS CAP standards. One CAP message/XML file describes exactly one warning part and is built from the same underlying warning information as the JSON file. Consequently, one JSON snapshot file with multiple warning parts corresponds to multiple CAP files, one per part_uuid (the most recent version of each). The version_id in the CAP identifier is taken from the associated warning set's version_id, so it need not start at 1 or increase by exactly 1 between CAP files of the same part. Each file contains information in two languages, Dutch and English, published as two info blocks.

CAP element JSON equivalent field Description
identifier version_dt, part_uuid, version_id A unique identifier, starting with WMO Object ID and country code, extended with the warning set's publication time (version_dt), part identifier (part_uuid) and set's version number (version_id).
sent version_dt The time this warning part was last published or updated.
status operational_status Whether the message is for actual use, a test, or an exercise.
msgType status, version_id Alert for a new warning part, Update for a changed or expired warning part, Cancel once the part is withdrawn.
references version_dt, version_id (of earlier versions) Identifies the earlier CAP message(s) this one updates or cancels, when applicable.
event phenomenon A short description of the event, equivalent to the weather phenomenon.
responseType response_type Set to "AllClear" once a warning part has expired; otherwise left empty.
urgency status, warning_type "Past" once expired; "Future" for a potentially dangerous weather; "Expected" for a current warning.
severity severity Same value as in the JSON file (Moderate, Severe or Extreme).
certainty certainty Same value as in the JSON file (Observed, Likely or Possible).
onset / expires onset / expires Same validity period as in the JSON file.
headline texts.nl.headline, texts.en.headline Same headline text, per language.
description texts.nl.description, texts.en.description, texts.nl.detailed_description, texts.en.detailed_description The description, followed by the detailed description when available.
instruction guidance.nl.instruction, guidance.en.instruction The enriched guidance instructions, where the pipe operator '|' is the delimiter.
area.polygon area Same geometry, converted to CAP's coordinate order and orientation.
area.areaDesc area description A human-readable area description, generated from the warning's covered area, same value as in the JSON file.
parameter: awareness_type phenomenon The MeteoAlarm awareness type that corresponds to the phenomenon, e.g. Wind, Rain, Fog.
parameter: awareness_level severity, certainty, status The MeteoAlarm awareness level (colour and label), based on severity and certainty; set to the lowest level (that is 1; green; Minor) once a warning is soft cancelled.
parameter: probability_percentage_range probability_percentage_range Probability of occurrence, same value as in the JSON file.
parameter: impacts guidance.nl.impact, guidance.en.impact The enriched impact text, shown as one or more short statements.

The JSON fields color, incident and domain are not used in the CAP message. A few CAP fields are always the same for every KNMI warning and have no JSON equivalent, these are: sender, code, category, senderName, web, contact, scope, language and eventCode.

Warning cancellation (hard cancel and soft cancel)

A warning that stops being active before expiry time has elapsed can end in one of two ways:

  • Hard cancel: the warning is withdrawn before onset time is reached. This happens when a meteorologist withdraws it, or for potentially dangerous weather warnings when the probability falls below the threshold of the dataset.
  • Soft cancel: a meteorologist explicitly marks a warning (whose onset is already passed) as expired because the weather no longer poses a threat. The warning was valid and is now over.

The table below shows for both JSON and CAP which elements are used to distinguish a hard or soft cancel.

Hard cancel Soft cancel
JSON status cancelled expired
CAP msgType Cancel Update
CAP urgency Unchanged Past
CAP responseType Unchanged AllClear
CAP awareness_level Unchanged 1; green; Minor