openapi: 3.0.3
info:
  title: NWS ALERTS | a Weather Source API
  description: |
    **Description:**

    NWS advisories, watches and warnings for latitude/longitude points and OnPoint™ points.

    Weather Source APIs are built upon the [OnPoint™ Platform](https://www.pelmorex.com/en/products-and-solutions/weather-source/onpoint-weather-data-suite/) which ensures data that is gap-free, homogeneous, and ready for immediate analysis. We offer one of the highest resolution grids on the market, covering every landmass in the world and up to 200 miles offshore.

    **Authorization:**

    Requests are authorized by a header named `X-API-KEY` with a value of your API key. If you do not have a Weather Source API key [sign up for a free developer account](https://developer.weathersourceapis.com/account/sign-up/) to trial the data, or contact sales at [weathersource@pelmorex.com](mailto:weathersource@pelmorex.com) to explore the right subscription package for your business.

    When using the \"Try it out\" capability in the documentation, your API key should be added by clicking the green \"Authorize\" button at the top of the page. You may use the evaluation API Key `C0W60UOFRML47ytbXk4xlLBfv` to access example locations found in this documentation.
  termsOfService: https://weathersource.com/company/legal/terms-of-service/
  contact:
    name: Weather Source APIs
    url: https://developer.weathersourceapis.com/
    email: weathersource@pelmorex.com
  version: 2.0.1
servers:
- url: https://nwswarnings.weathersourceapis.com/v2
security:
- ApiKeyAuth: []
tags:
- name: points
  description: "Latitude/Longitude NWS advisories, watches and warnings"
- name: onpoints
  description: "OnPoint™ point NWS advisories, watches and warnings"
paths:
  /points/{latitude},{longitude}:
    get:
      tags:
      - points
      summary: "NWS advisories, watches and warnings for a Latitude/Longitude point."
      description: |
        Returns NWS advisories, watches and warnings data for a Latitude/Longitude point.

        **IMPORTANT:** To authenticate to the Weather Source NWS Warnings API, each request must contain your API key set to a custom header named `X-API-KEY`. If you do not have a Weather Source API key [sign up for a free 30-day developer account](https://developer.weathersourceapis.com/account/sign-up/). You may use the evaluation API Key `C0W60UOFRML47ytbXk4xlLBfv` to access example locations found in this documentation.

        When using the \"Try it out\" capability in the documentation, the API key should be added by clicking the green \"Authorize\" button at the top of the page.
      parameters:
      - name: latitude
        in: path
        description: A latitude value between -90° and 90°.
        required: true
        schema:
          maximum: 90
          minimum: -90
          type: number
          format: float
          example: 38.8552
      - name: longitude
        in: path
        description: A longitude value between -180° (West) and 180° (East).
        required: true
        schema:
          maximum: 180
          minimum: -180
          type: number
          format: float
          example: -77.0513
      responses:
        "200":
          description: NWS Warnings response for a Latitude/Longitude point.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/nwsWarningsPointObj"
        default:
          $ref: "#/components/responses/errorResponse"
  /onpoints/{onpointId}:
    get:
      tags:
      - onpoints
      summary: "NWS advisories, watches and warnings for an OnPoint™ point."
      description: |
        Returns NWS advisories, watches and warnings data for an OnPoint™ point.

        **IMPORTANT:** To authenticate to the Weather Source NWS Warnings API, each request must contain your API key set to a custom header named `X-API-KEY`. If you do not have a Weather Source API key [sign up for a free 30-day developer account](https://developer.weathersourceapis.com/account/sign-up/). You may use the evaluation API Key `C0W60UOFRML47ytbXk4xlLBfv` to access example locations found in this documentation.

        When using the \"Try it out\" capability in the documentation, the API key should be added by clicking the green \"Authorize\" button at the top of the page.
      parameters:
      - name: onpointId
        in: path
        description: An OnPoint™ ID.
        required: true
        schema:
          type: integer
          example: 10725864
      responses:
        "200":
          description: NWS Warnings response for an OnPoint™ point.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/nwsWarningsOnpointObj"
        default:
          $ref: "#/components/responses/errorResponse"
components:
  schemas:
    fieldListObj:
      title: fieldListObj
      required:
      - fields
      type: object
      properties:
        fields:
          $ref: "#/components/schemas/fields"
      description: A list of returned field names the associated units.
      example:
        fields:
          timestampExpires: "Timestamp as string: RFC 3339"
          phenomCode: String value
          phenomDesc: String value
          significance: String value in
    nwsWarningsArr:
      type: array
      description: An array of NWS Warnings objects.
      items:
        $ref: "#/components/schemas/nwsWarningsObj"
    nwsWarningsObj:
      required:
      - phenomCode
      - phenomDesc
      - significance
      - timestampExpires
      type: object
      properties:
        timestampExpires:
          $ref: "#/components/schemas/timestampExpires"
        phenomCode:
          $ref: "#/components/schemas/phenomCode"
        phenomDesc:
          $ref: "#/components/schemas/phenomDesc"
        significance:
          $ref: "#/components/schemas/significance"
      description: A NWS Warnings object.
    nwsWarningsPointObj:
      required:
      - fieldList
      - location
      - warnings
      type: object
      properties:
        location:
          $ref: "#/components/schemas/pointObj"
        fieldList:
          $ref: "#/components/schemas/fieldListObj"
        warnings:
          $ref: "#/components/schemas/nwsWarningsArr"
      description: Latitude/Longitude NWS Warnings object
    nwsWarningsOnpointObj:
      required:
      - fieldList
      - location
      - warnings
      type: object
      properties:
        location:
          $ref: "#/components/schemas/onpointObj"
        fieldList:
          $ref: "#/components/schemas/fieldListObj"
        warniungs:
          $ref: "#/components/schemas/nwsWarningsArr"
      description: OnPoint™ point NWS Warnings object
    timestampExpires:
      type: string
      description: "A timestamp formatted as an RFC3339 date-time value that indicates when the advisory, watch, or warning expires."
      format: date-time
      example: 2019-12-20T23:00:00-05:00
    phenomCode:
      type: string
      description: "A 2-character string indicating the phenomena for which the advisory, watch, or warning was issued."
      example: WI
      enum:
      - AF
      - AS
      - BH
      - BW
      - BZ
      - CF
      - DF
      - DS
      - DU
      - EC
      - EH
      - EW
      - FA
      - FF
      - FG
      - FL
      - FR
      - FW
      - FZ
      - GL
      - HF
      - HT
      - HU
      - HW
      - HY
      - HZ
      - IS
      - LE
      - LO
      - LS
      - LW
      - MA
      - MF
      - MH
      - MS
      - RP
      - SC
      - SE
      - SM
      - SQ
      - SR
      - SS
      - SU
      - SV
      - TO
      - TR
      - TS
      - TY
      - UP
      - WC
      - WI
      - WS
      - WW
      - ZF
      - ZY
    phenomDesc:
      type: string
      description: "Description of the phenomena for which the advisory, watch, or warning was issued."
      example: Wind
      enum:
      - Ashfall (land)
      - Air Stagnation
      - Beach Hazard
      - Brisk Wind
      - Blizzard
      - Coastal Flood
      - Debris Flow
      - Dust Storm
      - Blowing Dust
      - Extreme Cold
      - Excessive Heat
      - Extreme Wind
      - Flood
      - Flash Flood
      - Dense Fog (land)
      - Flood (forecast point)
      - Frost
      - Fire Weather
      - Freeze
      - Gale
      - Hurricane Force Wind
      - Heat
      - Hurricane
      - High Wind
      - Hydrologic
      - Hard Freeze
      - Ice Storm
      - Lake Effect Snow
      - Low Water
      - Lakeshore Flood
      - Lake Wind
      - Marine
      - Dense Fog (marine)
      - Ashfall (marine)
      - Dense Smoke (marine)
      - Rip Current Risk
      - Small Craft
      - Hazardous Seas
      - Dense Smoke (land)
      - Snow Squall
      - Storm
      - Storm Surge
      - High Surf
      - Severe Thunderstorm
      - Tornado
      - Tropical Storm
      - Tsunami
      - Typhoon
      - Heavy Freezing Spray
      - Wind Chill
      - Wind
      - Winter Storm
      - Winter Weather
      - Freezing Fog
      - Freezing Spray
    significance:
      type: string
      description: The risk significance for the phenomona.
      example: WATCH
      enum:
      - ADVISORY
      - WATCH
      - WARNING
    errorObj:
      type: object
      properties:
        errorCode:
          maximum: 600
          minimum: 100
          type: integer
          example: 404
        errorMessage:
          type: string
          example: NOT FOUND. Item not found.
    fields:
      type: object
      additionalProperties:
        type: string
        description: Unit value for field identified in the related key.
        example: Fahrenheit
    pointObj:
      required:
      - boundingPoints
      - elevation
      - grid
      - latitude
      - longitude
      - timezone
      type: object
      properties:
        latitude:
          $ref: "#/components/schemas/latitude"
        longitude:
          $ref: "#/components/schemas/longitude"
        timezone:
          $ref: "#/components/schemas/timezone"
        countryCode:
          $ref: "#/components/schemas/countryCode"
        countryName:
          $ref: "#/components/schemas/countryName"
        subdivCode:
          $ref: "#/components/schemas/subdivCode"
        subdivName:
          $ref: "#/components/schemas/subdivName"
        boundingPoints:
          $ref: "#/components/schemas/boundingPoints"
        grid:
          $ref: "#/components/schemas/grid"
        elevation:
          $ref: "#/components/schemas/elevation"
      description: Metadata object for a postcode
    latitude:
      maximum: 90
      minimum: -90
      type: number
      description: A latitude value between -90° and 90°.
      format: float
      example: 38.8552
    longitude:
      maximum: 180
      minimum: -180
      type: number
      description: A longitude value between -180° (West) and 180° (East).
      format: float
      example: -77.0513
    timezone:
      type: string
      description: An Olson timezone ID.
      example: America/New_York
    countryCode:
      type: string
      description: "An [ISO 3166-1 Alpha-2 country code](https://developer.weathersourceapis.com/apis/countries-with-postal-code-support/)."
      example: US
    countryName:
      type: string
      description: A common country name.
      example: United States of America
    subdivCode:
      type: string
      description: An ISO 3166-2 country subdivision code.
      example: US-VA
    subdivName:
      type: string
      description: A common country subdivision name.
      example: Virginia
    boundingPoints:
      type: array
      description: A list of OnPoint™ points related to the location
      items:
        $ref: "#/components/schemas/boundingPoints_inner"
    onpointId:
      type: integer
      description: An OnPoint™ ID.
      example: 10725864
    grid:
      type: string
      description: The OnPoint™ grid on which the resource exists.
      example: NORTH_AMERICA_GRID
      enum:
      - GLOBAL_GRID
      - NORTH_AMERICA_GRID
    distance:
      type: number
      description: A distance from the provided point in miles.
      format: float
      example: 2.6772
    elevation:
      type: number
      description: The elevation above sea level of a location in meters
      format: float
      example: 173.5
    onpointObj:
      required:
      - elevation
      - grid
      - latitude
      - longitude
      - onpointId
      - timezone
      type: object
      properties:
        onpointId:
          $ref: "#/components/schemas/onpointId"
        latitude:
          $ref: "#/components/schemas/latitude"
        longitude:
          $ref: "#/components/schemas/longitude"
        timezone:
          $ref: "#/components/schemas/timezone"
        countryCode:
          $ref: "#/components/schemas/countryCode"
        countryName:
          $ref: "#/components/schemas/countryName"
        subdivCode:
          $ref: "#/components/schemas/subdivCode"
        subdivName:
          $ref: "#/components/schemas/subdivName"
        grid:
          $ref: "#/components/schemas/grid"
        elevation:
          $ref: "#/components/schemas/elevation"
      description: An OnPoint™ point location metadata object
    boundingPoints_inner:
      required:
      - distance
      - elevation
      - grid
      - latitude
      - longitude
      - onpointId
      type: object
      properties:
        onpointId:
          $ref: "#/components/schemas/onpointId"
        latitude:
          $ref: "#/components/schemas/latitude"
        longitude:
          $ref: "#/components/schemas/longitude"
        grid:
          $ref: "#/components/schemas/grid"
        distance:
          $ref: "#/components/schemas/distance"
        elevation:
          $ref: "#/components/schemas/elevation"
  responses:
    errorResponse:
      description: Unexpected error response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/errorObj"
  parameters:
    latitude:
      name: latitude
      in: path
      description: A latitude value between -90° and 90°.
      required: true
      schema:
        maximum: 90
        minimum: -90
        type: number
        format: float
        example: 38.8552
    longitude:
      name: longitude
      in: path
      description: A longitude value between -180° (West) and 180° (East).
      required: true
      schema:
        maximum: 180
        minimum: -180
        type: number
        format: float
        example: -77.0513
    onpointId:
      name: onpointId
      in: path
      description: An OnPoint™ ID.
      required: true
      schema:
        type: integer
        example: 10725864
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: |
        API key to authorize requests. If you do not have a Weather Source API key [sign up for a free developer account](https://developer.weathersourceapis.com/account/sign-up/) to trial the data, or contact sales at [weathersource@pelmorex.com](mailto:weathersource@pelmorex.com) to explore the right subscription package for your business. You may use the evaluation API Key `C0W60UOFRML47ytbXk4xlLBfv` to access example locations found in this documentation.
      name: X-API-KEY
      in: header