National Weather Service Products API

openapi: 3.1.2
info:
  title: weather.gov Alerts Products API
  description: weather.gov API
  version: 3.8.1
servers:
- url: https://api.weather.gov
  description: Production server
security:
- userAgent: []
- apiKeyAuth: []
tags:
- name: Products
paths:
  /products:
    get:
      description: Returns a list of text products
      operationId: products_query
      parameters:
      - name: location
        in: query
        description: Location id
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: start
        in: query
        description: Start time
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        description: End time
        schema:
          type: string
          format: date-time
      - name: office
        in: query
        description: Issuing office
        style: form
        explode: false
        schema:
          type: array
          items:
            pattern: ^[A-Z]{4}$
            type: string
      - name: wmoid
        in: query
        description: WMO id code
        style: form
        explode: false
        schema:
          type: array
          items:
            pattern: ^[A-Z]{4}\d{2}$
            type: string
      - name: type
        in: query
        description: Product code
        style: form
        explode: false
        schema:
          type: array
          items:
            pattern: ^\w{3}$
            type: string
      - name: limit
        in: query
        description: Limit
        schema:
          maximum: 500
          minimum: 1
          type: integer
      responses:
        '200':
          description: success
          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:
                $ref: '#/components/schemas/TextProductCollection'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Products
  /products/locations:
    get:
      description: Returns a list of valid text product issuance locations
      operationId: product_locations
      responses:
        '200':
          description: success
          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:
                $ref: '#/components/schemas/TextProductLocationCollection'
        default:
          $ref: '#/components/responses/Error'
      parameters: []
      tags:
      - Products
  /products/types:
    get:
      description: Returns a list of valid text product types and codes
      operationId: product_types
      responses:
        '200':
          description: success
          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:
                $ref: '#/components/schemas/TextProductTypeCollection'
        default:
          $ref: '#/components/responses/Error'
      parameters: []
      tags:
      - Products
  /products/{productId}:
    parameters:
    - name: productId
      in: path
      description: .
      required: true
      schema:
        type: string
    get:
      description: Returns a specific text product
      operationId: product
      responses:
        '200':
          description: success
          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:
                $ref: '#/components/schemas/TextProduct'
        default:
          $ref: '#/components/responses/Error'
      parameters: []
      tags:
      - Products
  /products/types/{typeId}:
    parameters:
    - name: typeId
      in: path
      description: .
      required: true
      schema:
        type: string
    get:
      description: Returns a list of text products of a given type
      operationId: products_type
      responses:
        '200':
          description: success
          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:
                $ref: '#/components/schemas/TextProductCollection'
        default:
          $ref: '#/components/responses/Error'
      parameters: []
      tags:
      - Products
  /products/types/{typeId}/locations:
    parameters:
    - name: typeId
      in: path
      description: .
      required: true
      schema:
        type: string
    get:
      description: Returns a list of valid text product issuance locations for a given product type
      operationId: products_type_locations
      responses:
        '200':
          description: success
          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:
                $ref: '#/components/schemas/TextProductLocationCollection'
        default:
          $ref: '#/components/responses/Error'
      parameters: []
      tags:
      - Products
  /products/locations/{locationId}/types:
    parameters:
    - name: locationId
      in: path
      description: .
      required: true
      schema:
        type: string
    get:
      description: Returns a list of valid text product types for a given issuance location
      operationId: location_products
      responses:
        '200':
          description: success
          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:
                $ref: '#/components/schemas/TextProductTypeCollection'
        default:
          $ref: '#/components/responses/Error'
      parameters: []
      tags:
      - Products
  /products/types/{typeId}/locations/{locationId}:
    parameters:
    - name: typeId
      in: path
      description: .
      required: true
      schema:
        type: string
    - name: locationId
      in: path
      description: .
      required: true
      schema:
        type: string
    get:
      description: Returns a list of text products of a given type for a given issuance location
      operationId: products_type_location
      responses:
        '200':
          description: success
          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:
                $ref: '#/components/schemas/TextProductCollection'
        default:
          $ref: '#/components/responses/Error'
      parameters: []
      tags:
      - Products
  /products/types/{typeId}/locations/{locationId}/latest:
    parameters:
    - name: typeId
      in: path
      description: .
      required: true
      schema:
        type: string
    - name: locationId
      in: path
      description: .
      required: true
      schema:
        type: string
    get:
      description: Returns latest text products of a given type for a given issuance location with product text
      operationId: latest_product_type_location
      responses:
        '200':
          description: success
          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:
                $ref: '#/components/schemas/TextProduct'
        default:
          $ref: '#/components/responses/Error'
      parameters: []
      tags:
      - Products
components:
  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
    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
    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
  schemas:
    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
    TextProductLocationCollection:
      type: object
      properties:
        '@context':
          $ref: '#/components/schemas/JsonLdContext'
        locations:
          type: object
          additionalProperties:
            type:
            - string
            - 'null'
      additionalProperties: false
    TextProduct:
      type: object
      properties:
        '@context':
          $ref: '#/components/schemas/JsonLdContext'
        '@id':
          type: string
          format: uri
        id:
          type: string
        wmoCollectiveId:
          type: string
        issuingOffice:
          type: string
        issuanceTime:
          type: string
          format: date-time
        productCode:
          type: string
        productName:
          type: string
        productText:
          type: string
      additionalProperties: false
    JsonLdContext:
      anyOf:
      - type: array
        items: {}
      - type: object
    TextProductTypeCollection:
      type: object
      properties:
        '@context':
          $ref: '#/components/schemas/JsonLdContext'
        '@graph':
          type: array
          items:
            required:
            - productCode
            - productName
            type: object
            properties:
              productCode:
                type: string
              productName:
                type: string
            additionalProperties: false
      additionalProperties: false
    TextProductCollection:
      type: object
      properties:
        '@context':
          $ref: '#/components/schemas/JsonLdContext'
        '@graph':
          type: array
          items:
            $ref: '#/components/schemas/TextProduct'
      additionalProperties: false
  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