CAP DWD Profile for the Common Alerting Protocol v1.2
Version 2.1.11
February 20, 2020
Deutscher Wetterdienst Frankfurter Straße 135, D-63067 Offenbach, Germany Tel: +49 (0)69 / 8062 – 0 Fax: +49 (0)69 / 8062 – 4484 http://w w w.dwd.de CAP@dw d.de
Document History Version Date Changes 2.1.7 21.03.2016 Initial version of the document. This document is a translation of the document “CAP DWD Profil zum Common Alerting Protocol v1.2” (German), version 2.1.7. 2.1.8 19.06.2017 Revised Version to account for new CAP-Products, that comply with the CAP update scheme and include : - Chapter 1 (Introduction) updated - Products without an update scheme are now marked as “deprecated” - GeoCodes “SIGN”, “ALTITUDE” and “STATE” marked as “deprecated” - File naming conventions and available files have been moved to a separate document - Description added for “SILENT_UPDATE” and “PARTIAL_CLEAR”, and “AllClear” - Descriptions updated for , , , , , , - Tables for eventCode “ii” in chapter 3.1 and eventCode “GROUP” in chapter 3.3 updated - CAP examples updated 2.1.9 10.01.2018 - removed „deprecated“ elements - chapter 2.1 removed reference to DWD-XSD Schema - chapter 2.2.1.1 added Product suffix for globally unique identifiers - chapter 2.2.1.8 added „id:“ - chapter 2.2.1.3 , 2.2.2.9 , 2.2.2.10 , 2.2.2.11 all CAP times in (CET/CEST) - chapter 2.2.2.7 added „Likely“ - added new chapter „3.6 WarncellID“ - updated CAP examples in chapter 3.7/3.8 2.1.10 29.04.2019 Improved documentation of optionality for used elements: - chapter 2 and 2.2 updated - added assured Elements in 2.2 - removed “optional” marker (2.2.18, 2.2.2.18, 2.2.3.2, 2.2.3.3) - added DWD marker for assured Elements (2.2.18, 2.2.2.1, 2.2.2.9, 2.2.2.10, 2.2.2.13, 2.2.2.14) 31.07.2019 Adjustments for snowfall and snowdrift: - Chapter 3. Adjusted event and parameter tables (removed 77 and 78, edited 76) 31.07.2019 Clean up of information in chapter 3: - Removed obsolete event types (81,83, 86) - Updated parameters table in 3.2 2.1.11 19.02.2020 New Warning event “extreme heat” - Chapter 3.1.5 adjust table of warning events - Chapter 3.3. adjust groups - Chapter 3.5. add special colors for heat events
19.02.2020 Cap parameter now uniformly given in English - Chapter 2.2.2.18 adjust description - Chapter 3.2. actualize table of parameter 20.02.2020 Add up-to-date Examples in chapter 3.7 and 3.8
1 Introduction 1.1 Objective The Deutscher Wetterdienst (DWD, Germany's National Meteorological Service) aims to make warnings available to as many users and applications as possible. Therefore it is necessary to provide warnings in an unambiguously defined, machine-readable format. To meet this requirement, the DWD makes public warnings available in the Common Alerting Protocol (CAP) format (see [CAP12]). The CAP format provides an open, non-proprietary digital message format for exchanging all-hazard warnings and notifications. CAP alerts can be integrated in any application and transmitted by any means. 1.2 Process The CAP DWD profile defines the syntactic extensions to [CAP12] by the DWD. It is constantly adapted to meet user demands and the requirements of the DWD. This document makes no claim to be complete. Existing content can be changed or completely removed in later versions of this document. The most recent version of this document can be found at [CAPDWD]. A list of available products and versions ([DWD PROD]) is available on the [OD-HELP] website. An in-depth description of the different CAP variants available from the DWD, as well as additional implementation notes can be found in the [DWD IN] document on the [OD-HELP] website. DWD CAP messages can be validated using the CAP v1.2 Schema [CAP12-XSD]. The DWD encourages all users to develop their software to be fully compatible with the original CAP v1.2 specification [CAP12], thereby allowing all valid CAP v1.2 messages to be processed correctly. 1.3 Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. The terms alert, warning, warning message and message are used as synonyms throughout this document. The term coordinate pair in this document refers to a pair of comma separated decimal values in degrees (°), which describe a geographical location (not projected) and are given in the form of “[latitude]”,”[longitude]”. Latitudes of the southern hemisphere and longitudes of the western hemisphere have negative values, indicated by a prefixed minus sign “-“.
1.4 References [AGS] Amtliche Gemeindeschlüssel (AGS), https://de.wikipedia.org/wiki/Amtlicher_Gemeindeschl%C3%BCssel [CAP12] Common Alerting Protocol Version 1.2, http://docs.oasis- open.org/emergency/cap/v1.2/CAP-v1.2-os.pdf [CAP12-XSD] CAP Alert Message (version 1.2) XSD Schema https://docs.oasis- open.org/emergency/cap/v1.2/CAP-v1.2.xsd [CAPDWD] Dokumentation zum DWD CAP Profil (in der aktuellen Version), https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_dw d_profile_de_pdf.pdf [DWD PROD] Überblick über die DWD-Produkte für Warnungen, https://www.dwd.de/DE/leistungen/opendata/help/warnungen/dwd_w arnings_products_overview_de_pdf.pdf [DWD IN] Verarbeitungshinweise zu DWD CAP-Produkten, https://www.dwd.de/DE/leistungen/opendata/help/warnungen/cap_dw d_implementation_notes_de_pdf.pdf [ISO 639-1] ISO 639 Code Tables, http://www-01.sil.org/iso639-3/codes.asp [OD-HELP] Open Data Erläuternde Dateien, https://www.dwd.de/DE/leistungen/opendata/hilfe.html#doc612284bo dyText3 [RFC2119] Key words for use in RFCs to indicate Requirement Levels, S. Bradner, IETF RFC 2119, March 1997, http://www.ietf.org/rfc/rfc2119.txt [UUID] A Universally Unique Identifier (UUID) URN Namespace, IETF RFC 4122, 2005, https://tools.ietf.org/html/rfc4122 [WMO386] WMO-No. 386 (Manual on the Global Telecommunication System), https://www.wmo.int/pages/prog/www/ois/Operational_Information/Pu blications/WMO_386/WMO_386_Vol_I_2009_en.pdf
2 CAP DWD profile The following sub-items specify the attributes of a DWD CAP message. A DWD CAP message SHOULD be fully compliant to the CAP v1.2 Schema [CAP12]. The reader SHOULD regard any incompatible specification as deprecated and SHOULD refrain from using it. DWD continues to adjust such elements to the CAP v1.2 specification. 2.1 XML/CAP format The content of a CAP file is determined by the following parameters. Coding UTF-8 Format Name space CAP v1.2 Format The general structure of a CAP file can be found in [CAP12]. The CAP v1.2 XML Schema can be found in [CAP12-XSD]. 2.2 CAP elements In the following the content of defined CAP elements provided by DWD is described in detail. Given specifications are of a descriptive nature and do not supersede the CAP v1.2 specification. DWD makes use of generic CAP v1.2 elements (, , and ) for special DWD warning content. The following sections contain the specific definitions for these DWD values.
Elements from the CAP v1.2 protocol, which are not listed in this document, are not considered invalid, and may or will be used as specified in [CAP12]. DWD will always provide all mandatory CAP v1.2 elements whether or not those are listed in this document. Every element defined as optional by the CAP v1.2 specification remains optional even if it is listed in the following.
However there are optional elements in CAP v1.2 which are considered essential by DWD. These will always be given in an official DWD Warning. To represent essential optional elements the following markings are used in this document:
ASSURED Every DWD warning contains reliably the marked optional ele ment. CONDITIONAL Every DWD warning usually contains the marked optional ele ment. However there are special warning types which do not define the element at all. These exceptions will be defined explicitly for CONDITIONAL elements. (E.g. the element is only conditionally as sured as there are warning types which do not define it.)
2.2.1 A CAP file MUST contain exactly one element, which displays the basic
Target recipients, who have already received earlier mes sage(s) identified in , SHOULD NOT receive a push notification for this update.
PARTIAL_CLEAR A partial clear MAY only occur in combination with Update and AllClear. It signifies an early or explicit expiration of alert message(s) identified in in the given (see [DWD IN]).
The clear message MAY be send as a push notification to tar get recipients for the given .
id:… Language independent message identifier. (ASSURED) This identifier MUST start with “id:” (without quotes). A CAP message MUST NOT have more than one element that starts with “id:”.
If two or more CAP messages with different ele ments (different languages) have the same id:, they MAY be regarded as representations (translations) of the same information (message) in different languages.
The current version of CAP messages generated by DWD al ways contains the language independent identifier. Beispiel: id:2.49.0.1.276.0.DWD.PVW.1515594060000.8fe03 46a-c4f5-4d86-8747-787d1438f931
2.2.1.9 Info The extended message identifier(s) of earlier CAP messages. If multiple messages are referenced, they SHALL be separated by whitespace (see [CAP12]). Format ,, E-Mail address of the agency issuing the CAP warning (see 2.2.1.2). Unique identifier of a CAP message (see 2.2.1.1). The date and time when the message was issued (see2.2.1.3). Example [email protected],2.49.0.1.276.0.DWD.PVW.1496087880000. 12486fd7-325f-417d-bcf9-c03187290b3a.ENG,2017-05- 29T19:58:00+00:00
2.2.2 An element MAY have one or more elements. Each element represents a warning in given language. Additional languages SHOULD be placed in separate elements and SHOULD carry the same information. An element MAY contain one or more elements. 2.2.2.1 (ASSURED) Info Language of the text in the element Format - RFC 3066 Specification of the language (lower case letters) RFC 3066 Specification of the country (upper case letters) Example de-DE
2.2.2.3 Info Terminology of the event depending on the ii of the message Example WINDBÖEN (wind gusts) Note: Information concerning the event codes can be found in chapter 3.1.
GROUP The event group, e.g. „WIND“. There MAY be multiple elements with valueName=GROUP (see section3.3). AREA_COLOR The DWD's preferred RGB colour for visualisation. Colour values are separated by spaces, e.g. „255 255 0“ (see section 3.5). PROFILE_VERSION Version of the DWD profile, which the content of the CAP file refers to, e.g. „2.1“. LICENSE License under which the data is provided (especially geodata), e.g. BKG (Federal Agency for Cartography and Geodesy) Note: Further Information can be found in chapter 3.
2.2.2.12 Info The text naming the originator of the message Example DWD / Nationales Warnzentrum Offenbach (national warning centre) Zentrum für Medizin-Meteorologische Forschung (Centre for medicine related meteorological research)
2.2.2.13 (ASSURED) Info Headline of the message Example Amtliche WARNUNG vor … (official warning) Example Amtliche UNWETTERWARNUNG vor … (official severe weather warning) Example VORABINFORMATION UNWETTER: … (preliminary information on severe weather) Example AUFHEBUNG der UNWETTERWARNUNG vor … (cancellation of the severe weather warning) Example AUFHEBUNG der VORABINFORMATION UNWETTER: ... (cancellation of the preliminary information on severe weather).
2.2.2.14 (ASSURED) Info Text describing the warning or the preliminary information Example Von Westen ziehen einzelne Gewitter auf. Dabei gibt es Sturmböen mit Geschwindigkeiten um 70 km/h (20m/s, 38kn, Bft 8). Example of a Am Mittwochmittag und -nachmittag muss an der Nordseeküste mit or preliminary kanartigen Böen um 110 km/h (Bft 11) aus Südwest gerechnet werden. information
2.2.2.15 Info Additional text to the warning (instructions and safety advises) Example ACHTUNG! Hinweis auf mögliche Gefahren: Es können zum Beispiel Bäume entwurzelt und Dächer beschädigt werden. Achten Sie besonders auf herabstürzende Äste, Dachziegel oder Gegenstände. Schließen Sie alle Fenster und Türen! Sichern Sie Gegenstände im Freien! Halten Sie insbesondere Abstand von Gebäuden, Bäumen, Gerüsten und Hochspannungsleitungen. Vermeiden Sie möglichst den Aufenthalt im Freien!
2.2.2.16 Info The identifier of the hyperlink (URI) associating additional information with the alert message Example http://www.wettergefahren.de
Note: In versions before 2.1.11, parameter names and values are language-sensitive. The German parameter names and values differed from the English. Starting with profile version 2.1.11 DWD will provide additional languages. Parameter names and values are now uniformly in English. The use case for parameters is the automatic processing of warning attributes. The parameter section is now consistent over all languages.
2.2.3 An element MAY occur one or more times in every block. Every element MAY define the target area using one or more geographical codes () and geographic polygons (). The element MAY contain one or multiple instances of or . If multiple or elements are given, the area described by this block is represented by the union of all the included elements. If more than one element is provided, the target area for the block is the union of all the included blocks. If a CAP file contains polygon elements ( and EXCLUDE_POLYGON) as well as entity related elements (e.g. WARNCELLID), then the union of all polygon elements MUST represent the same area as the union of all entity related elements. In this case one MAY use either the entity related elements or the polygon elements to determine the total affected area. 2.2.3.1
Info A text description of the affected area Format | polygonal event area Name of the affected (geographical/ political/ economical/ administrative) entity, e.g. “Vogelsbergkreis”. polygonal Static description for affected areas which are not directly linked to a fixed event area entity, but described by polygons. Example Gemeinde Stemwede Example polygonal event area
2.2.3.2
Info The paired values of points defining a polygon Format (1) Code Values: The geographic polygon is represented by a whitespace- delimited list of [WGS 84] coordinate pairs.
(2) A minimum of 4 coordinate pairs MUST be present and the first and last pairs of coordinates MUST be the same.
(3) Multiple instances MAY occur within an block. Example 48.3,8.2 48.2,8.3 ... 48.3,8.2
elements in addition to the element. If the surrounding element denotes a geographic entity, it MUST contain one or more elements to identify the affected areas.
EXCLUDE_POLYGON (1) Hole in the warning area (area without a warning) as a polygon.
(2) The contents of „value“ MUST include the whitespace- delimited list of points of the exclusion polygon in the form of [latitude, longitude] coordinate pairs (points), the last point MUST be identical to the first point (this is the same format as in the contents of a element, see chapter 2.2.3.2). For example:
EXCLUDE_POLYGON48.3,8.2 48.2,8.3 ... 48.3,8.2
(3) If an element contains one or more elements with valueName=”EXCLUDE_POLYGON”, then it MUST contain exactly one element to allow for an unambiguous relation between holes and hull.
(4) There MAY be multiple elements with valueName=“EXCLUDE_POLYGON“ in one block. Therefore, in processing, each element SHOULD be checked for valueName=“EXCLUDE_POLYGON“. All exclusion polygons SHOULD then be cut out of each polygon of a element.
(5) In order to conform with CAP v1.2, each hole SHOULD be covered entirely by at least one element.
(6) The element with valueName=“EXCLUDE_POLYGON“ MUST NOT be used if there is no element declared in the
2.2.3.4 Info Lower limit of the altitude range in feet. Format Altitude in feet Example 1312,336 (=400m) For further explanations and unit conversions see chapter 3.4.
2.2.3.5 Info Upper limit of the altitude range in feet. Format Altitude in feet Example 2624,672 (=800m) For further explanations and unit conversions see chapter 3.4.
3.1.5 Medical and Public Health Warnings (Medizin-Meteorologische Warnungen) ii 246 UV-INDEX (UV Index) 247 STARKE HITZE (strong heat) 248 EXTREME HITZE (extreme heat)
3.2 Parameters of the ii values () Only some of the characteristics are listed below in an exemplary manner.
ii Parameter name Parameter value Parameter unit 31 / 33 occurrence isolated / localalized / repeated / w idespread 34 / 36 38 / 40 direction of approach north / north-east / east /south-east / north-w est 41 / 42 ) / w est / south-w est / south 44 / 45 46 / 48 gusts <50 / ~50 / >120 / ... [km/h] 49 / 94 95 / 96 precipitation <10 / ~10 / 10-15 / ... [l/m² in 1h] /
Thunderstorm [l/m² in 6h] hail ~2 / ... [cm] tornado possible 51 / 52 gusts <50 / ~50 / >120 / ... [km/h] 53 / 54 exposed gusts <55 / ~55 / >55 / ... [km/h] 55 / 56 w ind direction north / north-east / east /south-east / north-w est / w est / south-w est / south
Wind subsequent w ind direction north / north-east / east /south-east / north-w est / w est / south-w est / south
59 occurrence mountains covered by clouds / particularly in low -lying river areas and valleys
Fog visibility <150 / ... [m] 61 / 62 precipitation <10 / ~10 / >10 / 5-10 / ... [l/m² in 1h] / 66 [l/m² in 6h] in w indw ard areas <10 / ... [l/m²] previous precipitation <5 / ~5 / >5 / 5-10 / ... [l/m²] Heavyrainfall 63 / 64 precipitation <5 / ~5 / >5 / 5-10 / ... [l/m²] 65 in w indw ard areas <10 / ... [l/m²] previous precipitation <10 [l/m²]
Continuousrainfall 70 / 71 snow fall <1 / ~1 / >2 / 1-3 / ... [cm] 72 / 73 In w indw ard areas <1 / ~1 / >1 / ... [cm]
previous snow fall <1 / ~1 / >1 / ... [cm]
Snowfall snow fall level rising to [200/400/600/…] meter dropping to [2000/1500/1000/ …] meter 74 / 75 / - - - 76
Snow Snow drift 22 / occurrence particularly as the sky clears / particularly in val 82 leys and dips / particularly over snow / particu larly as the sky clears over snow
local occurrence over snow / in valleys and dips / as clear sky con ditions continued / particularly as the sky clears over snow near surface >-2 / ~-2 / ... [°C]
84 cause Widespread ice formation / w idespread very heavy hoar frost depositions / traces of snow / w idespread very heavy hoar frost depositions or w idespread ice formation / w idespread very heavy hoar frost depositions or traces of snow / w idespread ice formation or traces of snow / w idespread very heavy hoar frost depositions , w idespread ice formation or traces of snow
Slipperysurfacesroad occourrence mainly on side roads and bridges
85 / cause as the snow turns to rain / as the rain turns to 87 snow / as the sky clears / due to freezing rain or
drizzle / due to black ice Glaze 88 / 89 runoff <5 / ~5 / >5 / 5-10 / ... [l/m²]
Note: The CAP message for a specific meteorological phenomenon contains only the groups, which match the phenomenon and its accompanying phenomena. The ii-values in brackets are OPTIONAL, marking events that MAY fall into the corresponding group. For example the event with ii=41 belongs to the group “THUNDERSTORMS”, but it MAY additionally belong to the group “TORNADO”.
3.4 Altitude information , The altitude information and in CAP are specified in feet. To convert to meters following approach can be used: meter= feet ∗ 0,3048 The values are rounded to the nearest integer value. Following rules apply: • If = 0 and not equal 9842.5197 (=3000 m), it means: „Altitudes below ...“, for example: 02624.67192 => Altitudes below 800 m • If not equal 0 and = 9842.5197 (=3000 m), it means: „Altitudes above...“, for example 2624.671929842.5197 => Altitudes above 800 m • If = 0 and ceiling = 9842.5197 (=3000 m), it means: „All altitudes“, for example: 09842.5197 => All altitudes 3.4.1 Altitude information used for General altitude Lower limit Upper limit Letter in the header / Meaning 0 m / 3000 m / X All altitudes 0.0 ft 9842.5197 ft
Upward expansion Lower limit Upper limit Letter in the header / Meaning 200 m / 3000 m / B >200 m 656.16798 ft 9842.5197 ft 400 m / 3000 m / C >400 m 1312.33596 ft 9842.5197 ft 600 m / 3000 m / D >600 m 1968.50394 ft 9842.5197 ft 800 m / 3000 m / E >800 m 2624.67192 ft 9842.5197 ft 1000 m 3000 m / F >1000 m /3280.8399 ft 9842.5197 ft 1500 m / 3000 m / G >1500 m 4921.25985 ft 9842.5197 ft 2000 m 3000 m / H >2000 m 9842.5197 ft
Downward expansion Lower limit Upper limit Letter in the header / Meaning 0 m / 800 m / L < 800 m 0.0 ft 2624.67192 ft 0 m / 600 m / M < 600 m 0.0 ft 1968.50394 ft 0 m / 400 m / N < 400 m 0.0 ft 1312.33596 ft 0 m / 200 m / A < 200 m 0.0 ft 656.16798 ft
3.6.2 Official Municipality Key (AGS) The 8 digit Official Municipality Key (german: “Amtlicher Gemeindeschlüssel”, AGS) is structured as follows [AGS]: • 1.-2. number designates the Federal State • 3.-5. number designates the district in the state • 6.-8. number designates the municipality in the district
Hence it is possible to deduce the Federal State (previously STATE) di rectly from the AGS.
Federal Name State 01 Schleswig-Holstein 02 Hamburg 03 Lower Saxony 04 Bremen 05 North Rhine-Westphalia 06 Hesse 07 Rhineland-Palatinate 08 Baden-Württemberg 09 Bavaria 10 Saarland 11 Berlin 12 Brandenburg 13 Mecklenburg-Vorpommern 14 Saxony 15 Saxony-Anhalt 16 Thuringia
The 1.-5. digit of the AGS uniquely identifies a district/urban area and is also referred to as District Key (german: “Kreisschlüssel”).
Example: AGS of Municipality Wiersdorf: 07 232 134 Federal State: 07 (Rhineland-Palatinate) District: 07232 (Eifelkreis Bitburg-Prüm)
3.6.3 WarncellIDs for special DWD warning areas The DWD provides warnings not only for political regions with an assigned Official Municipality Key, but additionally or alternatively for special areas (summaries, subdi visions). Some districts for example are subdivided in coastal (german: “Küste”) and inland (german: “Binnenland”) areas or mountainous (german: “Bergland”) and lowland (german: “Tiefland”) areas. Additionally some district-free cities are subdivided into ur ban quarters.
Examples: - Kreis Rostock (AGS: 13072000) subdivided into o Kreis Rostock – Binnenland Nord (913072001) o Kreis Rostock – Küste (913072002) o Kreis Rostock – Binnenland Süd (913072003) - Vogtlandkreis (AGS: 14523000) subdivided into o Vogtlandkreis – Tiefland (914523001) o Vogtlandkreis – Bergland (914523002) - Stadt Frankfurt am Main (AGS: 06412000) subdivided into o Frankfurt-Nord (706412101) o Frankfurt-Süd (706412102)
For these special areas new WarncellIDs are provided, which are structured according to AGS. 3.6.4 Implementation Note Currently only digits 1-9 are in use for WarncellID types. In the future the need may arise to use WarncellID types with multiple digits. To reliably extract the AGS from the WarncellID, e.g. to analyse the federal state (STATE) of an area, always process the WarncellID from the end: use the last 8 digits of the WarncellID, instead of removing the leading digit of the WarncellID type prefix.