> For the complete documentation index, see [llms.txt](https://api-v2-docs.disasteraware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-v2-docs.disasteraware.com/hazards/hazard-samples/volcano-sample.md). # Volcano Sample This page provides a complete sample response for a volcanic hazard from the Active Hazards API endpoint. Volcanic hazards in the API are sourced from Volcanic Ash Advisory Centres (VAACs), which are responsible for monitoring and issuing advisories on volcanic ash clouds that may affect aviation and surrounding populations. Each volcano object within the response includes detailed advisory information from the reporting VAAC, including observed and forecast ash cloud geometries, eruption details, and summit elevation data. Advisories come from the nine VAACs — Anchorage, Buenos Aires, Darwin, London, Montreal, Tokyo, Toulouse, Washington and Wellington — each responsible for a region of the globe. Each volcano object is updated every time the reporting VAAC publishes a new advisory. The response captures both the current state of the eruption and projected ash cloud positions at 6-hour forecast intervals, enabling users to assess potential impacts on aviation corridors and nearby populations. ## Severity and the Risk Rating Index A volcano hazard's `severity` is not copied from the VAAC advisory. It is derived from four inputs, all of which are present on the record: | Input | Where it appears | Notes | | ----------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | **VAAC aviation colour code** | `incident.properties.sourceSeverity` | `RED`, `ORANGE`, `YELLOW` or `GREEN`. `null` when the reporting VAAC supplied no colour code, which is the common case. | | **Risk Rating Index** | `incident.properties.riskRating` | Integer `0`–`3`. Higher means more population exposed. | | **Observed ash cloud** | `incident.properties.observedAshCloudPresent` | Boolean. | | **Forecast ash cloud** | `incident.properties.forecastAshCloudPresent` | Boolean. | ### Aviation colour codes The colour code is the International Civil Aviation Organization scale, assigned by the reporting VAAC. | Colour code | Meaning | | ----------- | --------------------------------------------------------------------------------------------------------------- | | **RED** | Eruption underway or imminent, with significant ash emission. | | **ORANGE** | Eruption underway with no or minor ash emission, or heightened unrest with an increased likelihood of eruption. | | **YELLOW** | Signs of elevated unrest. | | **GREEN** | The volcano is in, or has returned to, a normal non-eruptive state. | | **`null`** | No colour code was supplied. Severity then rests on ash cloud presence and the Risk Rating Index. | ### Risk Rating Index The Risk Rating Index is a DisasterAWARE value, not a VAAC one. It expresses how much population sits near the volcano, on a four-point ordinal scale. | `riskRating` | Meaning | | ------------ | ---------------------------------------------------------------------------------------- | | **3** | Highest. Raises the hazard to WARNING on its own, even when no colour code was supplied. | | **2** | Risk to nearby population is high. | | **1** | Risk to nearby population is moderate. | | **0** | Risk to nearby population is very low. | {% hint style="info" %} The population thresholds that divide one rating from the next are derived internally and are not published. Treat `riskRating` as an ordinal scale — 3 is more exposed than 2 — rather than as a value you can recompute from a population figure. {% endhint %} ### Severity matrix Read the row for the record's colour code, then the column that matches its Risk Rating Index and ash cloud flags. | Colour code | WARNING when | WATCH when | ADVISORY when | | ----------- | ---------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------- | | **RED** | Always | — | — | | **ORANGE** | `riskRating` 2 or 3 | `riskRating` 0 or 1 | — | | **YELLOW** | `riskRating` 2 or 3 | `riskRating` 1 | `riskRating` 0 | | **GREEN** | — | — | Always | | **`null`** | An ash cloud is both observed and forecast, or `riskRating` is 3 | An ash cloud is observed but none is forecast | No ash cloud is observed or forecast, and `riskRating` is below 3 | All fourteen volcano hazards active on 2026-09-22 agreed with this table. The common shapes were an erupting volcano with no colour code and both ash cloud flags set, which is a WARNING regardless of its Risk Rating Index, and a quiet volcano with no colour code and no ash cloud, which is a WARNING at `riskRating` 3 and an ADVISORY below that. ### Effect on geometry A volcano with no observed or forecast ash cloud carries no `SMART_ALERT` feature and no `ASH_CLOUD` features, so its `features` collection holds only the `INCIDENT` point at the summit. Its `alertGeometry` is still populated: a circular alert area of roughly 100 km radius around the summit, or the volcano's own exposure zone where PDC maintains one, which is usually smaller. When an ash cloud is observed or forecast, `alertGeometry` instead follows the ash cloud and matches the `SMART_ALERT` polygon. Those areas are larger and are not circular — they extend along the plume. `exposureAreas` is unaffected by severity: it is always the single level-0 zone described under [Exposure Areas](#exposure-areas). ## Volcano-Specific Properties ### Incident Data The `incident.properties` object of the volcano provides a detailed summary of the current volcanic activity status and advisory information. This includes data sourced directly from the VAAC advisory message, covering eruption characteristics, ash cloud observations, and forecast information. Key attributes describe the volcano's physical properties, the current state of the eruption, and the reporting agency's assessment. **Key incident properties for volcanoes include:** * `advisoryNumber` - Advisory number from the reporting VAAC (e.g., "2026/306") * `forecastAshCloudPresent` - Boolean indicating whether ash clouds are forecast in future time steps * `observedAshCloudPresent` - Boolean indicating whether ash clouds have been observed * `summitElevation` - Elevation of the volcano summit in meters (e.g., 3763) * `eruptionDetails` - Brief description of the eruption activity (e.g., "ONGOING VA EMS") * `infoSource` - Data sources used for the advisory (e.g., "GOES-19. WEBCAM. NWP MODELS") * `riskRating` - Risk Rating Index, an integer 0-3 reflecting the population near the volcano. See [Severity and the Risk Rating Index](#severity-and-the-risk-rating-index) * `sourceSeverity` - VAAC aviation colour code (`RED`, `ORANGE`, `YELLOW`, `GREEN`), or `null` when the reporting VAAC supplied none * `locationDescription` - Geographic region of the volcano (e.g., "Guatemala") * `nextAdvisory` - Expected time of the next advisory issuance * `forecastValidTime` - Valid time for the current forecast observation * `name` - Common name of the volcano (e.g., "Fuego") The hazard name follows the pattern `Volcano - [volcano name], [area name]`, where the area is the country, or the Smithsonian region for undersea volcanoes. `incident.sourceRecordId` carries the volcano's Smithsonian Global Volcanism Program number — `342090` for Fuego, `211060` for Etna — which is stable across advisories and is the key to use when joining DisasterAWARE volcano hazards to an external volcano catalogue. ### Features The `features` property of the volcano object is a GeoJSON feature collection providing a geospatial representation of the volcanic event. Each feature within this collection includes a `featureType` property that indicates its role. The primary types of features are: * **ASH\_CLOUD features** - Polygon geometries showing observed and forecast ash cloud extents at different time steps (0hr, 6hr, 12hr, 18hr). Each ASH\_CLOUD feature includes a `forecastHr` property indicating the forecast hour offset and a `forecastValidTime` indicating the valid time for that forecast step. The 0hr feature represents the currently observed ash cloud, while subsequent features represent projected positions. * **SMART\_ALERT features** - A polygon representing the alert boundary area for the volcanic event. This geometry defines the broader region under advisory and is also reflected in the top-level `alertGeometry` property. * **INCIDENT features** - A point geometry located at the volcano's summit, containing the full set of advisory details (eruption information, risk rating, source details, and all properties from the incident data). This serves as the geographic anchor for the volcanic event. ### Exposure Areas The `exposureAreas` property for volcanoes uses a single exposure level, reflecting the PDC Volcano Hazard Zone around the summit. * **Level 0** - PDC Volcano Hazard Zone. This is typically a buffer area around the volcano summit that follows known hazard zones, generally extending approximately 10km from the summit. The geometry may include multiple rings to account for terrain and historical hazard patterns. ## Sample Response ```json { "name": [ { "locale": "en", "value": "Volcano - Fuego, Guatemala" } ], "description": [ { "locale": "en", "value": "Volcanic activity has been reported for Fuego in Guatemala, by the Washington Volcanic Ash Advisory Centre (VAAC) on March 13, 2026, 19:44:00 UTC.\n\nThis volcanic activity is reported based on aerial, satellite and/or ground observations.\n\nIt is estimated that 79,300 people, 17,600 households, and $618 Million (USD) of infrastructure* are within the affected area(s). Exposure estimates will be refined as additional data from official sources becomes available.\n\nVolcano information sources for this report include: GOES-19. WEBCAM. NWP MODELS.\n\nAdditional information will be provided as it becomes available by official sources.\n\n*The cost represents the total replacement value of the infrastructure.\n\n" } ], "severity": "WARNING", "category": "EVENT", "incident": { "uuid": "37ea49e4-6a86-4aa5-a7e6-c19f4b1081ad", "type": "VOLCANO", "sourceId": 133, "sourceRecordId": "342090", "properties": { "hazardName": "Volcano - Fuego, Guatemala", "advisoryNumber": "2026/306", "locationDescription": "Guatemala", "reportDate": "2026-03-13T19:44:00+00:00", "featureType": "INCIDENT", "summitElevation": 3763, "eventDate": "2025-03-01T12:30:00+00:00", "...": "" } }, "uuid": "d47c3a21-14a7-47aa-aea7-02c62ca2f758", "comment": null, "createdAt": 1773431269, "relatedHazards": [], "longitude": -90.88, "latitude": 14.473, "version": 375, "alertGeometry": { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "Polygon", "coordinates": [...] }, "properties": null } ] }, "features": { "features": [ { "id": null, "type": "Feature", "properties": { "forecastHr": 0, "forecastValidTime": "2026-03-13T19:10:00+00:00", "featureType": "ASH_CLOUD", "type": "FORECAST" }, "geometry": { "coordinates": [...], "type": "Polygon", "properties": { "type": "FORECAST", "forecastHr": 0, "forecastValidTime": "2026-03-13T19:10:00+00:00", "featureType": "ASH_CLOUD" } }, "incidentType": null, "sourceId": null }, { "id": null, "type": "Feature", "properties": { "featureType": "SMART_ALERT", "type": "SMART_ALERT" }, "geometry": { "coordinates": [...], "type": "Polygon", "properties": { "type": "SMART_ALERT", "featureType": "SMART_ALERT" } }, "incidentType": null, "sourceId": null }, { "id": null, "type": "Feature", "properties": { "featureType": "INCIDENT", "type": "INCIDENT", "...": "" }, "geometry": { "coordinates": [ -90.88, 14.473 ], "type": "Point", "properties": { "featureType": "INCIDENT", "type": "INCIDENT", "...": "" } }, "incidentType": null, "sourceId": null } ], "incidentType": null, "metadata": null, "type": "FeatureCollection", "sourceId": null }, "exposureAreas": { "features": [ { "id": "0", "type": "Feature", "properties": { "exposureLevel": 0 }, "geometry": { "coordinates": [...], "type": "Polygon", "properties": { "intensity": "UNCATEGORIZED", "exposureDescription": "PDC Volcano Hazard Zone", "featureType": "EXPOSURE_AREA", "exposureLevel": "1" } }, "sourceId": null } ], "type": "FeatureCollection" }, "exposureAssessment": { "population": { "total": 79300, "total0_14": 25487, "total15_64": 50070, "total65_Plus": 3759, "households": 17622, "vulnerable": 47000 }, "capital": { "total": 618708300, "school": 24, "hospital": 0 }, "totalByCountry": [ { "population": { "total": 79300, "total0_14": 25487, "total15_64": 50070, "total65_Plus": 3759, "households": 17622, "vulnerable": 47000 }, "country": "GTM", "capital": { "total": 618708300, "school": 24, "hospital": 0 }, "admin0": "Guatemala", "admin1": null, "admin2": null, "foodNeedsUnit": "CAL", "foodNeeds": 98700000.0, "waterNeedsUnit": "liter", "waterNeeds": 141000.0, "wasteNeedsUnit": "100 liter", "wasteNeeds": 4700.0, "shelterNeedsUnit": "sq meters", "shelterNeeds": 162150.0 } ], "totalByAdmin": [ { "population": { "total": 79300, "total0_14": 25487, "total15_64": 50070, "total65_Plus": 3759, "households": 17622, "vulnerable": 47000 }, "country": "GTM", "capital": { "total": 618708300, "school": 24, "hospital": 0 }, "admin0": "Guatemala", "admin1": null, "admin2": null, "foodNeedsUnit": "CAL", "foodNeeds": 98700000.0, "waterNeedsUnit": "liter", "waterNeeds": 141000.0, "wasteNeedsUnit": "100 liter", "wasteNeeds": 4700.0, "shelterNeedsUnit": "sq meters", "shelterNeeds": 162150.0 } ], "exposureLevels": [ { "level": "0", "data": { "population": { "total": 79300, "total0_14": 25487, "total15_64": 50070, "total65_Plus": 3759, "households": 17622, "vulnerable": 47000 }, "capital": { "total": 618708300, "school": 24, "hospital": 0 }, "totalByCountry": [ { "population": { "total": 79300, "total0_14": 25487, "total15_64": 50070, "total65_Plus": 3759, "households": 17622, "vulnerable": 47000 }, "country": "GTM", "capital": { "total": 618708300, "school": 24, "hospital": 0 }, "admin0": "Guatemala", "admin1": null, "admin2": null, "foodNeedsUnit": "CAL", "foodNeeds": 98700000.0, "waterNeedsUnit": "liter", "waterNeeds": 141000.0, "wasteNeedsUnit": "100 liter", "wasteNeeds": 4700.0, "shelterNeedsUnit": "sq meters", "shelterNeeds": 162150.0 } ], "totalByAdmin": [ { "population": { "total": 79300, "total0_14": 25487, "total15_64": 50070, "total65_Plus": 3759, "households": 17622, "vulnerable": 47000 }, "country": "GTM", "capital": { "total": 618708300, "school": 24, "hospital": 0 }, "admin0": "Guatemala", "admin1": null, "admin2": null, "foodNeedsUnit": "CAL", "foodNeeds": 98700000.0, "waterNeedsUnit": "liter", "waterNeeds": 141000.0, "wasteNeedsUnit": "100 liter", "wasteNeeds": 4700.0, "shelterNeedsUnit": "sq meters", "shelterNeeds": 162150.0 } ], "foodNeedsUnit": "CAL", "foodNeeds": 98700000.0, "waterNeedsUnit": "liter", "waterNeeds": 141000.0, "wasteNeedsUnit": "100 liter", "wasteNeeds": 4700.0, "shelterNeedsUnit": "sq meters", "shelterNeeds": 162150.0 }, "exposureDescription": "PDC Volcano Hazard Zone" } ], "hazardUuid": "", "hazardType": "", "version": "", "timestamp": "1773431256288", "exposureDescription": "", "foodNeedsUnit": "CAL", "foodNeeds": 98700000.0, "waterNeedsUnit": "liter", "waterNeeds": 141000.0, "wasteNeedsUnit": "100 liter", "wasteNeeds": 4700.0, "shelterNeedsUnit": "sq meters", "shelterNeeds": 162150.0 }, "type": "VOLCANO", "creator": "RICHTER", "source": { "id": 133, "name": "Washington VAAC", "longName": "Washington Volcanic Ash Advisory Centre (VAAC)", "..." }, "startedAt": 1765936800, "updatedAt": 1773431256, "endedAt": 1773863253 } ``` {% hint style="info" %} Note: In this sample, coordinate arrays in `alertGeometry`, `features` geometries, and `exposureAreas` have been replaced with `[...]` for brevity. In actual API responses, these properties contain complete GeoJSON coordinate arrays. Additionally, the `features` array has been truncated to show only representative examples of the ASH\_CLOUD (0hr forecast), SMART\_ALERT, and INCIDENT feature types. The full response includes four ASH\_CLOUD features at 0hr, 6hr, 12hr, and 18hr forecast intervals. The INCIDENT feature properties have been truncated. For hazards with multiple affected countries or admin regions, the `totalByCountry` and `totalByAdmin` arrays will contain additional entries. {% endhint %}