National Weather Service Points API

openapi: 3.1.2
info:
  title: weather.gov Alerts Points API
  description: weather.gov API
  version: 3.8.1
servers:
- url: https://api.weather.gov
  description: Production server
security:
- userAgent: []
- apiKeyAuth: []
tags:
- name: Points
paths:
  /points/{latitude},{longitude}:
    parameters:
    - $ref: '#/components/parameters/Latitude'
    - $ref: '#/components/parameters/Longitude'
    get:
      description: Returns metadata about a given latitude/longitude point
      operationId: point
      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/geo+json:
              schema:
                $ref: '#/components/schemas/PointGeoJson'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/PointJsonLd'
        default:
          $ref: '#/components/responses/Error'
      parameters: []
      tags:
      - Points
  /points/{latitude},{longitude}/radio:
    parameters:
    - $ref: '#/components/parameters/Latitude'
    - $ref: '#/components/parameters/Longitude'
    get:
      description: Returns NOAA Weather Radio broadcast script for a latitude/longitude point
      externalDocs:
        url: https://www.w3.org/TR/speech-synthesis/
      operationId: point_radio
      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/ssml+xml:
              schema: {}
        default:
          $ref: '#/components/responses/Error'
      parameters: []
      tags:
      - Points
  /points/{latitude},{longitude}/stations:
    parameters:
    - $ref: '#/components/parameters/Latitude'
    - $ref: '#/components/parameters/Longitude'
    get:
      description: Returns a list of observation stations for a given point
      operationId: point_stations
      responses:
        '301':
          description: redirect to gridpoint stations
        default:
          $ref: '#/components/responses/Error'
      deprecated: true
      parameters: []
      tags:
      - Points
components:
  parameters:
    Latitude:
      name: latitude
      in: path
      description: Latitude
      required: true
      schema:
        multipleOf: 0.0001
        maximum: 90
        minimum: -90
        type: number
    Longitude:
      name: longitude
      in: path
      description: Longitude
      required: true
      schema:
        multipleOf: 0.0001
        maximum: 180
        minimum: -180
        type: number
  schemas:
    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.
    Point:
      type: object
      properties:
        '@context':
          $ref: '#/components/schemas/JsonLdContext'
        geometry:
          $ref: '#/components/schemas/GeometryString'
        '@id':
          type: string
          format: uri
        '@type':
          enum:
          - wx:Point
          type: string
        cwa:
          $ref: '#/components/schemas/NWSForecastOfficeId'
        type:
          enum:
          - land
          - marine
          type: string
          description: Whether the specific point is on land or marine
        forecastOffice:
          type: string
          format: uri
        gridId:
          $ref: '#/components/schemas/NWSForecastOfficeId'
        gridX:
          minimum: 0
          type: integer
        gridY:
          minimum: 0
          type: integer
        forecast:
          type: string
          format: uri
        forecastHourly:
          type: string
          format: uri
        forecastGridData:
          type: string
          format: uri
        observationStations:
          type: string
          format: uri
        relativeLocation:
          oneOf:
          - $ref: '#/components/schemas/RelativeLocationGeoJson'
          - $ref: '#/components/schemas/RelativeLocationJsonLd'
        forecastZone:
          type: string
          format: uri
        county:
          type: string
          format: uri
        fireWeatherZone:
          type: string
          format: uri
        timeZone:
          type: string
        radarStation:
          type: string
        astronomicalData:
          $ref: '#/components/schemas/AstronomicalData'
        nwr:
          type: object
          properties:
            transmitter:
              type:
              - string
              - 'null'
              description: Transmitter callsign
            sameCode:
              type: string
              description: The SAME code of this point's county
            areaBroadcast:
              type:
              - string
              - 'null'
              description: A link to the area NWR broadcast from this transmitter
              format: uri
            pointBroadcast:
              type:
              - string
              - 'null'
              description: A link to the local NWR broadcast for this point
              format: uri
          description: NOAA Weather Radio metadata for this point
    JsonLdContext:
      anyOf:
      - type: array
        items: {}
      - type: object
    GeometryString:
      type:
      - string
      - 'null'
      description: A geometry represented in Well-Known Text (WKT) format.
      format: wkt
    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
    GeoJsonCoordinate:
      minItems: 2
      type: array
      items:
        type: number
      description: A GeoJSON coordinate. 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.
    NWSForecastOfficeId:
      enum:
      - AKQ
      - ALY
      - BGM
      - BOX
      - BTV
      - BUF
      - CAE
      - CAR
      - CHS
      - CLE
      - CTP
      - GSP
      - GYX
      - ILM
      - ILN
      - LWX
      - MHX
      - OKX
      - PBZ
      - PHI
      - RAH
      - RLX
      - RNK
      - ABQ
      - AMA
      - BMX
      - BRO
      - CRP
      - EPZ
      - EWX
      - FFC
      - FWD
      - HGX
      - HUN
      - JAN
      - JAX
      - KEY
      - LCH
      - LIX
      - LUB
      - LZK
      - MAF
      - MEG
      - MFL
      - MLB
      - MOB
      - MRX
      - OHX
      - OUN
      - SHV
      - SJT
      - SJU
      - TAE
      - TBW
      - TSA
      - ABR
      - APX
      - ARX
      - BIS
      - BOU
      - CYS
      - DDC
      - DLH
      - DMX
      - DTX
      - DVN
      - EAX
      - FGF
      - FSD
      - GID
      - GJT
      - GLD
      - GRB
      - GRR
      - ICT
      - ILX
      - IND
      - IWX
      - JKL
      - LBF
      - LMK
      - LOT
      - LSX
      - MKX
      - MPX
      - MQT
      - OAX
      - PAH
      - PUB
      - RIW
      - SGF
      - TOP
      - UNR
      - BOI
      - BYZ
      - EKA
      - FGZ
      - GGW
      - HNX
      - LKN
      - LOX
      - MFR
      - MSO
      - MTR
      - OTX
      - PDT
      - PIH
      - PQR
      - PSR
      - REV
      - SEW
      - SGX
      - SLC
      - STO
      - TFX
      - TWC
      - VEF
      - AER
      - AFC
      - AFG
      - AJK
      - ALU
      - GUM
      - HPA
      - HFO
      - PPG
      - PQE
      - PQW
      - STU
      - NH1
      - NH2
      - ONA
      - ONP
      type: string
      description: Three-letter identifier for a NWS office.
    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
    UnitOfMeasure:
      pattern: ^((wmo|uc|wmoUnit|nwsUnit):)?.*$
      type: string
      description: 'A string denoting a unit of measure, expressed in the format "{unit}" or "{namespace}:{unit}".

        Units with the namespace "wmo" or "wmoUnit" are defined in the World Meteorological Organization Codes Registry at http://codes.wmo.int/common/unit and should be canonically resolvable to http://codes.wmo.int/common/unit/{unit}.

        Units with the namespace "nwsUnit" are currently custom and do not align to any standard.

        Units with no namespace or the namespace "uc" are compliant with the Unified Code for Units of Measure syntax defined at https://unitsofmeasure.org/. This also aligns with recent versions of the Geographic Markup Language (GML) standard, the IWXXM standard, and OGC Observations and Measurements v2.0 (ISO/DIS 19156).

        Namespaced units are considered deprecated. We will be aligning API to use the same standards as GML/IWXXM in the future.

        '
    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.
    RelativeLocation:
      type: object
      properties:
        city:
          type: string
        state:
          type: string
        distance:
          $ref: '#/components/schemas/QuantitativeValue'
        bearing:
          $ref: '#/components/schemas/QuantitativeValue'
    RelativeLocationJsonLd:
      allOf:
      - $ref: '#/components/schemas/RelativeLocation'
      - required:
        - geometry
        type: object
        properties:
          geometry:
            $ref: '#/components/schemas/GeometryString'
    QuantitativeValue:
      type: object
      properties:
        value:
          type:
          - number
          - 'null'
          description: A measured value
        maxValue:
          type: number
          description: The maximum value of a range of measured values
        minValue:
          type: number
          description: The minimum value of a range of measured values
        unitCode:
          $ref: '#/components/schemas/UnitOfMeasure'
        qualityControl:
          enum:
          - Z
          - C
          - S
          - V
          - X
          - Q
          - G
          - B
          - T
          type: string
          description: 'For values in observation records, the quality control flag from the MADIS system. The definitions of these flags can be found at https://madis.ncep.noaa.gov/madis_sfc_qc_notes.shtml

            '
      description: 'A structured value representing a measurement and its unit of measure. This object is a slightly modified version of the schema.org definition at https://schema.org/QuantitativeValue

        '
      additionalProperties: false
    RelativeLocationGeoJson:
      allOf:
      - $ref: '#/components/schemas/GeoJsonFeature'
      - type: object
        properties:
          properties:
            $ref: '#/components/schemas/RelativeLocation'
    PointJsonLd:
      allOf:
      - $ref: '#/components/schemas/Point'
      - required:
        - '@context'
        - geometry
        type: object
        properties:
          '@context':
            $ref: '#/components/schemas/JsonLdContext'
          geometry:
            $ref: '#/components/schemas/GeometryString'
    AstronomicalData:
      type: object
      properties:
        sunrise:
          type: string
          description: 'The timestamp of sunrise, defined as when the sun angle is 90°35'' from vertical.

            '
          format: date-time
        sunset:
          type: string
          description: 'The timestamp of sunset, defined as when the sun angle is 90°35'' from vertical.

            '
          format: date-time
        transit:
          type: string
          description: 'The timestamp when the sun reaches its zenith.

            '
          format: date-time
        civilTwilightBegin:
          type: string
          description: 'The timestamp of the onset of civil twilight, defined as when the sun angle is 96° from vertical. This is the beginning of civil dawn and lasts until sunrise.

            '
          format: date-time
        civilTwilightEnd:
          type: string
          description: 'The timestamp of the end of civil twilight, defined as when the sun angle is 96° from vertical. This is the end of civil dusk, which begins at sunset.

            '
          format: date-time
        nauticalTwilightBegin:
          type: string
          description: 'The timestamp of the onset of nautical twilight, defined as when the sun angle is 102° from vertical. This is the beginning of nautical dawn and lasts until the civil dawn.

            '
          format: date-time
        nauticalTwilightEnd:
          type: string
          description: 'The timestamp of the end of nautical twilight, defined as when the sun angle is 102° from vertical. This is the end of nautical dusk, which begins at the end of civil twilight.

            '
          format: date-time
        astronomicalTwilightBegin:
          type: string
          description: 'The timestamp of the onset of astronomical twilight, defined as when the sun angle is 108° from vertical. This is the beginning of astronomical dawn and lasts until the nautical dawn.

            '
          format: date-time
        astronomicalTwilightEnd:
          type: string
          description: 'The timestamp of the end of astronomical twilight, defined as when the sun angle is 108° from vertical. This is the end of astronomical dusk, which begins at the end of nautical twilight.

            '
          format: date-time
      description: 'An object representing sunrise, sunset, and twilight information for a location.

        '
    PointGeoJson:
      allOf:
      - $ref: '#/components/schemas/GeoJsonFeature'
      - type: object
        properties:
          properties:
            $ref: '#/components/schemas/Point'
    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.
  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