NOAA — National Oceanic and Atmospheric Administration Alerts API
The Alerts API from NOAA — National Oceanic and Atmospheric Administration — 8 operation(s) for alerts.
OpenAPI Specification
openapi: 3.1.2
info:
title: weather.gov Alerts API
description: weather.gov API
version: 3.9.2
servers:
- url: https://api.weather.gov
description: Production server
security:
- userAgent: []
- apiKeyAuth: []
tags:
- name: Alerts
paths:
/alerts:
get:
description: Returns all alerts
operationId: alerts_query
parameters:
- name: active
in: query
description: List only active alerts (use /alerts/active endpoints instead)
deprecated: true
schema:
type: boolean
- $ref: '#/components/parameters/QueryStartTime'
- $ref: '#/components/parameters/QueryEndTime'
- $ref: '#/components/parameters/AlertStatus'
- $ref: '#/components/parameters/AlertMessageType'
- $ref: '#/components/parameters/AlertEventName'
- $ref: '#/components/parameters/AlertCode'
- $ref: '#/components/parameters/AlertArea'
- $ref: '#/components/parameters/AlertPoint'
- $ref: '#/components/parameters/AlertRegion'
- $ref: '#/components/parameters/AlertRegionType'
- $ref: '#/components/parameters/AlertZone'
- $ref: '#/components/parameters/AlertUrgency'
- $ref: '#/components/parameters/AlertSeverity'
- $ref: '#/components/parameters/AlertCertainty'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/PaginationCursor'
responses:
'200':
$ref: '#/components/responses/AlertCollection'
'301':
description: Certain common queries may be redirected to discrete URLs
default:
$ref: '#/components/responses/Error'
tags:
- Alerts
/alerts/active:
get:
description: Returns all currently active alerts
operationId: alerts_active
parameters:
- $ref: '#/components/parameters/AlertStatus'
- $ref: '#/components/parameters/AlertMessageType'
- $ref: '#/components/parameters/AlertEventName'
- $ref: '#/components/parameters/AlertCode'
- $ref: '#/components/parameters/AlertArea'
- $ref: '#/components/parameters/AlertPoint'
- $ref: '#/components/parameters/AlertRegion'
- $ref: '#/components/parameters/AlertRegionType'
- $ref: '#/components/parameters/AlertZone'
- $ref: '#/components/parameters/AlertUrgency'
- $ref: '#/components/parameters/AlertSeverity'
- $ref: '#/components/parameters/AlertCertainty'
responses:
'200':
$ref: '#/components/responses/AlertCollection'
'301':
description: Certain common queries may be redirected to discrete URLs
default:
$ref: '#/components/responses/Error'
tags:
- Alerts
/alerts/active/count:
get:
description: Returns info on the number of active alerts
operationId: alerts_active_count
responses:
'200':
description: A data structure showing the counts of active alerts broken down by various categories
headers:
X-Correlation-Id:
$ref: '#/components/headers/CorrelationId'
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-Server-Id:
$ref: '#/components/headers/ServerId'
content:
application/ld+json:
schema:
type: object
properties:
total:
minimum: 0
type: integer
description: The total number of active alerts
land:
minimum: 0
type: integer
description: The total number of active alerts affecting land zones
marine:
minimum: 0
type: integer
description: The total number of active alerts affecting marine zones
regions:
type: object
description: Active alerts by marine region
additionalProperties:
minimum: 1
type: integer
areas:
type: object
description: Active alerts by area (state/territory)
additionalProperties:
minimum: 1
type: integer
zones:
type: object
description: Active alerts by NWS public zone or county code
additionalProperties:
minimum: 1
type: integer
default:
$ref: '#/components/responses/Error'
parameters: []
tags:
- Alerts
/alerts/active/zone/{zoneId}:
parameters:
- $ref: '#/components/parameters/NWSZoneId'
get:
description: Returns active alerts for the given NWS public zone or county
operationId: alerts_active_zone
responses:
'200':
$ref: '#/components/responses/AlertCollection'
default:
$ref: '#/components/responses/Error'
parameters: []
tags:
- Alerts
/alerts/active/area/{area}:
parameters:
- name: area
in: path
description: State/area ID
required: true
schema:
$ref: '#/components/schemas/AreaCode'
get:
description: Returns active alerts for the given area (state or marine area)
operationId: alerts_active_area
responses:
'200':
$ref: '#/components/responses/AlertCollection'
default:
$ref: '#/components/responses/Error'
parameters: []
tags:
- Alerts
/alerts/active/region/{region}:
parameters:
- name: region
in: path
description: Marine region ID
required: true
schema:
$ref: '#/components/schemas/MarineRegionCode'
get:
description: Returns active alerts for the given marine region
operationId: alerts_active_region
responses:
'200':
$ref: '#/components/responses/AlertCollection'
default:
$ref: '#/components/responses/Error'
parameters: []
tags:
- Alerts
/alerts/types:
get:
description: Returns a list of alert types
operationId: alerts_types
responses:
'200':
description: A list of recognized event types
headers:
X-Correlation-Id:
$ref: '#/components/headers/CorrelationId'
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-Server-Id:
$ref: '#/components/headers/ServerId'
content:
application/ld+json:
schema:
type: object
properties:
eventTypes:
type: array
items:
type: string
description: A list of recognized event types
default:
$ref: '#/components/responses/Error'
parameters: []
tags:
- Alerts
/alerts/{id}:
parameters:
- name: id
in: path
description: Alert identifier
required: true
schema:
$ref: '#/components/schemas/AlertId'
get:
description: Returns a specific alert
operationId: alerts_single
responses:
'200':
description: An alert record
headers:
X-Correlation-Id:
$ref: '#/components/headers/CorrelationId'
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-Server-Id:
$ref: '#/components/headers/ServerId'
content:
application/geo+json:
schema:
$ref: '#/components/schemas/AlertGeoJson'
application/ld+json:
schema:
$ref: '#/components/schemas/AlertJsonLd'
application/cap+xml:
schema:
$ref: '#/components/schemas/AlertCap'
x-url-content-negotiation-extensions:
json: application/geo+json
cap: application/cap+xml
default:
$ref: '#/components/responses/Error'
parameters: []
tags:
- Alerts
components:
schemas:
AlertAtomEntry:
type: object
properties:
id:
type: string
xml:
namespace: http://www.w3.org/2005/Atom
updated:
type: string
xml:
namespace: http://www.w3.org/2005/Atom
published:
type: string
xml:
namespace: http://www.w3.org/2005/Atom
author:
type: object
properties:
name:
type: string
xml:
namespace: http://www.w3.org/2005/Atom
summary:
type: string
xml:
namespace: http://www.w3.org/2005/Atom
event:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
sent:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
effective:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
expires:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
status:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
msgType:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
category:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
urgency:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
severity:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
certainty:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
areaDesc:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
polygon:
type: string
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
geocode:
type: array
items:
$ref: '#/components/schemas/AlertXMLParameter'
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
parameter:
type: array
items:
$ref: '#/components/schemas/AlertXMLParameter'
xml:
namespace: urn:oasis:names:tc:emergency:cap:1.2
description: An alert entry in an Atom feed
xml:
name: entry
namespace: http://www.w3.org/2005/Atom
AreaCode:
oneOf:
- $ref: '#/components/schemas/StateTerritoryCode'
- $ref: '#/components/schemas/MarineAreaCode'
description: State/territory codes and marine area codes
AlertCap:
type: object
AlertCertainty:
enum:
- Observed
- Likely
- Possible
- Unlikely
- Unknown
type: string
Alert:
type: object
properties:
id:
$ref: '#/components/schemas/AlertId'
areaDesc:
type: string
description: A textual description of the area affected by the alert.
geocode:
type: object
properties:
UGC:
type: array
items:
$ref: '#/components/schemas/NWSZoneID'
description: A list of NWS public zone or county identifiers.
SAME:
type: array
items:
pattern: ^\d{6}$
type: string
description: A list of SAME (Specific Area Message Encoding) codes for affected counties.
description: Lists of codes for NWS public zones and counties affected by the alert.
affectedZones:
type: array
items:
type: string
format: uri
description: 'An array of API links for zones affected by the alert. This is an API-specific extension field and is not part of the CAP specification.
'
references:
type: array
items:
type: object
properties:
'@id':
type: string
description: An API link to the prior alert.
format: uri
identifier:
$ref: '#/components/schemas/AlertId'
sender:
type: string
description: The sender of the prior alert.
sent:
type: string
description: The time the prior alert was sent.
format: date-time
description: A list of prior alerts that this alert updates or replaces.
sent:
type: string
description: The time of the origination of the alert message.
format: date-time
effective:
type: string
description: The effective time of the information of the alert message.
format: date-time
onset:
type:
- string
- 'null'
description: The expected time of the beginning of the subject event of the alert message.
format: date-time
expires:
type: string
description: The expiry time of the information of the alert message.
format: date-time
ends:
type:
- string
- 'null'
description: The expected end time of the subject event of the alert message.
format: date-time
status:
$ref: '#/components/schemas/AlertStatus'
messageType:
$ref: '#/components/schemas/AlertMessageType'
category:
enum:
- Met
- Geo
- Safety
- Security
- Rescue
- Fire
- Health
- Env
- Transport
- Infra
- CBRNE
- Other
type: string
description: The code denoting the category of the subject event of the alert message.
severity:
$ref: '#/components/schemas/AlertSeverity'
certainty:
$ref: '#/components/schemas/AlertCertainty'
urgency:
$ref: '#/components/schemas/AlertUrgency'
event:
type: string
description: The text denoting the type of the subject event of the alert message.
sender:
type: string
description: Email address of the NWS webmaster.
senderName:
type: string
description: The text naming the originator of the alert message.
headline:
type:
- string
- 'null'
description: The text headline of the alert message.
description:
type: string
description: The text describing the subject event of the alert message.
instruction:
type:
- string
- 'null'
description: 'The text describing the recommended action to be taken by recipients of the alert message.
'
note:
type:
- string
- 'null'
description: 'The text note accompanying the alert message. Per CAP spec, this should accompany alerts with a status of "Test".
'
response:
enum:
- Shelter
- Evacuate
- Prepare
- Execute
- Avoid
- Monitor
- Assess
- AllClear
- None
type: string
description: 'The code denoting the type of action recommended for the target audience.
This corresponds to responseType in the CAP specification.
'
parameters:
type: object
description: 'System-specific additional parameters associated with the alert message.
The keys in this object correspond to parameter definitions in the NWS CAP specification.
'
additionalProperties:
type: array
items: {}
scope:
enum:
- Public
- Restricted
- Private
type: string
description: The code denoting the intended distribution of the alert message.
code:
type: string
description: The code denoting the special handling of the alert message.
language:
type: string
description: The code denoting the language of the info sub-element of the alert message.
web:
type: string
description: The identifier of the hyperlink associating additional information within the alert message.
eventCode:
type: object
description: 'System-specific code identifiying the event type of the alert message The keys in this object correspond to eventCode definitions in the NWS CAP specification.
'
additionalProperties:
type: array
items: {}
description: 'An object representing a public alert message.
Unless otherwise noted, the fields in this object correspond to the National Weather Service CAP v1.2 specification, which extends the OASIS Common Alerting Protocol (CAP) v1.2 specification and USA Integrated Public Alert and Warning System (IPAWS) Profile v1.0. Refer to this documentation for more complete information.
http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html http://docs.oasis-open.org/emergency/cap/v1.2/ipaws-profile/v1.0/cs01/cap-v1.2-ipaws-profile-cs01.html https://vlab.noaa.gov/web/nws-common-alerting-protocol/cap-documentation
'
MarineAreaCode:
enum:
- AM
- AN
- GM
- LC
- LE
- LH
- LM
- LO
- LS
- PH
- PK
- PM
- PS
- PZ
- SL
type: string
description: 'Marine area code as defined in NWS Directive 10-302:
* AM: Western North Atlantic Ocean and along U.S. East Coast south of Currituck Beach Light NC following the coastline into Gulf of Mexico to Ocean Reef FL including the Caribbean
* AN: Western North Atlantic Ocean and along U.S. East Coast from Canadian border south to Currituck Beach Light NC
* GM: Gulf of Mexico and along the U.S. Gulf Coast from the Mexican border to Ocean Reef FL
* LC: Lake St. Clair
* LE: Lake Erie
* LH: Lake Huron
* LM: Lake Michigan
* LO: Lake Ontario
* LS: Lake Superior
* PH: Central Pacific Ocean including Hawaiian waters
* PK: North Pacific Ocean near Alaska and along Alaska coastline including the Bering Sea and the Gulf of Alaska
* PM: Western Pacific Ocean including Mariana Island waters
* PS: South Central Pacific Ocean including American Samoa waters
* PZ: Eastern North Pacific Ocean and along U.S. West Coast from Canadian border to Mexican border
* SL: St. Lawrence River above St. Regis
'
PointString:
pattern: ^(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)$
type: string
GeoJsonBoundingBox:
minItems: 4
type: array
items:
type: number
description: A GeoJSON bounding box. Please refer to IETF RFC 7946 for information on the GeoJSON format.
GeoJsonGeometry:
oneOf:
- title: GeoJSON Point
required:
- type
- coordinates
type: object
properties:
type:
enum:
- Point
type: string
coordinates:
$ref: '#/components/schemas/GeoJsonCoordinate'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- title: GeoJSON LineString
required:
- type
- coordinates
type: object
properties:
type:
enum:
- LineString
type: string
coordinates:
$ref: '#/components/schemas/GeoJsonLineString'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- title: GeoJSON Polygon
required:
- type
- coordinates
type: object
properties:
type:
enum:
- Polygon
type: string
coordinates:
$ref: '#/components/schemas/GeoJsonPolygon'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- title: GeoJSON MultiPoint
required:
- type
- coordinates
type: object
properties:
type:
enum:
- MultiPoint
type: string
coordinates:
type: array
items:
$ref: '#/components/schemas/GeoJsonCoordinate'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- title: GeoJSON MultiLineString
required:
- type
- coordinates
type: object
properties:
type:
enum:
- MultiLineString
type: string
coordinates:
type: array
items:
$ref: '#/components/schemas/GeoJsonLineString'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- title: GeoJSON MultiPolygon
required:
- type
- coordinates
type: object
properties:
type:
enum:
- MultiPolygon
type: string
coordinates:
type: array
items:
$ref: '#/components/schemas/GeoJsonPolygon'
bbox:
$ref: '#/components/schemas/GeoJsonBoundingBox'
- type: 'null'
description: A GeoJSON geometry object. Please refer to IETF RFC 7946 for information on the GeoJSON format.
GeoJsonLineString:
minItems: 2
type: array
items:
$ref: '#/components/schemas/GeoJsonCoordinate'
description: A GeoJSON line string. Please refer to IETF RFC 7946 for information on the GeoJSON format.
AlertGeoJson:
allOf:
- $ref: '#/components/schemas/GeoJsonFeature'
- type: object
properties:
properties:
$ref: '#/components/schemas/Alert'
AlertStatus:
enum:
- Actual
- Exercise
- System
- Test
- Draft
type: string
GeoJsonFeatureCollection:
required:
- type
- features
type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
type:
enum:
- FeatureCollection
type: string
features:
type: array
items:
$ref: '#/components/schemas/GeoJsonFeature'
description: A GeoJSON feature collection. Please refer to IETF RFC 7946 for information on the GeoJSON format.
GeoJsonFeature:
required:
- type
- geometry
- properties
type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
id:
type: string
format: uri
type:
enum:
- Feature
type: string
geometry:
$ref: '#/components/schemas/GeoJsonGeometry'
properties:
type: object
description: A GeoJSON feature. Please refer to IETF RFC 7946 for information on the GeoJSON format.
additionalProperties: false
AlertCollectionGeoJson:
allOf:
- $ref: '#/components/schemas/GeoJsonFeatureCollection'
- type: object
properties:
features:
type: array
items:
type: object
properties:
properties:
$ref: '#/components/schemas/Alert'
- $ref: '#/components/schemas/AlertCollection'
NWSZoneID:
pattern: ^(A[KLMNRSZ]|C[AOT]|D[CE]|F[LM]|G[AMU]|I[ADLN]|K[SY]|L[ACEHMOS]|M[ADEHINOPST]|N[CDEHJMVY]|O[HKR]|P[AHKMRSWZ]|S[CDL]|T[NX]|UT|V[AIT]|W[AIVY]|[HR]I)[CZ]\d{3}$
type: string
description: 'UGC identifier for a NWS forecast zone or county.
The first two letters will correspond to either a state code or marine area code (see #/components/schemas/StateTerritoryCode and #/components/schemas/MarineAreaCode for lists of valid letter combinations).
The third letter will be Z for public/fire zone or C for county.
'
PaginationInfo:
required:
- next
type: object
properties:
next:
type: string
description: A link to the next page of records
format: uri
description: Links for retrieving more data from paged data sets
additionalProperties: false
AlertAtomFeed:
type: object
properties:
id:
type: string
xml:
namespace: http://www.w3.org/2005/Atom
generator:
type: string
xml:
namespace: http://www.w3.org/2005/Atom
updated:
type: string
xml:
namespace: http://www.w3.org/2005/Atom
author:
type: object
properties:
name:
type: string
xml:
namespace: http://www.w3.org/2005/Atom
xml:
namespace: http://www.w3.org/2005/Atom
title:
type: string
xml:
namespace: http://www.w3.org/2005/Atom
entry:
type: array
items:
$ref: '#/components/schemas/AlertAtomEntry'
xml:
namespace: http://www.w3.org/2005/Atom
description: An alert feed in Atom format
xml:
name: feed
namespace: http://www.w3.org/2005/Atom
AlertId:
type: string
description: The identifier of the alert message.
MarineRegionCode:
enum:
- AL
- AT
- GL
- GM
- PA
- PI
type: string
description: 'Marine region code. These are groups of marine areas combined.
* AL: Alaska waters (PK)
* AT: Atlantic Ocean (AM, AN)
* GL: Great Lakes (LC, LE, LH, LM, LO, LS, SL)
* GM: Gulf of Mexico (GM)
* PA: Eastern Pacific Ocean and U.S. West Coast (PZ)
* PI: Central and Western Pacific (PH, PM, PS)
'
AlertXMLParameter:
type: object
properties:
valueName:
type: string
value:
type: string
AlertUrgency:
enum:
- Immediate
- Expected
- Future
- Past
- Unknown
type: string
AlertSeverity:
enum:
- Extreme
- Severe
- Moderate
- Minor
- Unknown
type: string
StateTerritoryCode:
enum:
- AL
- AK
- AS
- AR
- AZ
- CA
- CO
- CT
- DE
- DC
- FL
- GA
- GU
- HI
- ID
- IL
- IN
- IA
- KS
- KY
- LA
- ME
- MD
- MA
- MI
- MN
- MS
- MO
- MT
- NE
- NV
- NH
- NJ
- NM
- NY
- NC
- ND
- OH
- OK
- OR
- PA
- PR
- RI
- SC
- SD
- TN
- TX
- UT
- VT
- VI
- VA
- WA
- WV
- WI
- WY
- MP
- PW
- FM
- MH
type: string
GeoJsonCoordinate:
minItems: 2
type: array
items:
type: number
description: A GeoJSON coordinate. Please refer to IETF RFC 7946 for information on the GeoJSON format.
AlertCollection:
type: object
properties:
title:
type: string
description: A title describing the alert collection
updated:
type: string
description: The last time a change occurred to this collection
format: date-time
pagination:
$ref: '#/components/schemas/PaginationInfo'
AlertJsonLd:
type: object
properties:
'@graph':
type: array
items:
$ref: '#/components/schemas/Alert'
AlertMessageType:
enum:
- Alert
- Update
- Cancel
- Ack
- Error
type: string
AlertCollectionJsonLd:
allOf:
- $ref: '#/components/schemas/AlertCollection'
- type: object
properties:
'@context':
$ref: '#/components/schemas/JsonLdContext'
'@graph':
type: array
items:
$ref: '#/components/schemas/Alert'
GeoJsonPolygon:
type: array
items:
minItems: 4
type: array
items:
$ref: '#/components/schemas/GeoJsonCoordinate'
description: A GeoJSON polygon. Please refer to IETF RFC 7946 for information on the GeoJSON format.
ProblemDetail:
required:
- type
- title
- status
- detail
- instance
- correlationId
type: object
properties:
type:
type: string
description: 'A URI reference (RFC 3986) that identifies the problem type. This is only an identifier and is not necessarily a resolvable URL.
'
format: uri
default: about:blank
examples:
- urn:noaa:nws:api:UnexpectedProblem
title:
type: string
description: A short, human-readable summary of the problem type.
examples:
- Unexpected Problem
status:
maximum: 999
minimum: 100
type: number
description: 'The HTTP status code (RFC 7231, Section 6) generated by the origin server for this occurrence of the problem.
'
examples:
- 500
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem.
examples:
- An unexpected problem has occurred.
instance:
type: string
description: 'A URI reference (RFC 3986) that identifies the specific occurrence of the problem. This is only an identifier and is not necessarily a resolvable URL.
'
format: uri
examples:
- urn:noaa:nws:api:request:493c3a1d-f87e-407f-ae2c-24483f5aab63
correlationId:
type: string
description: 'A unique identifier for the request, used for NWS debugging purposes. Please include this identifier with any correspondence to help us investigate your issue.
'
examples:
- 493c3a1d-f87e-407f-ae2c-24483f5aab63
description: Detail about an error. This document conforms to RFC 7807 (Problem Details for HTTP APIs).
additionalProperties: true
JsonLdContext:
anyOf:
- type: array
items: {}
- type: object
parameters:
PaginationCursor:
name: cursor
in: query
description: Pagination cursor
schema:
type: string
AlertMessageType:
name: message_type
in: query
description: Message type (alert, update, cancel)
style: form
explode: false
schema:
type: array
items:
enum:
- alert
- update
- cancel
type: string
AlertEventName:
name: event
in: query
description: Event name
style: form
explode: false
schema:
type: array
items:
pattern: ^[A-Za-z0-9 ]+$
type: string
AlertSeverity:
name: severity
in: query
description: Severity (extreme, severe, moderate, minor, unknown)
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AlertSeverity'
AlertCode:
name: code
in: query
description: Event code
style: form
explode: false
schema:
type: array
items:
pattern: ^\w{3}$
type: string
AlertRegionType:
name: region_type
in: query
description: 'Region type (land or marine)
This parameter is incompatible with the following parameters: area, point, region, zone
'
schema:
enum:
- land
- marine
type: string
Limit:
name: limit
in: query
description: Limit
schema:
maximum: 500
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/noaa-gov/refs/heads/main/openapi/noaa-gov-alerts-api-openapi.yml