Reference · built on requestCommons signalEarth, seismic & volcanic

USGS Volcano Hazards Program HANS API

US volcano alert levels, aviation color codes, activity notices, and VONAs in JSON from the USGS Volcano Hazards Program.

Request accessPricing ↗

About

The Hazard Notification System, HANS, is how the USGS Volcano Hazards Program and its observatories publish volcano status. Its public API at volcanoes.usgs.gov/hans-public/api returns JSON unless noted and is split into Volcano, Notice, Search, Map, Other, and Research groups. Volcano Alert Levels run NORMAL, ADVISORY, WATCH, WARNING; Aviation Color Codes run GREEN, YELLOW, ORANGE, RED. A Volcano Activity Notice is issued when the alert level changes and a Volcano Observatory Notice for Aviation when the color code changes.

Through Fibric, an operator polls getElevatedVolcanoes and the recent notices, matches volcanoes to your sites and lanes, and proposes a filter change, a routing hold, or a notice for your approval.

This is a reference listing. It documents what Fibric would read from USGS Volcano Hazards Program HANS API and what it could propose, based on the publisher's published interfaces. Fibric builds it under a managed deployment when you request it; selecting it here installs nothing.

Inputs

  • Volcanoes at YELLOW, ORANGE, or RED, or at ADVISORY, WATCH, or WARNING, through volcano/getElevatedVolcanoes
  • CAP records for volcanoes whose current or previous status is at least ORANGE / WATCH through volcano/getCapElevated
  • The monitored list and the full US list through volcano/getMonitoredVolcanoes and volcano/getUSVolcanoes
  • One volcano by Smithsonian volcano number or USGS volcano code through volcano/getVolcano and volcano/newestForVolcano
  • Recent notices through notice/getRecentNotices, notice/getNewestOrRecent, and notice/recent/{OBS}/{DAYS} with DAYS from 1 to 7
  • A notice as json, html, text, or sms through notice/getNoticeFormatted, and VONAs from the last year through notice/getVonasWithinLastYear
  • Observatories through other/getObservatories, and notice search by observatory, type, volcano, time range, and text through search/search

Proposed actions

Read-only. This feed informs operators; it changes nothing.

Proposed actions are target capabilities. Every action runs propose-first and needs a validated deployment and the appropriate permissions.

What you can build

  • Change HVAC filters ahead of ashfall

    When a volcano near a facility moves to WATCH or WARNING, the operator proposes pulling the next filter change forward and stocking spares, and records the notice identifier behind it.

    With Filter Change

  • Hold or reroute air freight

    A new VONA or a color code at ORANGE or RED on a lane's flight path becomes a proposed shipment hold or reroute for you to approve, with the VONA text attached.

    With Carrier Exception

  • Watch indoor air during an eruption

    A nearby volcano at ADVISORY or above raises the priority of particulate readings at that site. The operator proposes ventilation setpoint changes for your approval.

    With Indoor Air

  • Explain a drop in solar yield

    Ash in the air cuts array output. The operator matches a yield dip to a volcano in getElevatedVolcanoes and proposes an annotation instead of a fault ticket.

    With Array Yield

Requirements

  • A polling schedule; the API documents no push or webhook delivery
  • A mapping from your sites, lanes, or airports to Smithsonian volcano numbers or USGS volcano codes
  • An observatory code from the documented set (all, avo, calvo, cvo, hvo, nmi, yvo) when filtering recent notices
Authentication
None documented. The API pages describe no key, token, or account; requests are plain HTTP GETs, with search/search and search/preflight taking a JSON POST body.

Limits

  • getRecentNotices covers roughly the last month, per the endpoint description; older notices need search/search
  • getCapElevated lists only volcanoes whose current or previous status is at least ORANGE / WATCH
  • No rate limit or update interval is published
  • Coverage is US volcanoes and their observatories; volcanoes elsewhere are outside this API

Access and pricing

Reference listing. Public feed access is separate from Fibric integration. If you request this feed, your quote covers the build, usage, and support.

Request USGS Volcano Hazards Program HANS API ↗

Questions and answers

What is the difference between an alert level and a color code?
Volcano Alert Levels (NORMAL, ADVISORY, WATCH, WARNING) describe ground hazards. Aviation Color Codes (GREEN, YELLOW, ORANGE, RED) describe hazards to aircraft. A Volcano Activity Notice is issued when the alert level changes; a Volcano Observatory Notice for Aviation, VONA, when the color code changes.
How do I identify a volcano in requests?
By Smithsonian volcano number or USGS volcano code. volcano/getVolcano/{vnumOrVolcanoCd} and volcano/newestForVolcano/{vnumOrVolcanoCd} accept either. volcano/getUSVolcanoes returns all US volcanoes and volcano/getMonitoredVolcanoes those the USGS actively monitors.
Do I need a key, and what are the terms?
The API pages document no key or account. USGS-authored or produced data and information are in the US public domain; USGS suggests the credit 'U.S. Geological Survey'.
Ask about USGS Volcano Hazards Program HANS API

Ask about the capabilities and requirements in this listing.

For project-specific requirements, contact Fibric.

This Commons signal listing is developed, published, and supported by Fibric. It reads public data published by USGS Volcano Hazards Program (volcanoes.usgs.gov). Upstream agencies and projects are the property of their respective owners, who are not affiliated with Fibric and do not sponsor or endorse this listing. Trademark policy