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

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.

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

Locations

DISCRETE

The DISCRETE XML file can be located at the URL

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

CONSOLIDATED

The CONSOLIDATED XML file can be located at the URL

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

Alerts (DISCRETE) DTD

<!ELEMENT alert (summary, details, locations, sectors, duration, detail_sections)>
<!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 locations (location*)>
<!ELEMENT location (#PCDATA)>
<!ELEMENT sectors (sector*)>
<!ELEMENT sector (#PCDATA)>
<!ELEMENT detail_sections (detail_section*)>
<!ELEMENT detail_section (detail_title,detail)>
<!ELEMENT detail_title (#PCDATA)>
<!ELEMENT detail (#PCDATA)>
 

Sample Alerts (alerts) file

<?xml version="1.0" encoding="UTF-8"?>
<alerts>
	<alert start='2013/04/14 14:39' end='2014/04/14 14:38' href='/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
  • detail_sections
    A list of information specific to the threat detailed by the alert
  • detail section
    An individual detail section containing a specific piece of information for the alert.
  • detail_title
    An individual detail section title. May contain HTML
  • detail
    An individual piece of detail related to the threat. 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:38" 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 description of the duration of the alert]]></duration>
    <detail_sections>
          <detail_section>
              <detail_title><![CDATA[Freeform detail title]]></detail_title>
              <detail><![CDATA[<p>Freeform text description of threat details</p>]]></detail>
        </detail_section>
          <detail_section>
              <detail_title><![CDATA[Freeform detail title]]></detail_title>
              <detail><![CDATA[<p>Freeform text description of threat details</p>]]></detail>
        </detail_section>
          <detail_section>
              <detail_title><![CDATA[Freeform detail title]]></detail_title>
              <detail><![CDATA[<p>Freeform text description of threat details</p>]]></detail>
        </detail_section>
          <detail_section>
              <detail_title><![CDATA[Freeform detail title]]></detail_title>
              <detail><![CDATA[<p>Freeform text description of threat details</p>]]></detail>
        </detail_section>
    </detail_sections>
  </alert>

Feed (CONSOLIDATED) DTD

<!ELEMENT alerts (alert*)>

<!ELEMENT alert (summary, details, locations, sectors, duration, detail_sections)>
<!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 locations (location*)>
<!ELEMENT location (#PCDATA)>
<!ELEMENT sectors (sector*)>
<!ELEMENT sector (#PCDATA)>
<!ELEMENT detail_sections (detail_section*)>
<!ELEMENT detail_section (detail_title,detail)>
<!ELEMENT detail_title (#PCDATA)>
<!ELEMENT detail (#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
  • detail_sections
    A list of information specific to the threat detailed by the alert
  • detail section
    An individual detail section containing a specific piece of information for the alert.
  • detail_title
    An individual detail section title. May contain HTML
  • detail
    An individual piece of detail related to the threat. 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:38" 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 description of the duration of the alert]]></duration>
    <detail_sections>
          <detail_section>
              <detail_title><![CDATA[Freeform detail title]]></detail_title>
              <detail><![CDATA[<p>Freeform text description of threat details</p>]]></detail>
        </detail_section>
          <detail_section>
              <detail_title><![CDATA[Freeform detail title]]></detail_title>
              <detail><![CDATA[<p>Freeform text description of threat details</p>]]></detail>
        </detail_section>
          <detail_section>
              <detail_title><![CDATA[Freeform detail title]]></detail_title>
              <detail><![CDATA[<p>Freeform text description of threat details</p>]]></detail>
        </detail_section>
          <detail_section>
              <detail_title><![CDATA[Freeform detail title]]></detail_title>
              <detail><![CDATA[<p>Freeform text description of threat details</p>]]></detail>
        </detail_section>
    </detail_sections>
  </alert>
</alerts>

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
> 

Last Published Date: July 16, 2015

Was this page helpful?

Back to Top