Google Public Alerts CAP v1.0

This section describes Google-specific differences with the CAP 1.2 XML format. The Google CAP schema is available for download from GitHub.

Overview

Alert message data must be provided in CAP 1.2 XML format. (CAP 1.1 XML format also is accepted.)

Google Public Alerts requires some elements that are optional in the OASIS spec, such as <expires>, <description>, and <area>. These elements allow Google to process and display your alerts effectively. For example, specifying <area> helps us target your alert to the users most likely to find it relevant based on their location.

The tables below list the standard CAP 1.2 message elements as modified by the additional Google Public Alert requirements. These elements, including the Google modifications, comprise the data dictionary for CAP-Google. They have been implemented in the Google CAP validator as Google Public Alerts CAP v1.0.

Terminology

  1. 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 RFC 2119.
  2. Where an element's optionality has changed from the OASIS CAP 1.2 specification, the new value is bold and highlighted in RED.

About the requirements tables

The "Optionality" columns in the tables below classify each element as one of the following:

  1. REQUIRED: Your feed is considered invalid if it doesn't include a properly-formatted value for this tag
  2. CONDITIONAL: Optional, but conditioned on the value of another tag
  3. OPTIONAL: These tags are supported to allow you to tailor results based on your application

Google CAP also specifies additional requirements about the format and content of field values. The "notes and requirements" columns provide details and reasons for these.

<alert> element and sub-elements

Element Name Optionality CAP-Google notes and requirements
<alert> REQUIRED
<identifier> REQUIRED
<sender> REQUIRED
<sent> REQUIRED 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> REQUIRED 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> REQUIRED <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> OPTIONAL
<scope> REQUIRED
<restriction> CONDITIONAL
<addresses> CONDITIONAL
<code> OPTIONAL
<note> OPTIONAL
<references> OPTIONAL 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> OPTIONAL

<info> element and sub-elements

Element Name Optionality CAP-Google notes and requirements
<info> REQUIRED At least one <info> must be present all <info> blocks must have the same <category> and <eventCode> values.
<language> OPTIONAL All <info> blocks with the same <language> must have the same values for <event>
<category> REQUIRED
<event> 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 (for example, 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 need 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.

<responseType> OPTIONAL <responseType> is strongly recommended, when applicable, along with a corresponding <instruction> value.
<urgency> REQUIRED Do not use "unknown" as this makes indexing alerts and relative rankings difficult. It's important for Google to know how this field 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> REQUIRED Do not use "unknown" as this makes indexing alerts and relative rankings difficult. It's important for Google to know how this field 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.
<certainty> REQUIRED Do not use "unknown" as this makes indexing alerts and relative rankings difficult. It's important for Google to know how this field 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.
<audience> OPTIONAL
<eventCode> OPTIONAL
<effective> OPTIONAL 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.
<onset> OPTIONAL 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> REQUIRED <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> OPTIONAL This is 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> OPTIONAL 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 explain the core of the alert (for example, "Pontoon bridge closure...."). The <headline> and <description> should not be the same, as the <description> should provide more detail than the headline.
<description> REQUIRED The value of this element 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, they serve different purposes in CAP and on the Google alerts pages.
<instruction> OPTIONAL Optional though strongly recommended. Google Public Alerts uses this field in alert details pages as the "recommended action". The<instruction> and <description> fields should be different, as they serve different purposes. Though some publishers simply copy one to the other, this makes for a poor user experience
<web> REQUIRED This should link to a copy of the original alert accessible on your web server. Note: Google validates against this.
<contact> 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. For example, "For emergencies call 911".
<parameter> OPTIONAL

<resource> element and sub-elements

Element Name Optionality CAP-Google notes and requirements
<resource> OPTIONAL Let us know when discussing your content with Google what kinds of resources may be linked to the message. For example, related web sites, .wav files, or images.
<resourceDesc> REQUIRED
<mimeType> REQUIRED
<size> OPTIONAL
<uri> OPTIONAL
<derefUri> CONDITIONAL
<digest> OPTIONAL

<area> element and sub-elements

Element Name Optionality CAP-Google notes and requirements
<area> REQUIRED <area> blocks must have at least one <circle>, <polygon>, or <geocode>. Google strongly prefers <circle> or <polygon>.
<areaDesc> REQUIRED <areaDesc> element may be used by Google to generate the location text string used in the alert title/headline.
<polygon> OPTIONAL

Polygons must meet the following requirements:

  • They must be closed.
  • They can't overlap.
  • Holes (for example, a donut-shaped polygon) and intersections aren't supported.
  • A minimum of four coordinate pairs are required. The first and last pairs of coordinates must be the same.
<circle> OPTIONAL
<geocode> OPTIONAL Values for <geocode> should be associated with a free and open dataset of polygons. As an example, in the USA, this includes the following:
  • 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> OPTIONAL
<ceiling> CONDITIONAL

Additional field requirements

Date/time fields

Date/Time fields MUST include the time zone. This applies to <sent>, <effective>, <onset>, and <expires>:

  1. 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.
  2. 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

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

  • <msgType> UPDATE or CANCEL must include at least one <references> element.
  • There are three ways to CANCEL events, in order of preference:
    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.

Refer to Sample updates and cancellations for examples.