US flag signifying that this is a United States Federal Government website   Official website of the Department of Homeland Security

Homeland Security

NTAS API Documentation


Overview

The Department of Homeland Security provides a feed of National Terrorism Advisory System current alerts in the form of XML files. Developers can use these XML files to place information in their own applications or web pages regarding current alerts.

Back To Top


Data Types

There are two separate sources for information on NTAS Alerts. All information is available from both sources. Which source to use is purely a matter of developer choice.

The two sources are referred to as DISCRETE and CONSOLIDATED. The difference between the two is that the DISCRETE data source gives alert start and end times, and a reference to a separate XML file which contains the rest of the data for that alert. By contrast, the CONSOLIDATED data source embeds all alert data for all active alerts within a single data source

Back To Top


Locations

DISCRETE

The DISCRETE XML file can be located at the URL

http://www.dhs.gov/ntas/1.0/alerts.xml

CONSOLIDATED

The CONSOLIDATED XML file can be located at the URL

http://www.dhs.gov/ntas/1.0/feed.xml

Back To Top


Alerts (DISCRETE) DTD

<!ELEMENT alert (summary, details, locations, sectors, duration, affected_areas, how_to_help, stay_prepared, stay_informed)>
<!ATTLIST alert
  start CDATA #REQUIRED
  end CDATA #IMPLIED
  type (Elevated Threat | Imminent Threat)
  link CDATA #REQUIRED

<!ELEMENT summary (#PCDATA)>
<!ELEMENT details ANY>
<!ELEMENT duration (#PCDATA)>
<!ELEMENT affected_areas ANY>
<!ELEMENT how_to_help ANY>
<!ELEMENT stay_prepared ANY>
<!ELEMENT stay_informed ANY>
<!ELEMENT locations (location*)>
<!ELEMENT location (#PCDATA)>
<!ELEMENT sectors (sector*)>
<!ELEMENT sector (#PCDATA)>

Sample Alerts (alerts) file

<?xml version="1.0" encoding="UTF-8"?>
<alerts>
  <alert start=”2011/04/14 14:39” end=”2012/04/14 14:39” type=”Elevated Threat” details=http://www.dhs.gov/ntas/samplealert.xml />
</alerts>

Description of elements

  • alert
    A single active alert. Contains the following attributes
    • start
      The effective start date/time of the alert, in the form YYYY/MM/DD HH:MM, expressed in GMT
    • end
      The effective end date/time of the alert, in the form YYYY/MM/DD HH:MM, expressed in GMT
    • type
      The type of the alert. Possible choices are
      • Imminent Threat
      • Elevated Threat
    • link
      a URL to a PDF document which provides further details about the alert
  • summary
    A short plain text summary of the alert.
  • details
    A longer explanation of the alert. May contain HTML
  • sectors
    A possibly empty list of sectors which are impacted by this alert
  • sector
    An individual sector impacted by an alert. Represented as plain text
  • locations
    A possibly empty list of locations which are impacted by this alert
  • location
    An individual location impacted by an alert. Represented as plain text
  • duration
    A plain text description of the expected duration of this alert May be blank
  • affected_areas
    A description of the affected areas for this alert. May contain HTML
  • how_to_help
    A description of how citizens can assist. May contain HTML
  • stay_prepared
    A description of how citizens can be prepared. May contain HTML
  • stay_infomed
    A description of how citizens can keep up to date on this alert. May contain HTML

Sample individual alert

<?xml version="1.0" encoding="UTF-8"?>
<alert start="2011/04/14 14:39'" end="2012/04/14 14:39" type="Elevated Threat" link="http://www.dhs.gov/xlibrary/assets/ntas/ntas-sample-alert.pdf">
    <summary><![CDATA[This is a summary of the alert]]></summary>
    <details><![CDATA[<p>This is a more detailed description of the alert</p>]]></details>
    <locations>
      <location><![CDATA[A location or region]]></location>
      <location><![CDATA[Another location or region]]></location>
</locations>
    <sectors>
      <sector><![CDATA[An impacted sector]]></sector>
      <sector><![CDATA[Another impacted sector]]></sector>
    </sectors>
    <duration><![CDATA[freeform text duration of the alert]]></duration>
    <affected_areas><![CDATA[Freeform text description of affected areas]]></affected_areas>
    <how_to_help><![CDATA[Freeform text description of ways citizens can help
]]></how_to_help>
    <stay_prepared><![CDATA[Freeform text description of how citizens can be prepared]]></stay_prepared>
    <stay_informed><![CDATA[Freeform text description of how citizens can stay informed of updates]]></stay_informed>
</alert>

Back To Top


Feed (CONSOLIDATED) DTD

<!ELEMENT alerts (alert*)>

<!ELEMENT alert (summary, details, locations, sectors, duration, affected_areas, how_to_help, stay_prepared, stay_informed)>
<!ATTLIST alert
  start CDATA #REQUIRED
  end CDATA #IMPLIED
  type (Elevated Threat | Imminent Threat)
  link CDATA #REQUIRED

<!ELEMENT summary (#PCDATA)>
<!ELEMENT details ANY
<!ELEMENT duration (#PCDATA)>
<!ELEMENT affected_areas ANY>
<!ELEMENT how_to_help ANY>
<!ELEMENT stay_prepared ANY>
<!ELEMENT stay_informed ANY>
<!ELEMENT locations (location*)>
<!ELEMENT location (#PCDATA)>
<!ELEMENT sectors (sector*)>
<!ELEMENT sector (#PCDATA)>

Description of elements

  • alerts
    Root container of all other elements
  • alert
    A single active alert. Contains the following attributes
    • start
      The effective start date/time of the alert, in the form YYYY/MM/DD HH:MM, expressed in GMT
    • end
      The effective end date/time of the alert, in the form YYYY/MM/DD HH:MM, expressed in GMT
    • type
      The type of the alert. Possible choices are
      • Imminent Threat
      • Elevated Threat
    • link
      a URL to a PDF document which provides further details about the alert
  • summary
    A short plain text summary of the alert.
  • details
    A longer explanation of the alert. May contain HTML
  • sectors
    A possibly empty list of sectors which are impacted by this alert.
  • sector
    An individual sector impacted by an alert. Represented as plain text
  • locations
    A possibly empty list of locations which are impacted by this alert
  • location
    An individual location impacted by an alert. Represented as plain text
  • duration
    A description of the expected duration of this alert May contain HTML
  • affected_areas
    A description of the affected areas for this alert. May contain HTML
  • how_to_help
    A description of how citizens can assist. May contain HTML
  • stay_prepared
    A description of how citizens can be prepared. May contain HTML
  • stay_infomed
    A description of how citizens can keep up to date on this alert. May contain HTML

Sample CONSOLIDATED feed

<?xml version="1.0" encoding="UTF-8"?>
<alerts>
  <alert start="2011/04/14 14:39'" end="2012/04/14 14:39" type="Elevated Threat" link="http://www..dhs.gov/xlibrary/assets/ntas/ntas-sample-alert.pdf">
    <summary><![CDATA[This is a summary of the alert]]></summary>
    <details><![CDATA[<p>This is a more detailed description of the alert</p>]]></details>
    <locations>
      <location><![CDATA[A location or region]]></location>
      <location><![CDATA[Another location or region]]></location>
</locations>
    <sectors>
      <sector><![CDATA[An impacted sector]]></sector>
      <sector><![CDATA[Another impacted sector]]></sector>
    </sectors>
    <duration><![CDATA[freeform text duration of the alert]]></duration>
    <affected_areas><![CDATA[Freeform text description of affected areas]]></affected_areas>
    <how_to_help><![CDATA[Freeform text description of ways citizens can help
]]></how_to_help>
    <stay_prepared><![CDATA[Freeform text description of how citizens can be prepared]]></stay_prepared>
    <stay_informed><![CDATA[Freeform text description of how citizens can stay informed of updates]]></stay_informed>
  </alert>
</alerts>

Back To Top


HSAS (legacy) Backward Compatibility

The NTAS alert system is replacing the existing HSAS alert system. During this transition period, the existing HSAS system will continue to be supported, with the following caveats

  • The DTD of the HSAS data source will remain unchanged
  • The data source will continue to be available at http://www.dhs.gov/threat_level/threatlevel.xml
  • Only two alert levels will be supported, rather than the five currently possible
  • The graphic indicating the current alert level will continue to be available at http://www.dhs.gov/threat_level/current.gif
  • The DETAILS attribute of the THREAT_ADVISORY element will always be empty, and thus not present

Supported Alert Levels

The existing HSAS system supports five alert levels

  • Low
  • Guarded
  • Elevated
  • High
  • Extreme

The new NTAS system supports only two states

  • No Active Alerts
  • One or more Active Alerts

For the purposes of this transition period, when NTAS is at the “No Active Alerts” stage, then HSAS will report the condition as “ELEVATED.” When NTAS is at the “One or More Active Alerts” state, then HSAS will report the condition as “HIGH.”

Note: This should not be regarded as an official policy position, or any statement of equivalency between these alert levels or systems. This is solely an implementation decision to support backward compatibility.

HSAS (legacy) DTD

This is provided for reference only. Developers should migrate to the NTAS data source as soon as practical.

<!ELEMENT THREAT_ADVISORY EMPTY>
<!ATTLIST THREAT_ADVISORY
  CONDITION (LOW | GUARDED | ELEVATED | HIGH | EXTREME)
  DETAILS CDATA #IMPLIED

Back To Top

Last Published Date: August 28, 2014
Back to Top