CAP for the Web -

Google Public Alerts Technical Guide

Google CAP documentation and additional requirements to get CAP ready for the Web

Version: Public v1.0

Date: 2012-05-22

Technical comments and feedback to: google-public-alerts@google.com

Partnership questions to: gcr-partnerships@google.com

Technical Guide Goals

Google Public Alerts uses the Common Alerting Protocol (CAP), an international alerting standard that has been adopted by many government and commercial alerting services.

While the OASIS CAP standard and various national profiles provide a degree of specificity on data elements, Google Public Alerts also takes a different approach to public alerting than many other online alerting systems. We are attempting to surface relevant alerts to users without having them sign up for any particular feed, thus we have found that to index, search and show CAP successfully on the web we need to be more specific about various fields and elements.

This document outlines Google Public Alerts’ requirements for CAP, specifying restrictions on data elements and additional information required for Google to republish CAP data to the web and target non-expert users.

This Technical Guide should be accompanied by 2 documents:

The Google Public Alerts partner presentation is the overview on the GPA product. It will soon be available online.
The Google Public Alerts new publisher playbook is the set of workflow instructions and FAQs that helps trusted publishers to integrate their data into Google Public Alerts.

Data Requirements

Google Public Alerts is an emergency alerting system that is designed to show Google’s users relevant emergency alerts from authoritative sources when and where they need them. This means surfacing relevant alerts on Google’s mobile, web and map properties.

Google Public Alerts also takes a different approach to public alerting than many other online alerting systems. We are attempting to surface relevant alerts to users without having them sign up for any particular feed. In order to do this, we need to know additional alert content than those specified in standard CAP:

The geographical area in which people are affected by this alert
The significance of the alert, preferably relative to each other or a standard set such as NOAA’s
When the alert begins and expires
Whether or not this alert is an update of a previous alert

How Google Public Alerts displays CAP

The following are screenshots of Google Public Alerts (as of 2012-04-26) showing an alert onebox on Google Maps and an alert details page. The screenshots have been annotated to show how CAP elements appear on the page to users.

Note: <string> elements are from CAP, [string] elements are non-CAP static content that’s separate from your CAP feed, but required/requested by Google

Onebox on maps

Alert details page

In addition: Alert Details

[recommended actions text, url] is non-CAP information required by Google. Links will appear as a section of “Recommended actions” beneath the information from the <instructions> field of the CAP document.

How to create and validate Google CAP data

Google is creating and collecting a set of tools and resources to help agencies and providers move their public alerts data towards CAP compliance.

The Google CAP validator validates event messages against Google CAP and other CAP profiles. Providers can upload their CAP data, or point the tool to the URL where the CAP data is hosted.
Providers can also download the latest version of the Google CAP schema from http://code.google.com/p/cap-library/source/browse/schema/ and validate offline for development.

The Google CAP Library is an open-source project that provides a collection of code and tools built in Java. We welcome contributions to this resource - please read through the Developer How-To guide at http://code.google.com/p/cap-library/wiki/DeveloperHowTo to learn how to participate.

How to publish CAP data to Google

From Google’s experience and research we believe the following hosting and data setup will help citizens access relevant iformation in emergencies:

Web feeds — maximise public access to alert warning messages by publishing them online using open, publicly available and Internet-accessible web feeds such as RSS or Atom (preferred) or EDXL-DE
Authentication and security — as efficacy of alert warning systems depend upon them being secure and trusted by the public, publishers should digitally sign their alerts, or use HTTPS (OASIS CAP specification specifies how to do this technically).
Usage guide — enhance the usability of CAP alerts and improve machine readability by fully defining the preferred usage of CAP alert data elements.
Pub-sub rather than polling — use a subscription/push system to increase efficiency of distribution and alleviate concerns about polling intervals, thus ensuring that new alerts are pushed out instantly to subscribers. This is preferable to simply publishing a feed or “pull” API such as RSS which requires each subscriber to regularly check or poll for updates.

Authentication and Security

The efficacy of alert warning systems depends upon them being secure and trusted by the public. Consequently, it is vital that the distribution of alerts include authentication through digital signatures or secure transmission via HTTPS. These measures would prevent spoofing or hacking and ensure the credibility of the alert system.

Note that digital signatures are preferred to HTTPS, as per section 3.3.4 of the common alerting protocol spec: http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html

If you use a digital signature system, we recommend that you either use a certificate authority, or ensure that you provide us updates to your public key ASAP via a pre-determined mechanism. This will prevent any unexpected disruptions to your data updates.

Usage Guide from Publishers

Even though the CAP standard establishes the basic structure and data elements for a CAP alert, it leaves considerable room for inconsistencies in how and when the various data elements are employed. Because Google Public Alerts is developing a set of automated tools to process, publish online, and act on CAP alerts, we recommend that publishers and providers of CAP profiles provide us a usage guide that more fully define the preferred usage of their CAP alert data elements.

For instance, Canada and Australia have what is called a "CAP Profile" that defines this list for all alert providers in the country. In those cases, we are happy to take the country list.

Other examples include:

EAS has a number of event types
NOAA CAP 1.2 has a limited number of event types (published here as of Jan 2012)

Google recommends that publishers follow data best practices on top of the required CAP elements, so that alerts we surface are clear, relevant, and actionable for the user. Publishers should provide a usage guide that’s preferably derived from an existing CAP profile, plus the additional information below:

The <incidents> field - Provide guidance on its usage and generation. For example, state whether specifying incidents follows a template or standard format, or if it’s free text input. Also state who enters these incident strings, and how these strings are shared among different agencies.
The event area - Provide a way to specify the event area, and not just the alertable area. An example is wildfires/bushfires: the CAP <area> specifies the alertable area, the area in which people should be warned about a fire. Since there is no good construct in CAP to specify the actual area where the fire is burning, we suggest using a custom <parameter>, for example:

<valueName>EventAreaPolygon</valueName>

</parameter>

Event end time - Provide a way to handle the end time of an event, in addition to the <expires> time of an alert. We see frequently with alerts from the National Weather Service in the US, that the expires time denotes the “time before which an update to the alert is expected” and not the “time which the alertable event is expected to end”. While the former is useful for routing and displaying messages, the latter is more useful for notifying the public. Thus we also suggest using a custom parameter, for example:

<valueName>EventEndTime</valueName>

</parameter>

Publish-subscribe rather than polling

Google has designed PubSubHubbub - a simple, open, server-to-server web-hook-based publish/subscribe protocol as an extension to Atom and RSS: http://code.google.com/p/pubsubhubbub/. It is an open source reference implementation. Parties (servers) speaking the PubSubHubbub protocol can get near-instant notifications (via web hook callbacks) when a topic (feed URL) they have subscribed to is updated.

Google.org also created Alert Hub to aggregate all data feeds with emergency information in one location using PubSubHubbub: http://alert-hub.appspot.com/. By pushing alerts and other kinds of emergency information here, publishers can make it easy for developers around the world to ingest and distribute relevant data to users.

Google CAP recommendations and specifications

The following CAP elements have restrictions, requirements or recommended forms for Google Public Alerts, and comprise the data dictionary for CAP-Google. They have been implemented in the Google CAP validator (http://goo.gl/jANLX) as the CAP-Google profile.

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].
Where an element’s optionality has changed from the OASIS CAP 1.2 specification the new value is bold and highlighted in RED

Elements Summary

The summary table classifies each parameter as follows:

Required: Your feed is considered invalid if it doesn’t include a properly-formatted value for this tag
Conditional: Optional, but conditioned on the value of another tag
Optional: These tags are supported to allow you to tailor results based on your application

Name	Summary	Required
	"alert" Element and Sub-elements
alert	Container for all component parts of the alert message	Required
identifier	Identifier of the alert message	Required
sender	Identifier of the sender of the alert message	Required
sent	Time and date of the origination of the alert message	Required
status	The appropriate handling of the alert message	Required
msgType	Nature of the alert message	Required
source	Source of the alert message	Optional
scope	The intended distribution of the alert message	Required
restriction	The rule for limiting distribution of the restricted alert message. Used when scope value is “restricted”	Conditional
addresses	The group listing of intended recipients of the alert message	Conditional
code	Code denoting the special handling of the alert message	Optional
note	The purpose or significance of the alert message	Optional
references	Group listing identifying earlier message(s) referenced by the alert message	Optional
incidents	Group listing naming the referent incident(s) of the alert message	Optional
	“info” Element and Sub-elements
info	Container for all component parts of the info sub-element of the alert message	Required
language	Language of the info sub-element of the alert message	Optional
category	Category of the subject event of the alert message	Required
event	The type of the subject event of the alert message	Required
responseType	The type of action recommended for the target audience	Optional
urgency	The urgency of the subject event of the alert message	Required
severity	The severity of the subject event of the alert message	Required
certainty	The certainty of the subject event of the alert message	Required
audience	The intended audience of the alert message	Optional
eventCode	System-specific code identifying the event type of the alert message	Optional
effective	Effective time of the information of the alert message	Optional
onset	Expected time of the beginning of the subject event of the alert message	Optional
expires	Expiry time of the information of the alert message	Required
senderName	Originator of the alert message	Optional
headline	Text headline of the alert message	Optional
description	The text describing the subject event of the alert message	Required
instruction	Recommended action to be taken by recipients of the alert message	Optional
web	The hyperlink associating additional information with the alert message	Required
contact	The contact for follow-up and confirmation of the alert message	Optional
parameter	A system-specific additional parameter associated with the alert message	Optional
	“resource” Element and Sub-elements
resource	Container for all component parts of the resource sub-element of the info sub-element of the alert element	Optional
resourceDesc	The type and content of the resource file	Required
mimeType	the MIME content type and sub-type describing the resource file	Required
size	The integer indicating the size of the resource file	Optional
uri	The hyperlink for the resource file	Optional
derefUri	The base-64 encoded data content of the resource file	Conditional
digest	The code representing the digital digest (“hash”) computed from the resource file	Optional
	“area” Element and Sub-elements
area	The container for all component parts of the area sub-element of the info sub-element of the alert message	Required
areaDesc	The text describing the affected area of the alert message	Required
polygon	The paired values of points defining a polygon that delineates the affected area of the alert message	Optional
circle	The paired values of a point and radius delineating the affected area of the alert message	Optional
geocode	Geographic code delineating the affected area of the alert message	Optional
altitude	The specific or minimum altitude of the affected area of the alert message	Optional
ceiling	The maximum altitude of the affected area of the alert message	Conditional

Elements Definitions

Element Name	Definition and (Optionality)	CAP 1.2 Notes or Value Domain	Google CAP for the web notes and requirements
“alert” Element and sub-elements
alert	The container for all component parts of the alert message (REQUIRED)	(1) Surrounds CAP alert message sub-elements. (2) MUST include the xmlns attribute referencing the CAP URN as the namespace, e.g.: <cap:alert xmlns:cap="urn:oasis:names:tc:emergency:cap:1.2"> [sub-elements] </cap:alert> (3) In addition to the specified sub-elements, MAY contain one or more <info> blocks.
identifier	The identifier of the alert message (REQUIRED)	(1) A number or string uniquely identifying this message, assigned by the sender. (2) MUST NOT include spaces, commas or restricted characters (< and &).
sender	The identifier of the sender of the alert message (REQUIRED)	(1) Identifies the originator of this alert. Guaranteed by assigner to be unique globally; e.g., may be based on an Internet domain name. (2) MUST NOT include spaces, commas or restricted characters (< and &).
sent	The time and date of the origination of the alert message (REQUIRED)	(1) The date and time SHALL be represented in the DateTime Data Type (See Implementation Notes) format (e.g., "2002-05-24T16:49:00-07:00" for 24 May 2002 at 16:49 PDT). (2) Alphabetic timezone designators such as “Z” MUST NOT be used. The timezone for UTC MUST be represented as “-00:00”.	If the location cited in the <area> block falls within a single timezone, <effective> SHOULD specify time in that zone, including allowance for Daylight Savings when applicable. When the content of a message applies across multiple timezones, the message producer SHOULD use UTC times in preference to local times.
status	The code denoting the appropriate handling of the alert message (REQUIRED)	Code Values: “Actual” - Actionable by all targeted recipients “Exercise” - Actionable only by designated exercise participants; exercise identifier SHOULD appear in <note> “System” - For messages that support alert network internal functions “Test” - Technical testing only, all recipients disregard “Draft” – A preliminary template or draft, not actionable in its current form	Require the use of “test” as <status> for all test messages. Sending test messages “actual” is considered extremely bad form and will lead Google to suspend a publisher.
msgType	The code denoting the nature of the alert message (REQUIRED)	Code Values: “Alert” - Initial information requiring attention by targeted recipients “Update” - Updates and supercedes the earlier message(s) identified in <references> “Cancel” - Cancels the earlier message(s) identified in <references> “Ack” - Acknowledges receipt and acceptance of the message(s) identified in <references> “Error” - Indicates rejection of the message(s) identified in <references>; explanation SHOULD appear in <note>	<msgType> UPDATE or CANCEL must include at least one <references> element. As specified in the CAP standard, any alert message that is updating a previous alert should use <msgType>Update</msgType> and set <references> to all previous messages that haven't reached their <expires> date. The UPDATE or CANCEL must apply to a non-expired alert, and hence all related messages and unexpired alerts must be referenced when an UPDATE or CANCEL is issued.
source	The text identifying the source of the alert message (OPTIONAL)	The particular source of this alert; e.g., an operator or a specific device.
scope	The code denoting the intended distribution of the alert message (REQUIRED)	Code Values: “Public” - For general dissemination to unrestricted audiences “Restricted” - For dissemination only to users with a known operational requirement (see <restriction>, below) “Private” - For dissemination only to specified addresses (see <addresses>, below)
restriction	The text describing the rule for limiting distribution of the restricted alert message (CONDITIONAL)	Used when <scope> value is "Restricted".
addresses	The group listing of intended recipients of the alert message (CONDITIONAL)	(1) Required when <scope> is “Private”, optional when <scope> is “Public” or “Restricted”. (2) Each recipient SHALL be identified by an identifier or an address. (3) Multiple space-delimited addresses MAY be included. Addresses including whitespace MUST be enclosed in double-quotes.
code	The code denoting the special handling of the alert message (OPTIONAL)	(1) Any user-defined flag or special code used to flag the alert message for special handling. (2) Multiple instances MAY occur.
note	The text describing the purpose or significance of the alert message (OPTIONAL)	The message note is primarily intended for use with <status> “Exercise” and <msgType> “Error”.
references	The group listing identifying earlier message(s) referenced by the alert message (OPTIONAL)	(1) The extended message identifier(s) (in the form sender,identifier,sent) of an earlier CAP message or messages referenced by this one. (2) If multiple messages are referenced, they SHALL be separated by whitespace.	Required if msgType is “Update” or “Cancel” Where your system republishes CAP content from another publisher you should include alert CAP in full, but if it’s been edited use the <references> tag to link to the original source.
incidents	The group listing naming the referent incident(s) of the alert message (OPTIONAL)	(1) Used to collate multiple messages referring to different aspects of the same incident. (2) If multiple incident identifiers are referenced, they SHALL be separated by whitespace. Incident names including whitespace SHALL be surrounded by double-quotes.
“info” element and sub-elements
info	The container for all component parts of the info sub-element of the alert message (REQUIRED)	(1) Multiple occurrences are permitted within a single <alert>. If targeting of multiple <info> blocks in the same language overlaps, information in later blocks may expand but may not override the corresponding values in earlier ones. Each set of <info> blocks containing the same language identifier SHALL be treated as a separate sequence. (2) In addition to the specified sub-elements, MAY contain one or more <resource> blocks and/or one or more <area> blocks.	At least one <info> must be present all <info> blocks must have the same <category> and <eventCode> values.
language	The code denoting the language of the info sub-element of the alert message (OPTIONAL)	(1) Code Values: Natural language identifier per [RFC 3066]. (2) If not present, an implicit default value of "en-US" SHALL be assumed. (3) A null value in this element SHALL be considered equivalent to “en-US.”	All <info> blocks with the same <language> must have the same values for <event>
category	The code denoting the category of the subject event of the alert message(REQUIRED)	(1) Code Values: “Geo” - Geophysical (inc. landslide) “Met” - Meteorological (inc. flood) “Safety” - General emergency and public safety “Security” - Law enforcement, military, homeland and local/private security “Rescue” - Rescue and recovery “Fire” - Fire suppression and rescue “Health” - Medical and public health “Env” - Pollution and other environmental “Transport” - Public and private transportation “Infra” - Utility, telecommunication, other non-transport infrastructure “CBRNE” – Chemical, Biological, Radiological, Nuclear or High-Yield Explosive threat or attack “Other” - Other events (2) Multiple instances MAY occur within an <info> block.
event	The text denoting the type of the subject event of the alert message (REQUIRED)		length: <35 characters Google Public Alerts requires CAP that supports a finite and pre-defined set of <event> types. Alerts with <event> not drawn from this set for the appropriate profile or as provided to Google will not be published. This is a common pattern for many national CAP profiles e.g. CAP-CP and CAP-AU. The set of event types should be defined in a CSV or Google Spreadsheet document (sample here). We want these to be short (<35 char) and descriptive enough for the public to understand; we use the event string (or sometimes the <headline>) in the title of our alert. If your <event> names aren’t like this, then we'd want a clear mapping to an "ordinary user" understandable string of <35 char that we can use in it's place. This should go either in the <headline> element (as the first 35 characters of the <140 char string) or be listed as a separate string for each event type. Canada and Australia have CAP profiles, that define this list for all alert providers in the country. Where such a profile exists we are happy to use it. Examples: EAS has a number of event types NOAA CAP 1.2 has a limited number of event types (published here as of Jan 2012)
responseType	The code denoting the type of action recommended for the target audience (OPTIONAL)	(1) Code Values: “Shelter” – Take shelter in place or per <instruction> “Evacuate” – Relocate as instructed in the <instruction> “Prepare” – Make preparations per the <instruction> “Execute” – Execute a pre-planned activity identified in <instruction> “Avoid” – Avoid the subject event as per the <instruction> “Monitor” – Attend to information sources as described in <instruction> “Assess” – Evaluate the information in this message. (This value SHOULD NOT be used in public warning applications.) “AllClear” – The subject event no longer poses a threat or concern and any follow on action is described in <instruction> “None” – No action recommended (2) Multiple instances MAY occur within an <info> block.	<responseType> is strongly recommended, when applicable, along with a corresponding <instruction> value.
urgency	The code denoting the urgency of the subject event of the alert message (REQUIRED)	(1) The <urgency>, <severity>, and <certainty> elements collectively distinguish less emphatic from more emphatic messages. (2) Code Values: “Immediate” - Responsive action SHOULD be taken immediately “Expected” - Responsive action SHOULD be taken soon (within next hour) “Future” - Responsive action SHOULD be taken in the near future “Past” - Responsive action is no longer required “Unknown” - Urgency not known	We very much don’t want “unknown” as this makes indexing alerts and relative rankings difficult. It’s important for Google to know how urgency is set and by whom, though this is outside the scope of the formal profile. While preferably this value is set by the publisher on a case-by-case basis following clear triggering guidelines, they might be fixed by <event>, though this reduces the flexibility of alert authors. As an example, NOAA in the USA sets urgency statically based on event type.
severity	The code denoting the severity of the subject event of the alert message (REQUIRED)	(1) The <urgency>, <severity>, and <certainty> elements collectively distinguish less emphatic from more emphatic messages. (2) Code Values: “Extreme” - Extraordinary threat to life or property “Severe” - Significant threat to life or property “Moderate” - Possible threat to life or property “Minor” – Minimal to no known threat to life or property “Unknown” - Severity unknown	We very much don’t want “unknown” as this makes indexing alerts and relative rankings difficult. It’s important for Google to know how it’s set and by whom, though this is outside the scope of the formal profile. While preferably this value is set by the publisher on a case-by-case basis following clear triggering guidelines, they might be fixed by <event>, though this reduces the flexibility of alert authors. As an example, NOAA in the USA sets urgency statically based on event type.
certainty	The code denoting the certainty of the subject event of the alert message (REQUIRED)	(1) The <urgency>, <severity>, and <certainty> elements collectively distinguish less emphatic from more emphatic messages. (2) Code Values: “Observed” – Determined to have occurred or to be ongoing “Likely” - Likely (p > ~50%) “Possible” - Possible but not likely (p <= ~50%) “Unlikely” - Not expected to occur (p ~ 0) “Unknown” - Certainty unknown (3) For backward compatibility with CAP 1.0, the deprecated value of “Very Likely” SHOULD be treated as equivalent to “Likely”.	We very much don’t want “unknown” as this makes indexing alerts and relative rankings difficult. It’s important for Google to know how it’s set and by whom, though this is outside the scope of the formal profile. While preferably this value is set by the publisher on a case-by-case basis following clear triggering guidelines, they might be fixed by <event>, though this reduces the flexibility of alert authors. As an example, NOAA in the USA sets urgency statically based on event type.
audience	The text describing the intended audience of the alert message (OPTIONAL)
eventCode	A system-specific code identifying the event type of the alert message (OPTIONAL)	(1) Any system-specific code for event typing, in the form: <eventCode> <valueName>valueName</valueName> <value>value</value> </eventCode> where the content of “valueName” is a user-assigned string designating the domain of the code, and the content of “value” is a string (which may represent a number) denoting the value itself (e.g., valueName ="SAME" and value="CEM"). (2) Values of “valueName” that are acronyms SHOULD be represented in all capital letters without periods (e.g., SAME, FIPS, ZIP). (3) Multiple instances MAY occur within an <info> block.
effective	The effective time of the information of the alert message (OPTIONAL)	(1) The date and time SHALL be represented in the DateTime Data Type (See Implementation Notes) format (e.g., “2002-05-24T16:49:00-07:00” for 24 May 2002 at 16: 49 PDT). (2) Alphabetic timezone designators such as “Z” MUST NOT be used. The timezone for UTC MUST be represented as “-00:00”. (3) If this item is not included, the effective time SHALL be assumed to be the same as in <sent>.	Time zone fields must be included in all date/time values. If the location cited in the <area> block falls within a single timezone, <effective> SHOULD specify time in that zone, including allowance for Daylight Savings when applicable. When the content of a message applies across multiple timezones, the message producer SHOULD use UTC times in preference to local times. Same for onset, expires, sent.
onset	The expected time of the beginning of the subject event of the alert message (OPTIONAL)	(1) The date and time SHALL be represented in the DateTime Data Type (See Implementation Notes) format (e.g., “2002-05-24T16:49:00-07:00” for 24 May 2002 at 16: 49 PDT). (2) Alphabetic timezone designators such as “Z” MUST NOT be used. The timezone for UTC MUST be represented as “-00:00”.	Time zone fields must be included in all date/time values. If the location cited in the <area> block falls within a single timezone, <effective> SHOULD specify time in that zone, including allowance for Daylight Savings when applicable. When the content of a message applies across multiple timezones, the message producer SHOULD use UTC times in preference to local times.
expires	The expiry time of the information of the alert message (REQUIRED)	(1) The date and time SHALL be represented in the DateTime Data Type (See Implementation Notes) format (e.g., “2002-05-24T16:49:00-07:00” for 24 May 2002 at 16:49 PDT). (2) Alphabetic timezone designators such as “Z” MUST NOT be used. The timezone for UTC MUST be represented as “-00:00”. (3) If this item is not provided, each recipient is free to set its own policy as to when the message is no longer in effect.	<expires> must come after <effective> in time order. Time zone fields must be included in all date/time values. If the location cited in the <area> block falls within a single timezone, <effective> SHOULD specify time in that zone, including allowance for Daylight Savings when applicable. When the content of a message applies across multiple timezones, the message producer SHOULD use UTC times in preference to local times.
senderName	The text naming the originator of the alert message (OPTIONAL)	The human-readable name of the agency or authority issuing this alert.	Strongly recommended. Having the human readable name for the sender enables the <web> link to be shown in a user-friendly way as per the publisher/sender’s preferences. In addition this allows alert aggregators to acts to publish from multiple authorities.
headline	The text headline of the alert message (OPTIONAL)	A brief human-readable headline. Note that some displays (for example, short messaging service devices) may only present this headline; it SHOULD be made as direct and actionable as possible while remaining short. 160 characters MAY be a useful target limit for headline length.	length: <140 characters The headline string can be free text, but should be <140 characters (CAP 1.2 suggests < 160 for text messages). The start of this string should be a few descriptive words that can be used to understand the core of the alert e.g. “Pontoon bridge closure....”. The <headline> and <description> should not be the same as the <description> should provide more detail than the headline.
description	The text describing the subject event of the alert message (REQUIRED)	An extended human readable description of the hazard or event that occasioned this message.	Must not be the same as the <instruction> element. Google uses <description> to populate the "Message" section of our page and <instruction> to populate the "Recommended actions" section. Thus even though some publishers make them identical, we don’t want both to be the same as they serve different purposes in CAP and on the Google alerts pages.
instruction	The text describing the recommended action to be taken by recipients of the alert message (OPTIONAL)	An extended human readable instruction to targeted recipients. If different instructions are intended for different recipients, they should be represented by use of multiple <info> blocks.	Optional though strongly recommended. Google Public Alerts uses this field in alert details pages as the “recommended action” (see here). The <instruction> and <description> fields should be different. They serve different purposes, but some publishers simply copy one to the other and this makes for a poor user experience
web	The identifier of the hyperlink associating additional information with the alert message (REQUIRED)	A full, absolute URI for an HTML page or other text resource with additional or reference information regarding this alert.	This should link to a copy of the original alert accessible on your web server. Note: Google validates against this.
contact	The text describing the contact for follow-up and confirmation of the alert message (OPTIONAL)		This contact field is optional but we strongly recommend it be present as it provides a way for users to provide feedback and respond to the alert. e.g. “For emergencies call 911”.
parameter	A system-specific additional parameter associated with the alert message (OPTIONAL)	(1) Any system-specific datum, in the form: <parameter> <valueName>valueName</valueName> <value>value</value> </parameter> where the content of “valueName” is a user-assigned string designating the domain of the code, and the content of “value” is a string (which may represent a number) denoting the value itself (e.g., valueName ="SAME" and value="CIV"). (2) Values of “valueName” that are acronyms SHOULD be represented in all capital letters without periods (e.g., SAME, FIPS, ZIP). (3) Multiple instances MAY occur within an <info> block.
“resource” element and sub-elements
resource	The container for all component parts of the resource sub-element of the info sub-element of the alert element (OPTIONAL)	(1) Refers to an additional file with supplemental information related to this <info> element; e.g., an image or audio file. (2) Multiple instances MAY occur within an <info> block.	Let us know when discussing your content with Google what kinds of resources may be linked to the message. e.g. related web sites, .wav files, images?
resourceDesc	The text describing the type and content of the resource file (REQUIRED)	The human-readable text describing the type and content, such as “map” or “photo”, of the resource file.
mimeType	The identifier of the MIME content type and sub-type describing the resource file (REQUIRED)	MIME content type and sub-type as described in [RFC 2046].(As of this document, the current IANA registered MIME types are listed at http://www.iana.org/assignments/media-types/)
size	The integer indicating the size of the resource file (OPTIONAL)	(1) Approximate size of the resource file in bytes. (2) For <uri> based resources, <size> SHOULD be included if available.
uri	The identifier of the hyperlink for the resource file (OPTIONAL)	A full absolute URI, typically a Uniform Resource Locator that can be used to retrieve the resource over the Internet OR a relative URI to name the content of a <derefUri> element if one is present in this resource block.
derefUri	The base-64 encoded data content of the resource file(CONDITIONAL)	(1) MAY be used either with or instead of the <uri> element in messages transmitted over one-way (e.g., broadcast) data links where retrieval of a resource via a URI is not feasible. (2) Clients intended for use with one-way data links MUST support this element. (3) This element MUST NOT be used unless the sender is certain that all direct clients are capable of processing it. (4) If messages including this element are forwarded onto a two-way network, the forwarder MUST strip the <derefUri> element and SHOULD extract the file contents and provide a <uri> link to a retrievable version of the file. (5) Providers of one-way data links MAY enforce additional restrictions on the use of this element, including message-size limits and restrictions regarding file types.
digest	The code representing the digital digest (“hash”) computed from the resource file (OPTIONAL)	Calculated using the Secure Hash Algorithm (SHA-1) per [FIPS 180-2].
“area” element and sub-elements
area	The container for all component parts of the area sub-element of the info sub-element of the alert message (REQUIRED)	(1) Multiple occurrences permitted, in which case the target area for the <info> block is the union of all the included <area> blocks. (2) MAY contain one or multiple instances of <polygon>, <circle> or <geocode>. If multiple <polygon>, <circle> or <geocode> elements are included, the area described by this <area> block is represented by the union of all the included elements.	<area> blocks must have at least one <circle> <polygon> or <geocode>. Google strongly prefers <circle> or <polygon>.
areaDesc	The text describing the affected area of the alert message (REQUIRED)	A text description of the affected area.	<areaDesc> element may be used by Google to generate the location text string used in the alert title/headline.
polygon	The paired values of points defining a polygon that delineates the affected area of the alert message (OPTIONAL)	(1) Code Values: The geographic polygon is represented by a whitespace-delimited list of [WGS 84] coordinate pairs. (See WGS 84 Note at end of this section) (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 <area> block.	Don’t leave polygons open or overlapping.
circle	The paired values of a point and radius delineating the affected area of the alert message (OPTIONAL)	(1) Code Values: The circular area is represented by a central point given as a [WGS 84] coordinate pair followed by a space character and a radius value in kilometers. (See WGS 84 Note at end of this section) (2) Multiple instances MAY occur within an <area> block.
geocode	The geographic code delineating the affected area of the alert message (OPTIONAL)	(1) Any geographically-based code to describe a message target area, in the form: <geocode> <valueName>valueName</valueName> <value>value</value> </geocode> where the content of “valueName” is a user-assigned string designating the domain of the code, and the content of “value” is a string (which may represent a number) denoting the value itself (e.g., valueName ="SAME" and value="006113"). (2) Values of “valueName” that are acronyms SHOULD be represented in all capital letters without periods (e.g., SAME, FIPS, ZIP). (3) Multiple instances MAY occur within an <area> block. (4) This element is primarily for compatibility with other systems. Use of this element presumes knowledge of the coding system on the part of recipients; therefore, for interoperability, it SHOULD be used in concert with an equivalent description in the more universally understood <polygon> and <circle> forms whenever possible.	Values for <geocode> should be associated with a free and open dataset of polygons. As an example in the USA this includes FIPS6 UGC code SAME US Zipcode This may also be provided as a fixed list provided as a http accessible CSV or Google Spreadsheet of valid <area> <geocodes> elements. Notices of updates to this list should be posted via a separate channel, preferably as RSS or email alerts.
altitude	The specific or minimum altitude of the affected area of the alert message (OPTIONAL)	(1) If used with the <ceiling> element this value is the lower limit of a range. Otherwise, this value specifies a specific altitude. (2) The altitude measure is in feet above mean sea level per the [WGS 84] datum.
ceiling	The maximum altitude of the affected area of the alert message (CONDITIONAL)	(1) MUST NOT be used except in combination with the <altitude> element. (2) The ceiling measure is in feet above mean sea level per the [WGS 84] datum.

Implementation Notes

Date/Time fields SHALL include time zone: this applies to <sent>, <offset>, <expires>, <onset>

If the location cited in the <area> block falls within a single timezone, <effective> SHOULD specify time in that zone, including allowance for Daylight Savings when applicable.
When the content of a message applies across multiple timezones, the message producer SHOULD use UTC times in preference to local times.

Event changes or expiration should be handled in the following way:

<msgType> UPDATE or CANCEL must include at least one <references> element
There are 3 ways to CANCEL events, in order of preference

Set an <expires> datetime for each event, with the message description setting the expectation that this alert will end on its own
Issue a new <alert> with <msgType> UPDATE, <responseType> “All Clear”, and <expires> a short time in the future.
Issue a new <alert> with <msgType> CANCEL.

Examples

“Googly” NOAA CAP alert

Notes:

this is a modified version of a NOAA CAP alert.
ALL CAPS isn’t best practice.
Changes to original feed include addition of <web> element, updated <areaDesc> fields.
Displayed on Google Public Alerts as this alert details page.

<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet href='https://alerts.weather.gov/cap/capatomproduct.xsl' type='text/xsl'?>

<!--

This atom/xml feed is an index to active advisories, watches and warnings

issued by the National Weather Service. This index file is not the complete

Common Alerting Protocol (CAP) alert message. To obtain the complete CAP

alert, please follow the links for each entry in this index. Also note the

CAP message uses a style sheet to convey the information in a human readable

format. Please view the source of the CAP message to see the complete data

set. Not all information in the CAP message is contained in this index of

active alerts.

-->

<identifier>NOAA-NWS-ALERTS-NE124C9B0E523C.TornadoWarning.124C9B0E5DF4NE.LBFTORLBF.8cb293373886cf0e5646bdb790df1f01</identifier>

<sender>w-nws.webmaster@noaa.gov</sender>

<status>Actual</status>

<msgType>Alert</msgType>

<scope>Public</scope>

<note>Alert for Lincoln; Logan (Nebraska) Issued by the National Weather Service</note>

<info>

<event>Tornado Warning</event>

<urgency>Immediate</urgency>

<severity>Extreme</severity>

<certainty>Observed</certainty>

</eventCode>

<senderName>NWS NorthPlatte (Central Nebraska - North Platte)</senderName>

<headline>Tornado Warning issued February 28 at 4:15PM CST until February 28 at 4:45PM CST by NWS NorthPlatte</headline>

<description>THE NATIONAL WEATHER SERVICE IN NORTH PLATTE HAS ISSUED A

* TORNADO WARNING FOR...

NORTH CENTRAL LINCOLN COUNTY IN SOUTHWEST NEBRASKA...

CENTRAL LOGAN COUNTY IN WEST CENTRAL NEBRASKA...

* UNTIL 445 PM CST

* AT 410 PM CST...TRAINED WEATHER SPOTTERS REPORTED A TORNADO 9 MILES

SOUTH OF STAPLETON. DOPPLER RADAR SHOWED THIS TORNADO MOVING

NORTHEAST AT 40 MPH.

* THE TORNADO WILL BE NEAR...

STAPLETON AND GANDY AROUND 425 PM CST.

TARBOZ LAKE AROUND 430 PM CST.

OTHER LOCATIONS IMPACTED BY THE TORNADO INCLUDE HIGHWAY 83 MILE

MARKER 120.</description>

<instruction>TO REPEAT...A TORNADO IS ON THE GROUND. TAKE COVER NOW. MOVE TO AN

INTERIOR ROOM ON THE LOWEST FLOOR OF A STURDY BUILDING. AVOID

WINDOWS. IF IN A MOBILE HOME...A VEHICLE OR OUTDOORS...MOVE TO THE

CLOSEST SUBSTANTIAL SHELTER AND PROTECT YOURSELF FROM FLYING DEBRIS.</instruction>

<web>http://alerts.weather.gov/cap/wwacapget.php?x=NE124C9B0E523C.TornadoWarning.124C9B0E5DF4NE.LBFTORLBF.8cb293373886cf0e5646bdb790df1f01

</web>

<valueName>WMOHEADER</valueName>

</parameter>

</parameter>

</parameter>

</parameter>

<area>

<areaDesc>Lincoln and Logan Counties NE</areaDesc>

</geocode>

</geocode>

</geocode>

</geocode>

</area>

</info>

</alert>

“Googly” USGS Earthquake Alert

Notes:

This feed includes a digital signature.
Alert has been updated from the USGS original to be more “Googly CAP”. Displayed on Google Public Alerts as this alert.

<?xml version="1.0" encoding="UTF-8"?>

<identifier>USGS-earthquakes-usB0007WGQ.32647958.20120206T035934.474Z</identifier>

<sender>http://earthquake.usgs.gov/research/monitoring/anss/neic/</sender>

<status>Actual</status>

<msgType>Update</msgType>

<scope>Public</scope>

<code>IPAWSv1.0</code>

<references>http://earthquake.usgs.gov/research/monitoring/anss/regions/ak/,USGS-earthquakes-at00lyyda6.32647931.20120206T035848.665Z,2012-02-06T03:58:48+00:00 http://earthquake.usgs.gov/research/monitoring/anss/regions/hi/,USGS-earthquakes-pt12037000.3264787B.20120206T035553.436Z,2012-02-06T03:55:53+00:00 http://earthquake.usgs.gov/research/monitoring/anss/regions/hi/,USGS-earthquakes-pt12037000.3264782A.20120206T035433.402Z,2012-02-06T03:54:33+00:00</references>

<info>

<event>Earthquake</event>

<responseType>Monitor</responseType>

<severity>Moderate</severity>

<certainty>Likely</certainty>

</eventCode>

<senderName>U.S. Geological Survey</senderName>

<headline>EQ 6.8 Dumaguete, Negros, Philippines - PRELIMINARY REPORT</headline>

<description>An earthquake with magnitude 6.8 occurred near Dumaguete, Negros, Philippines at 11:49:16.92 PHT on Feb 6, 2012. (This event has been reviewed by a seismologist.)</description>

<web>http://earthquake.usgs.gov/earthquakes/event/usB0007WGQ</web>

<contact>http://earthquake.usgs.gov/research/monitoring/anss/neic/</contact>

<valueName>EventTime</valueName>

</parameter>

<valueName>EventIDKey</valueName>

</parameter>

<valueName>Version</valueName>

</parameter>

<valueName>Magnitude</valueName>

</parameter>

<valueName>Depth</valueName>

<value>46.6 km (29.0 miles)</value>

</parameter>

<valueName>HorizontalError</valueName>

</parameter>

<valueName>VerticalError</valueName>

</parameter>

<valueName>NumStations</valueName>

</parameter>

<valueName>NumPhases</valueName>

</parameter>

<valueName>MinDistance</valueName>

</parameter>

<valueName>RMSTimeError</valueName>

<value>1.03 seconds</value>

</parameter>

<valueName>AzimuthalGap</valueName>

<value>48 degrees</value>

</parameter>

<resourceDesc>1-Tsunami Information Statement from the WC/ATWC</resourceDesc>

<uri>http://wcatwc.arh.noaa.gov/2012/02/06/lyyda6/01/messagelyyda6-01.htm</uri>

</resource>

<resourceDesc>USGS PAGER (shaking and loss estimates)</resourceDesc>

<uri>http://earthquake.usgs.gov/earthquakes/eventpage/usb0008wgq#pager</uri>

</resource>

<resourceDesc>USGS ShakeMap</resourceDesc>

<uri>http://earthquake.usgs.gov/earthquakes/eventpage/usb0008wgq#shakemap</uri>

</resource>

<uri>http://earthquake.usgs.gov/earthquakes/eventpage/usb0008wgq#dyfi_form</uri>

</resource>

<area>

<areaDesc>44 miles (70 km) NNW of Dumaguete, Negros, Philippines; 49 miles (79 km) WNW of Tagbilaran, Bohol, Philippines; 50 miles (80 km) SSE of Bacolod, Negros, Philippines; 356 miles (574 km) SSE of MANILA, Philippines</areaDesc>

</area>

</info>

</Transforms>

<DigestValue>WiQXo/G8s9zm6C42J0G3hKbB1x8=</DigestValue>

</Reference>

</SignedInfo>

<SignatureValue>XoZcnbjku6FMCXCbhpnL6OdLg4fRlnCiS0whm9TrDHOMH4rITweuWd4oyTbzEy7I25QFrdyYWZGC

I7upvXbfRLESKYym/HFwRUehA3uJyum/pcfQPf2BaR7E2/0vv+QPmJzcm8iVWtuDZ6IYoORn8zmO

bVZzvpuGkLfIBjtk4MWyx7iACBlYdn5SDXrPamy9YrWxdkdfPlOXAS2aCqoJUqx/VUphT9tZOBLc

L+hKng1Ywtth3xkrlA/p0CxXyOAmIQzcTp8hmBJTrN5LKqxO9jCZr12lN0J9vwQnKt3UXusp+qAx

p3/XL4fOEw1Wxxl5z2WuekklKp4wuMSW4TDUbQ==</SignatureValue>

<Modulus>iqSOSGRoJI7hg8yUih5WFOPcEsc4bZhYwQ1etBSM5eYip4pc2xr3n5aMnJOCatFUIiJBxIfopp+9

w5W52LvqQJst+qkfv6ZV6ZUu86lLV1znXKOf10b1JtBtkZiJA+alaE1xd+oMmz+KdYRpoAaVFKM7

ClnXu16pV9ZLHHtLmAe6sO+MIZ+up1Q+9CqF32rJXM4exPKqdEBCHYrz1iCAjDApRwxXb60D4wtQ

EtTF9t9z3k1RjnbviozWQuF/k5MzdcVbCfRJk8s3kF+oaJolWd3ukOfExpBQFiIQ8ritEbLWS+z3

yd66g9CdXRvJZWht4MWamDOClBaRnNKGflutAQ==</Modulus>

</RSAKeyValue>

</KeyValue>

</KeyInfo>

</Signature>

</alert>

Revision History

v 0.5 draft - 2012-05-12 added elements summary table
v 0.2 draft - 2012-04-27 final version before being released to the public. Provided full CAP profile and synced with CAP-Google validator
v 0.1 draft - copy and slight edits based on draft Google CAP publishers guide

Authors

Nigel Snoad and Steve Hakusa, Google Crisis Response team.

Technical Guide Goals

Related Documents and References

Data Requirements

How Google Public Alerts displays CAP

Onebox on maps

Alert details page

How to create and validate Google CAP data

How to publish CAP data to Google

Authentication and Security

Usage Guide from Publishers

Publish-subscribe rather than polling

Google CAP recommendations and specifications

Terminology

Elements Summary

Elements Definitions

Google CAP for the web notes and requirements

Implementation Notes

Examples

“Googly” NOAA CAP alert

“Googly” USGS Earthquake Alert

Revision History

Authors