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

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

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:

Related Documents and References

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:

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

 

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 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:

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:

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:

 <parameter>

   <valueName>EventAreaPolygon</valueName>

   <value>41.63,-100.52 41.56,-100.33 41.33,-100.56 41.38,-100.64 41.63,-100.52</value>

 </parameter>

 <parameter>

   <valueName>EventEndTime</valueName>

   <value>2012-02-28T16:45:00-06:00</value>

 </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

Elements Summary

The summary table classifies each parameter as follows:

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:

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:00for 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

  1. Date/Time fields SHALL include time zone: this applies to <sent>, <offset>, <expires>, <onset>
  1. Event changes or expiration should be handled in the following way:
  1. Set an <expires> datetime for each event, with the message description setting the expectation that this alert will end on its own
  2. Issue a new <alert> with <msgType> UPDATE, <responseType> “All Clear”, and <expires> a short time in the future.
  3. Issue a new <alert> with <msgType> CANCEL.

Examples

“Googly” NOAA CAP alert

Notes:

<?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.

-->

<alert xmlns="urn:oasis:names:tc:emergency:cap:1.1">

<!-- http-date = Tue, 28 Feb 2012 10:15:00 GMT -->

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

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

<sent>2012-02-28T16:15:00-06:00</sent>

<status>Actual</status>

<msgType>Alert</msgType>

<scope>Public</scope>

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

<info>

 <category>Met</category>

 <event>Tornado Warning</event>

 <urgency>Immediate</urgency>

 <severity>Extreme</severity>

 <certainty>Observed</certainty>

 <eventCode>

   <valueName>SAME</valueName>

   <value>TOR</value>

 </eventCode>

 <effective>2012-02-28T16:15:00-06:00</effective>

 <expires>2012-02-28T16:45:00-06:00</expires>

 <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>    

<parameter>

   <valueName>WMOHEADER</valueName>

   <value />

 </parameter>

 <parameter>

   <valueName>UGC</valueName>

   <value>NEC111-113</value>

 </parameter>

 <parameter>

   <valueName>VTEC</valueName>

   <value>/O.NEW.KLBF.TO.W.0001.120228T2215Z-120228T2245Z/</value>

 </parameter>

 <parameter>

   <valueName>TIME...MOT...LOC</valueName>

   <value>2215Z 205DEG 33KT 4140 10054</value>

 </parameter>

 <area>

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

   <polygon>41.63,-100.52 41.56,-100.33 41.33,-100.56 41.38,-100.64 41.63,-100.52</polygon>

   <geocode>

     <valueName>FIPS6</valueName>

     <value>031111</value>

   </geocode>

   <geocode>

     <valueName>FIPS6</valueName>

     <value>031113</value>

   </geocode>

   <geocode>

     <valueName>UGC</valueName>

     <value>NEC111</value>

   </geocode>

   <geocode>

     <valueName>UGC</valueName>

     <value>NEC113</value>

   </geocode>

 </area>

</info>

</alert>

“Googly” USGS Earthquake Alert

Notes:

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

<alert xmlns="urn:oasis:names:tc:emergency:cap:1.1">

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

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

<sent>2012-02-06T11:59:34+08:00</sent>

<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>

 <category>Geo</category>

 <event>Earthquake</event>

 <responseType>Monitor</responseType>

 <urgency>Past</urgency>

 <severity>Moderate</severity>

 <certainty>Likely</certainty>

 <eventCode>

   <valueName>SAME</valueName>

   <value>EQW</value>

 </eventCode>

 <onset>2012-02-06T11:49:16+08:00</onset>

 <expires>2012-02-13T11:59:34+08:00</expires>

 <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>

 <instruction>None</instruction>

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

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

 <parameter>

   <valueName>EventTime</valueName>

   <value>20120206T034916.920Z</value>

 </parameter>

 <parameter>

   <valueName>EventIDKey</valueName>

   <value>usB0007WGQ</value>

 </parameter>

 <parameter>

   <valueName>Version</valueName>

   <value>8</value>

 </parameter>

 <parameter>

   <valueName>Magnitude</valueName>

   <value>6.8</value>

 </parameter>

 <parameter>

   <valueName>Depth</valueName>

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

 </parameter>

 <parameter>

   <valueName>HorizontalError</valueName>

   <value>13.5 km</value>

 </parameter>

 <parameter>

   <valueName>VerticalError</valueName>

   <value>11.5 km</value>

 </parameter>

 <parameter>

   <valueName>NumStations</valueName>

   <value>72</value>

 </parameter>

 <parameter>

   <valueName>NumPhases</valueName>

   <value>75</value>

 </parameter>

 <parameter>

   <valueName>MinDistance</valueName>

   <value>744.7 km</value>

 </parameter>

 <parameter>

   <valueName>RMSTimeError</valueName>

   <value>1.03 seconds</value>

 </parameter>

 <parameter>

   <valueName>AzimuthalGap</valueName>

   <value>48 degrees</value>

 </parameter>

 <resource>

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

   <mimeType>text/html</mimeType>

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

 </resource>

 <resource>

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

   <mimeType>text/html</mimeType>

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

 </resource>

 <resource>

   <resourceDesc>USGS ShakeMap</resourceDesc>

   <mimeType>text/html</mimeType>

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

 </resource>

 <resource>

   <resourceDesc>Did You Feel It?  Tell Us!</resourceDesc>

   <mimeType>text/html</mimeType>

   <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>

   <circle>9.964,123.246 32.5</circle>

 </area>

</info>

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">

 <SignedInfo>

   <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments" />

   <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />

   <Reference URI="">

     <Transforms>

       <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />

     </Transforms>

     <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />

     <DigestValue>WiQXo/G8s9zm6C42J0G3hKbB1x8=</DigestValue>

   </Reference>

 </SignedInfo>

 <SignatureValue>XoZcnbjku6FMCXCbhpnL6OdLg4fRlnCiS0whm9TrDHOMH4rITweuWd4oyTbzEy7I25QFrdyYWZGC

I7upvXbfRLESKYym/HFwRUehA3uJyum/pcfQPf2BaR7E2/0vv+QPmJzcm8iVWtuDZ6IYoORn8zmO

bVZzvpuGkLfIBjtk4MWyx7iACBlYdn5SDXrPamy9YrWxdkdfPlOXAS2aCqoJUqx/VUphT9tZOBLc

L+hKng1Ywtth3xkrlA/p0CxXyOAmIQzcTp8hmBJTrN5LKqxO9jCZr12lN0J9vwQnKt3UXusp+qAx

p3/XL4fOEw1Wxxl5z2WuekklKp4wuMSW4TDUbQ==</SignatureValue>

 <KeyInfo>

   <KeyValue>

     <RSAKeyValue>

       <Modulus>iqSOSGRoJI7hg8yUih5WFOPcEsc4bZhYwQ1etBSM5eYip4pc2xr3n5aMnJOCatFUIiJBxIfopp+9

w5W52LvqQJst+qkfv6ZV6ZUu86lLV1znXKOf10b1JtBtkZiJA+alaE1xd+oMmz+KdYRpoAaVFKM7

ClnXu16pV9ZLHHtLmAe6sO+MIZ+up1Q+9CqF32rJXM4exPKqdEBCHYrz1iCAjDApRwxXb60D4wtQ

EtTF9t9z3k1RjnbviozWQuF/k5MzdcVbCfRJk8s3kF+oaJolWd3ukOfExpBQFiIQ8ritEbLWS+z3

yd66g9CdXRvJZWht4MWamDOClBaRnNKGflutAQ==</Modulus>

       <Exponent>AQAB</Exponent>

     </RSAKeyValue>

   </KeyValue>

 </KeyInfo>

</Signature>

</alert>

Revision History

Authors

Nigel Snoad and Steve Hakusa, Google Crisis Response team.