Generate Alerts in CAP format

In addition to the CAP Standard, follow the Google-specific requirements for CAP files to ensure your alerts process correctly.

You have 2 options for generating alerts:

  1. Automated generation: Setup your system to dynamically format your database information into a CAP feed and auto-submit it to Google.
  2. Manual creation: Manually create and submit alert content as needed via a web-based application.

Automated generation

Check out the Google CAP library to get started in the language of your choice. The library supports creation, parsing, and validation of CAP feeds.

The Google team can provide support during implementation. Reach out to your Google team or google-public-alerts@google.com.

Manual creation

  1. Work with your IT team to install the CAPCreator™ open source web application onto a web server. Alternatively, you can create your own web application.
  2. As events occur, visit the application’s URL and use the interface to create alerts in CAP format.
  3. Your application publishes a feed to a web location; Google then pulls that information from your published feed.

Alert elements

The anatomy of an alert

An alert should answer these key questions:

  1. What is happening?
  2. When is it happening?
  3. What should people do?
  4. Where do alerts go?

The following is a simple example of an alert:

    <alert xmlns="urn:oasis:names:tc:emergency:cap:1.1">
        <identifier>AL20110412020900TornadoWarning</identifier>
        <sender>w-nws.webmaster@noaa.gov</sender>
        <sent>2011-04-11T21:18:07-05:00</sent>
        <status>Actual</status>
        <msgType>Alert</msgType>
        <scope>Public</scope>
        <info>
            <language>en-US</language>
            <category>Met</category>
            <event>Tornado Warning</event>
            <urgency>Immediate</urgency>
            <severity>Extreme</severity>
            <certainty>Observed</certainty>
            <effective>2011-04-11T21:09:00-05:00</effective>
            <expires>2011-04-11T21:30:00-05:00</expires>
            <headline>Tornado Warning issued April 11 at
            9:30PM CDT by NWS Birmingham</headline>
            <instruction>
                Do not wait to see or hear the tornado.
            For your protection, move to an interior room on the 
            lowest floor of your home or business.</instruction> 
            <area>
                <areaDesc>Cleburne</areaDesc>
                <polygon>33.61,-85.58 33.65,-85.58 33.72,-85.58 
                33.81,-85.36 33.7,-85.34 33.7,-85.33 33.68,-85.33
                33.61,-85.58</polygon> 
            </area>
        </info>
    </alert>

Please be sure to check out our Sample CAP Alerts for richer examples of working alerts that may be similar to yours.

event

The CAP <event> string (or sometimes the <headline>) appears in the title of our alerts. These should be short (less than 35 characters) and descriptive enough for the public to understand. For more detailed requirements, please see <info> elements and sub-elements in the reference guide.

dates

Time zone fields must be included in all date/time values (such as <effective>, <expires>, and <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.

instructions

The CAP alert's <instruction> field appears in alert details pages as the "recommended action". Note that the content of this element should not be the same as the <description>, which is more suitable for summarizing the nature and intensity of the alert, and the impacted area.

notification area

The CAP alert's <area> element should describe the geographic area to be notified, which may include locations outside the incident area. For example, consider a wildfire alert: Because wildfires can spread quickly to areas that aren't currently burned, the <area> should cover the entire potential danger zone, not simply the fire's origin point or current burn area.

Specifying areas as polygons

Alerting areas are best given as polygons because they tend to be more precise. Ideally, the value of the <area> element is defined as the specific geographic area that's impacted by current or forecasted conditions, rather than predetermined geopolitical areas such as districts or provinces. This helps ensure that users who see the alert find it relevant for their location. For example, thunderstorm or flood warnings may only affect a small portion of a political jurisdiction, and snowfall warnings likely only affect users who are located above a certain altitude. In cases like this, specifying an entire district or province as the <area> of the CAP alert overestimates the affected area and makes the alert less useful.

In our experience, alerting software or tools that allow forecasters to draw a custom polygon over the area that they want to warn are ideal.

If you're using polygons, we recommend including no more than 5-6 decimal points of precision in the lat/long coordinates. (This produces higher resolution than most alerting systems should be able to target.) Also, please be sure that the polygons are valid; for example, they shouldn't have intersecting edges.

Specifying areas as geocodes

If you must specify the <area> as a geocode or set of multiple geocodes instead, please use geocodes at the most granular level possible and include the names of the specific towns, cities, etc that are likely to be impacted in the <description> element. You'll need to share the underlying shapefiles in the format of a shapefile.

Supporting multiple languages

Please create one <alert> containing multiple <info> blocks (one <info> block per language).

For more details and a sample multi-lingual alert, see the Multiple Languages sample.

Validate CAP alerts

We recommend that you use Google's open source CAP Validator tool to validate your CAP alerts. You can also subscribe to error notification emails via this tool. The validator offers several CAP validation options and examples:

validator screenshot

Select Google Public Alerts CAP v1.0 to validate against Google-specific requirements for CAP feeds.

To subscribe to error notification emails, click Subscribe to feed validation results, or go to http://cap-validator.appspot.com/subscribe. You need to provide your feed URL and email address, select Google Public Alerts CAP v1.0, and click Subscribe. You will receive a notification when issues are found in your CAP feed.

Alert publishers can also download the latest version of the Google CAP schema from the CAP library and validate offline.

Next step: Send Google your Alerts feed