# Requesting Active Hazards To request the list of current active hazards please use the route defined here: {% openapi src="/files/wYQaKpPZEdPb68ZWOF6w" path="/active-hazards-query" method="get" %} [openapi.yaml](https://3664004773-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbwQ2AvqpbIy1hD3QFTQG%2Fuploads%2Fgit-blob-9d646f1681dee35f7dc1c0638c3b2af1bcd498f5%2Fopenapi.yaml?alt=media) {% endopenapi %} {% hint style="info" %} See [Authorizing Requests](/authentication/authorizing-requests.md#get-accesstoken-and-refreshtoken) page to get your accessToken. {% endhint %} ## Response Format The API returns data as **gzipped NDJSON** (newline-delimited JSON) for optimal performance. When decompressed, each line contains a complete hazard object in JSON format. Each hazard object includes enriched data with detailed incident information, geographic features, exposure assessments, and related metadata. ## Response Fields | Field | Type | Description | | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **uuid** | String | A unique universal identifier for the hazard across all DisasterAWARE systems. | | **name** | Array | An array of objects, each defining the hazard name in a specific locale formatted according to RFC 5646 (e.g., "en" for US English). Each object contains `locale` and `value` keys. Currently, names are provided only in US English. | | **description** | Array | An array of objects providing localized descriptions of the hazard. These descriptions detail the areas affected by the hazard, as well as an assessment of the populations and infrastructure at risk. Each object contains `locale` (RFC 5646 format) and `value` keys. | | **severity** | String | Indicates the likelihood of the hazard impacting populated areas. This property helps assess the potential risk to human settlements, aiding in preparation and response efforts. Values include TERMINATION, INFORMATION, ADVISORY, WATCH, and WARNING. See [Requesting Hazard Severities](/hazards/requesting-active-hazards/requesting-hazard-severities.md) for complete reference. | | **category** | String | The category classification of the hazard (e.g., EVENT, RESPONSE, EXERCISE, OTHER). See [Requesting Hazard Categories](/hazards/requesting-active-hazards/requesting-hazard-categories.md) for complete reference. | | **type** | String | Specifies the phenomenon that caused the hazard, such as EARTHQUAKE, CYCLONE, VOLCANO, FLOOD, WILDFIRE, TSUNAMI, or TORNADO. This property is essential for understanding the hazard's nature and planning appropriate response strategies. See [Requesting Hazard Types](/hazards/requesting-active-hazards/requesting-hazard-types.md) for complete reference. | | **comment** | String/Null | Optional comment or additional information about the hazard. Currently not populated; reserved for future use. | | **createdAt** | Integer | Unix timestamp (seconds since epoch) indicating when the hazard object was initialized and first logged in the system. Provides a reference point for tracking the timeline of the hazard's identification. | | **startedAt** | Integer | Unix timestamp recording when the event underlying the hazard began. This can include future dates for forecasted hazards (e.g., an anticipated flood), valuable for preparedness and preemptive measures. | | **updatedAt** | Integer | Unix timestamp capturing the last time information within the hazard object was updated. Essential for tracking changes as the hazard may increase/decrease in intensity or move locations. Regular updates ensure current and reliable data. | | **endedAt** | Integer | Unix timestamp specifying when the event ceased to be hazardous. Can be a future date based on forecasts/predictions. The value may change as new information becomes available, providing updated insights into the hazard's duration. | | **latitude** | Float | Geographic latitude coordinate (WGS84 projection). The significance varies by hazard type: may represent an earthquake epicenter, the last observed location of a cyclone, or the weighted center of wildfire perimeters. | | **longitude** | Float | Geographic longitude coordinate (WGS84 projection). The significance varies by hazard type: may represent an earthquake epicenter, the last observed location of a cyclone, or the weighted center of wildfire perimeters. | | **version** | Integer | Tracks the number of updates made to the hazard object, serving as a version counter that increments with each modification (intensity changes, movement, or other attribute updates). Maintains a clear record of how the hazard has evolved. | | **creator** | String | Identifies the system or person responsible for reporting the hazard. "RICHTER" indicates the new hazard identification system, "D2P2" indicates the legacy system, or a username for manually created hazards by the monitoring team. Crucial for tracking the source and ensuring accountability. | | **relatedHazards** | Array | A placeholder for future use. Currently returns an empty array. Once implemented, will contain UUIDs of related hazards (e.g., earthquake that triggered a tsunami, tornadoes associated with a cyclone). Will enhance comprehensiveness by illustrating connections between events for holistic risk assessments. | | **incident** | Object | Details the event classified as hazardous. Contains: **uuid** (unique identifier), **sourceRecordId** (identifier from reporting agency like USGS or NHC), **type** (phenomenon type), and **properties** (dictionary of key/value pairs describing specific attributes that vary by phenomenon, such as epicenter location and magnitude for earthquakes). | | **source** | Object/Null | Identifies the authoritative agency responsible for reporting the hazard. Includes: **id** (source ID in the system), **name** (agency name), **longName** (full agency name), and **description** (agency scope and expertise). Not all hazards have a source populated. When absent, this field is null. Source is fully populated for hazards from known agencies (e.g., USGS for earthquakes, VAAC for volcanoes, AI for Humanity for geopolitical events). Source population is being expanded to cover all hazard types. | | **alertGeometry** | Object | A GeoJSON FeatureCollection delineating an area for notification purposes. Designed to intersect with user areas of interest for early-warning notifications (subject to user filtering settings). Intentionally larger than the actual impact area to inform nearby assets and individuals, allowing proactive decisions like altering travel plans. | | **features** | Object | A GeoJSON FeatureCollection representing geographic features associated with the hazard (not included for all hazard types). When present, provides detailed geographical information specific to the hazard, such as the track of a tropical cyclone. Crucial for visualizing movement or extent over time. | | **exposureAreas** | Object | A GeoJSON FeatureCollection with polygons defining areas exposed to the hazard, categorized by severity level: **1** = moderate severity, **2** = strong severity, **3** = severe. Allows for nuanced understanding of potential effects across different regions, helping authorities and residents prepare based on graded risk levels. Note: These severity levels differ from the hazard's overall `severity` property. | | **exposureAssessment** | Object | A comprehensive report utilizing exposureAreas geometry to estimate affected populations. Provides detailed breakdown by region and exposure severity, including population estimates segmented by age group and vulnerability status. Details critical infrastructure (hospitals, airports, etc.), highlighting potential impact on essential services. Includes humanitarian needs estimates with specific units (CAL for food, liters for water, 100-liter units for waste, square meters for shelter). | ## Field Details ### Timestamps All timestamp fields (`createdAt`, `updatedAt`, `startedAt`, `endedAt`) are Unix timestamps representing seconds since January 1, 1970 UTC. **Important Notes:** * `startedAt` and `endedAt` can include future dates for forecasted hazards * `updatedAt` changes as hazards evolve (intensity, movement, etc.) * Future date values may change as new forecasts become available ### Geographic Data * `latitude` and `longitude` use the WGS84 coordinate system (EPSG:4326) * The meaning of coordinates varies by hazard type: * **Earthquakes**: Epicenter location * **Tropical Cyclones**: Last observed position * **Wildfires**: Weighted center of perimeter polygons * Geographic feature collections (`alertGeometry`, `features`, `exposureAreas`) follow the GeoJSON specification ### Incident Object The `incident` property contains event-specific details that vary by hazard type: * **uuid**: Unique identifier for the incident * **sourceRecordId**: ID from the reporting agency (e.g., USGS event ID, NHC advisory number) * **type**: The phenomenon type (matches the hazard's `type` field) * **sourceId**: Numeric identifier for the data source * **properties**: A dictionary of hazard-specific attributes (e.g., magnitude and depth for earthquakes, wind speed and pressure for cyclones) ### Source Object The `source` property identifies the authoritative reporting agency: * **id**: Numeric identifier in the DisasterAWARE system * **name**: Short agency name (e.g., "USGS", "NHC") * **longName**: Full official agency name * **description**: Details about the agency's scope, expertise, and geographic coverage This is particularly relevant when multiple agencies report on the same hazard type (e.g., different cyclone warning centers covering specific ocean basins). ### Alert Geometry The `alertGeometry` GeoJSON defines the notification boundary: * Intentionally larger than the actual impact area * Used to trigger alerts for users with intersecting areas of interest * Allows people near (but not directly in) the hazard zone to make proactive decisions * Subject to additional user-defined filtering preferences * Feature properties are currently empty (`{}` or `null`). The geometry alone defines the notification boundary. ### Features The `features` GeoJSON is not included for all hazard types. When present, it contains geographic features specific to the hazard's source data. The structure and properties vary by hazard type: * **Cyclones**: Storm track segments (observed and forecast paths), forecast cones (72hr/120hr), position points with detailed meteorological data, and wind radii polygons (34kt, 50kt, 64kt thresholds). See [Cyclone Sample](/hazards/hazard-samples/cyclone-sample.md). * **Floods**: Watershed severity points and flood incident area polygons from the NASA Global Flood Model. Properties include `featureType` ("INCIDENT" or "WATERSHED"), `pfafId` (Pfafstetter basin ID), risk scores (`rfrScore`, `cfrScore`), GloFAS return period flags, DFO/VIIRS satellite observation scores, and `exposureLevel`. * **Volcanoes**: Volcanic Ash Advisory polygons from VAAC sources with forecast time steps (0hr, 6hr, 12hr, 18hr). Properties include `featureType` ("ASH\_CLOUD", "SMART\_ALERT", or "INCIDENT"), advisory details, ash cloud observations, eruption information, and summit elevation. * **Landslides**: Landslide incident polygons. Properties include `featureType` ("INCIDENT"), `senderName`, risk scores, and exposure levels. * **Geopolitical (COMBAT, TERRORISM, ACCIDENT, CIVILUNREST)**: Smart Alert area and exposure area features. Properties include `featureType` ("SMART\_ALERT" or "EXPOSURE\_AREA"), casualty data, and incident details. * **Weather (WINTERSTORM, SEVEREWEATHER, HIGHWIND, HIGHSURF, TORNADO, STORM, EXTREMETEMPERATURE)**: CAP (Common Alerting Protocol) info features with source-provided alert polygons. Properties include `featureType` ("CAP\_INFO"), `senderName`, `headline`, `urgency`, `severity`, `certainty`, and alert timing fields. Note: The `features` property may be `null` or contain an empty features array for some hazard types (e.g., earthquakes prior to ShakeMap availability, wildfires). ### Exposure Areas The `exposureAreas` GeoJSON contains polygons categorized by severity level. The number of levels and their meaning vary by hazard type: **3-Level Exposure (levels 1, 2, 3):** | Type | Level 1 (Limited) | Level 2 (Moderate) | Level 3 (Severe) | | ----------------------------------------------------------- | ------------------------------ | ---------------------------- | --------------------------- | | **Earthquake** (before ShakeMap) | 30-100km buffer | 10-30km buffer | 0-10km buffer | | **Earthquake** (with ShakeMap) | Moderate-Strong shaking (V-VI) | Very Strong shaking (VII) | Severe shaking (VIII+) | | **Cyclone** | Minor damage / power out | Moderate damage (\~5% value) | Widespread damage and above | | **Wildfire** | Outer buffer zone | Moderate proximity zone | Active fire perimeter area | | **Geopolitical** (ACCIDENT, CIVILUNREST, COMBAT, TERRORISM) | 30-100km buffer | 10-30km buffer | 0-10km buffer | **Single-Level Exposure (level 1 only):** | Type | Exposure Area Description | | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | **Flood** | Combined water basins at Watch or Warning severity | | **Landslide** | Combined landslide polygons at Watch or Warning severity | | **Volcano** | PDC Volcano Hazard Zone (10km buffer fallback) | | **Avalanche** | 10km buffer around reported area | | **Weather types** (WINTERSTORM, TORNADO, SEVEREWEATHER, HIGHWIND, HIGHSURF, STORM, EXTREMETEMPERATURE) | Source-provided alert area (NWS, Environment Canada, BoM) or SmartAlert Area | **No Exposure:** CYBER, MANMADE types have no exposure areas. **Note:** These exposure severity levels are distinct from the hazard's overall `severity` property (which indicates likelihood of impact on populated areas). ### Exposure Assessment The `exposureAssessment` object provides critical humanitarian planning data with the following structure: **Population Breakdown (`population`):** The `population` field is an object containing demographic estimates for the affected area: * **total**: Total estimated population within all affected areas * **total0\_14**: Estimated population aged 0-14 * **total15\_64**: Estimated population aged 15-64 * **total65\_Plus**: Estimated population aged 65 and over * **households**: Estimated number of households * **vulnerable**: Estimated vulnerable population **Capital/Infrastructure Breakdown (`capital`):** The `capital` field is an object containing infrastructure exposure data: * **total**: Total estimated capital/infrastructure value at risk (USD) * **school**: Number of schools exposed (when non-zero) * **hospital**: Number of hospitals exposed (when non-zero) **Humanitarian Needs:** * **foodNeeds** / **foodNeedsUnit**: Food requirements (units: MRE - Meals Ready to Eat, or CAL - calories) * **waterNeeds** / **waterNeedsUnit**: Water requirements (units: gal - US gallons, or liter) * **wasteNeeds** / **wasteNeedsUnit**: Waste management needs (units: 25 gal - 25-gallon units, or 100 liter) * **shelterNeeds** / **shelterNeedsUnit**: Shelter space requirements (units: sq feet, or sq meters) **Note:** Units may vary by country within the same hazard. Check the `*Unit` fields for each entry rather than assuming a single unit system. **Geographic Breakdowns:** * **totalByCountry**: Array of objects providing exposure totals broken down by country. Each entry includes `population` (object), `capital` (object), humanitarian needs, `country` (ISO 3166-1 alpha-3 code), and `admin0` (country name). * **totalByAdmin**: Array of objects with the same structure as `totalByCountry`, broken down by administrative region. Includes `admin0` (country), `admin1` (province/state), and `admin2` (municipality/district) when available. **Exposure Levels Array (`exposureLevels`):** Breakdown by severity level. Each level contains the same `population`, `capital`, humanitarian needs, `totalByCountry`, and `totalByAdmin` structure as the top level: * **level**: "1" (moderate), "2" (strong), or "3" (severe) * **exposureDescription**: Human-readable description of the exposure zone (varies by hazard type) * **data**: Object containing all exposure metrics for that specific level **Note:** The `hazardUuid`, `hazardType`, `version`, and `exposureDescription` fields at the top level of `exposureAssessment` may be empty strings in the current implementation and are reserved for internal use. The `level` field within `exposureLevels` is returned as a String (e.g., `"1"`, `"2"`, `"3"`), not an Integer. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api-v2-docs.disasteraware.com/hazards/requesting-active-hazards.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.