NOAA — National Oceanic and Atmospheric Administration Aviation API

openapi: 3.1.2
info:
  title: weather.gov Alerts Aviation API
  description: weather.gov API
  version: 3.9.2
servers:
- url: https://api.weather.gov
  description: Production server
security:
- userAgent: []
- apiKeyAuth: []
tags:
- name: Aviation
paths:
  /aviation/cwsus/{cwsuId}:
    get:
      description: Returns metadata about a Center Weather Service Unit
      operationId: cwsu
      parameters:
      - $ref: '#/components/parameters/NWSCenterWeatherServiceUnitId'
      responses:
        '200':
          description: success
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/CenterWeatherServiceUnitJsonLd'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Aviation
  /aviation/cwsus/{cwsuId}/cwas:
    get:
      description: Returns a list of Center Weather Advisories from a CWSU
      operationId: cwas
      parameters:
      - $ref: '#/components/parameters/NWSCenterWeatherServiceUnitId'
      responses:
        '200':
          description: success
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/CenterWeatherAdvisoryCollectionGeoJson'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Aviation
  /aviation/cwsus/{cwsuId}/cwas/{date}/{sequence}:
    get:
      description: Returns a list of Center Weather Advisories from a CWSU
      operationId: cwa
      parameters:
      - $ref: '#/components/parameters/NWSCenterWeatherServiceUnitId'
      - $ref: '#/components/parameters/Date'
      - name: sequence
        in: path
        description: Sequence number
        required: true
        schema:
          minimum: 100
          type: integer
      responses:
        '200':
          description: success
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/CenterWeatherAdvisoryGeoJson'
            application/vnd.noaa.uswx+xml:
              schema: {}
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Aviation
  /aviation/sigmets:
    get:
      description: Returns a list of SIGMET/AIRMETs
      operationId: sigmetQuery
      parameters:
      - $ref: '#/components/parameters/QueryStartTime'
      - $ref: '#/components/parameters/QueryEndTime'
      - $ref: '#/components/parameters/QueryDate'
      - name: atsu
        in: query
        description: ATSU identifier
        schema:
          $ref: '#/components/schemas/ATSUIdentifier'
      - name: sequence
        in: query
        description: SIGMET sequence number
        schema:
          $ref: '#/components/schemas/SigmetSequenceNumber'
      responses:
        '200':
          description: success
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/SigmetCollectionGeoJson'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Aviation
  /aviation/sigmets/{atsu}:
    get:
      description: Returns a list of SIGMET/AIRMETs for the specified ATSU
      operationId: sigmetsByATSU
      parameters:
      - $ref: '#/components/parameters/ATSUIdentifier'
      responses:
        '200':
          description: success
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/SigmetCollectionGeoJson'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Aviation
  /aviation/sigmets/{atsu}/{date}:
    get:
      description: Returns a list of SIGMET/AIRMETs for the specified ATSU for the specified date
      operationId: sigmetsByATSUByDate
      parameters:
      - $ref: '#/components/parameters/ATSUIdentifier'
      - $ref: '#/components/parameters/Date'
      responses:
        '200':
          description: success
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/SigmetCollectionGeoJson'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Aviation
  /aviation/sigmets/{atsu}/{date}/{time}:
    get:
      description: Returns a specific SIGMET/AIRMET
      operationId: sigmet
      parameters:
      - $ref: '#/components/parameters/ATSUIdentifier'
      - $ref: '#/components/parameters/Date'
      - $ref: '#/components/parameters/Time'
      responses:
        '200':
          description: success
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/SigmetGeoJson'
            application/vnd.noaa.uswx+xml:
              schema: {}
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Aviation
components:
  schemas:
    Date:
      type: string
      description: Date (in YYYY-MM-DD format).
      format: date
    CenterWeatherAdvisoryCollectionGeoJson:
      allOf:
      - $ref: '#/components/schemas/GeoJsonFeatureCollection'
      - type: object
        properties:
          features:
            type: array
            items:
              type: object
              properties:
                properties:
                  $ref: '#/components/schemas/CenterWeatherAdvisory'
    SigmetCollectionGeoJson:
      allOf:
      - $ref: '#/components/schemas/GeoJsonFeatureCollection'
      - type: object
        properties:
          features:
            type: array
            items:
              $ref: '#/components/schemas/SigmetGeoJson'
    CenterWeatherAdvisory:
      type: object
      properties:
        id:
          type: string
        issueTime:
          type: string
          format: date-time
        cwsu:
          $ref: '#/components/schemas/NWSCenterWeatherServiceUnitId'
        sequence:
          minimum: 101
          type: integer
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        observedProperty:
          type: string
        text:
          type: string
      additionalProperties: false
    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.
    Time:
      pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      type: string
      description: A time (in HHMM format). This is always specified in UTC (Zulu) time.
    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.
    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
    SigmetGeoJson:
      allOf:
      - $ref: '#/components/schemas/GeoJsonFeature'
      - type: object
        properties:
          properties:
            $ref: '#/components/schemas/Sigmet'
    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.
    NWSCenterWeatherServiceUnitId:
      enum:
      - ZAB
      - ZAN
      - ZAU
      - ZBW
      - ZDC
      - ZDV
      - ZFA
      - ZFW
      - ZHU
      - ZID
      - ZJX
      - ZKC
      - ZLA
      - ZLC
      - ZMA
      - ZME
      - ZMP
      - ZNY
      - ZOA
      - ZOB
      - ZSE
      - ZTL
      type: string
      description: Three-letter identifier for a Center Weather Service Unit (CWSU).
    CenterWeatherServiceUnitJsonLd:
      $ref: '#/components/schemas/Office'
    Office:
      type: object
      properties:
        '@context':
          $ref: '#/components/schemas/JsonLdContext'
        '@type':
          enum:
          - GovernmentOrganization
          type: string
        '@id':
          type: string
          format: uri
        id:
          type: string
        name:
          type: string
        address:
          type: object
          properties:
            '@type':
              enum:
              - PostalAddress
              type: string
            streetAddress:
              type: string
            addressLocality:
              type: string
            addressRegion:
              type: string
            postalCode:
              type: string
          additionalProperties: false
        telephone:
          type: string
        faxNumber:
          type: string
        email:
          type: string
        sameAs:
          type: string
          format: uri
        nwsRegion:
          type: string
        parentOrganization:
          type: string
          format: uri
        responsibleCounties:
          type: array
          items:
            type: string
            format: uri
        responsibleForecastZones:
          type: array
          items:
            type: string
            format: uri
        responsibleFireZones:
          type: array
          items:
            type: string
            format: uri
        approvedObservationStations:
          type: array
          items:
            type: string
            format: uri
      additionalProperties: false
    SigmetSequenceNumber:
      type: string
    CenterWeatherAdvisoryGeoJson:
      allOf:
      - $ref: '#/components/schemas/GeoJsonFeature'
      - type: object
        properties:
          properties:
            $ref: '#/components/schemas/CenterWeatherAdvisory'
    GeoJsonCoordinate:
      minItems: 2
      type: array
      items:
        type: number
      description: A GeoJSON coordinate. Please refer to IETF RFC 7946 for information on the GeoJSON format.
    Sigmet:
      type: object
      properties:
        id:
          type: string
          format: uri
        issueTime:
          type: string
          format: date-time
        fir:
          type:
          - string
          - 'null'
        atsu:
          $ref: '#/components/schemas/ATSUIdentifier'
        sequence:
          type:
          - string
          - 'null'
        phenomenon:
          type:
          - string
          - 'null'
          format: uri
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
      additionalProperties: false
    ATSUIdentifier:
      pattern: ^[A-Z]{3,4}$
      type: string
      description: ATSU Identifier
    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:
    NWSCenterWeatherServiceUnitId:
      name: cwsuId
      in: path
      description: NWS CWSU ID
      required: true
      schema:
        $ref: '#/components/schemas/NWSCenterWeatherServiceUnitId'
    ATSUIdentifier:
      name: atsu
      in: path
      description: ATSU identifier
      required: true
      schema:
        $ref: '#/components/schemas/ATSUIdentifier'
    Date:
      name: date
      in: path
      description: Date (YYYY-MM-DD format)
      required: true
      schema:
        $ref: '#/components/schemas/Date'
    Time:
      name: time
      in: path
      description: Time (HHMM format). This time is always specified in UTC (Zulu) time.
      required: true
      schema:
        $ref: '#/components/schemas/Time'
    QueryEndTime:
      name: end
      in: query
      description: End time
      schema:
        type: string
        format: date-time
    QueryStartTime:
      name: start
      in: query
      description: Start time
      schema:
        type: string
        format: date-time
    QueryDate:
      name: date
      in: query
      description: Date (YYYY-MM-DD format)
      schema:
        $ref: '#/components/schemas/Date'
  headers:
    RequestId:
      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.

        '
      schema:
        type: string
    CorrelationId:
      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.

        '
      schema:
        type: string
    ServerId:
      description: 'The identifier of the server that generated the response, used for NWS debugging purposes. Please include this identifier with any correspondence to help us investigate your issue.

        '
      schema:
        type: string
  responses:
    Error:
      description: An error response.
      headers:
        X-Correlation-Id:
          $ref: '#/components/headers/CorrelationId'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        X-Server-Id:
          $ref: '#/components/headers/ServerId'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
  securitySchemes:
    userAgent:
      type: apiKey
      description: 'We require that all consumers of the API include a User-Agent header in requests. This is due to a high number of scripts exhibiting abusive behavior (intentional or unintentional). We recommend setting the value to something that identifies your application and includes a contact email. This will help us contact you if we notice unusual behavior and also aid in troubleshooting issues.

        The API remains open and free to use and there are no limits imposed based on the User-Agent string.

        This mechanism will be replaced with a more typical API key system at a later date.

        '
      name: User-Agent
      in: header
    apiKeyAuth:
      type: apiKey
      description: 'We are testing including a more traditional API Key system on certain endpoints.  This is due to a large change in the weather.gov site.

        The API remains open and free to use and there are no limits imposed based on the X-Api-Key string.

        '
      name: API-Key
      in: header
externalDocs:
  description: Full API documentation
  url: https://www.weather.gov/documentation/services-web-api