DTN Endpoints API

openapi: 3.2.0
info:
  title: Dtn Endpoints API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Endpoints across 10 of this provider''s published API definitions: dtn-agency-bulletin-api-openapi.json, dtn-agency-bulletin-websocket-api-openapi.json, dtn-astronomical-api-openapi.json, dtn-climatology-api-openapi.json, dtn-marine-weather-api-openapi.json, dtn-precipitation-api-openapi.json, dtn-probabilistic-api-openapi.json, dtn-renewables-api-openapi.json, dtn-soil-api-openapi.json, dtn-weather-conditions-api-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://wxbulletin.api.dtn.com
- url: http://wxbulletin-ws.api.dtn.com
- url: http://agency-bulletin-ws.prd.wx.zones.dtn.com
- url: https://astronomical.api.dtn.com
- url: https://climatology.api.dtn.com
- url: https://weather.api.dtn.com
- url: https://precipitation.api.dtn.com
- url: https://probabilistic.api.dtn.com
- url: https://renewables.api.dtn.com
- url: https://soil.api.dtn.com
tags:
- name: Endpoints
  description: The the Agency Bulletin API (ABA) is designed around two major endpoints, each offering unique functionalities tailored to your diverse weather bulletin data needs. Whether you require forecast and historical data for a single location, data for multiple location/timestamp pairs, or the associated metadata, our API has got you covered.
paths:
  /v2/bulletins:
    get:
      tags:
      - Endpoints
      summary: Bulletins
      description: "```shell \nGET https://wxbulletin.api.dtn.com/v2/bulletins\n```\n\nThis endpoint returns the latest active weather bulletins from the requested national meteorological agency. \nIt is the primary source of information for real-time weather alerts and updates.\n\nUnderstanding and Utilizing Key Query Parameters:\n- **Country:** \nUse this parameter to access all active weather bulletins within a specific country. \nThis parameter accepts ISO 3166-1 alpha-2 codes.\nExample: country=US\n\n- **startTime:**\nThis parameter allows you to filter alerts sent from a specific date and time onward, \nreturning all subsequent alerts. It requires timestamps in ISO 8601 date-time format as specified in RFC 3339.\nExample: startTime=2022-11-25T00:00:00\n\n- **endTime:**\nUse this parameter to receive alerts up to a specific timestamp, \nfiltering out any alerts sent after this date and time. The expected format is ISO 8601 date-time as per RFC 3339.\nExample: endTime=2022-11-26T00:00:00\n\n- **excludeGeometry:**\nThis parameter is crucial and is set to false by default, meaning the response will include detailed geometry of the \npolygons corresponding to each active warning. This can be particularly useful for understanding the exact impacted \nareas or for visualizing warnings in GIS applications. However, be mindful that including this detailed information \nmight substantially increase the payload size when dealing with numerous active bulletins. \nIf you prefer to exclude the detailed geometry and reduce payload size, set this parameter to true.\n\nQuery Example: `https://wxbulletin.api.dtn.com/v2/bulletins?country=US&showTotal=true&agency=NWS&startTime=2023-09-25T12:45:00&endTime=2023-09-25T12:47:00`"
      operationId: get_bulletins_v2_bulletins_get
      parameters:
      - description: 'Specify the country code of the alerts request. This is a required parameter. The reference for acceptable values is ISO 3166 two-letter codes (alpha-2). example: US'
        required: false
        schema:
          type: string
          title: Country
          description: 'Specify the country code of the alerts request. This is a required parameter. The reference for acceptable values is ISO 3166 two-letter codes (alpha-2). example: US'
        name: country
        in: query
      - description: 'Specify the language the language to use in the text values of the alert. Values should follow RFC 3066. example: en-US'
        required: false
        schema:
          type: string
          title: Language
          description: 'Specify the language the language to use in the text values of the alert. Values should follow RFC 3066. example: en-US'
        name: language
        in: query
      - description: 'Specify the agency of the alert request. example: NWS'
        required: false
        schema:
          type: string
          title: Agency
          description: 'Specify the agency of the alert request. example: NWS'
        name: agency
        in: query
      - description: 'Specify the sender of the alerts request. example: w-nws.webmaster@noaa.gov'
        required: false
        schema:
          type: string
          title: Sender
          description: 'Specify the sender of the alerts request. example: w-nws.webmaster@noaa.gov'
        name: sender
        in: query
      - description: 'When specified, the API will return only alerts that match the specified event types. example: Flood Warning'
        required: false
        schema:
          items:
            type: string
          type: array
          title: Event
          description: 'When specified, the API will return only alerts that match the specified event types. example: Flood Warning'
        name: event
        in: query
      - description: 'Specify the date and time alerts are sent. When set, all alerts sent from this timestamp are returned. ISO8601 date-time format specified int RFC 3339. example: 2022-11-25T00:00:00'
        required: false
        schema:
          type: string
          format: date-time
          title: Starttime
          description: 'Specify the date and time alerts are sent. When set, all alerts sent from this timestamp are returned. ISO8601 date-time format specified int RFC 3339. example: 2022-11-25T00:00:00'
        name: startTime
        in: query
      - description: 'Specify the date and time alerts are sent. When set, all alerts sent until this timestamp are returned. ISO8601 date-time format specified int RFC 3339. example: 2022-11-26T00:00:00'
        required: false
        schema:
          type: string
          format: date-time
          title: Endtime
          description: 'Specify the date and time alerts are sent. When set, all alerts sent until this timestamp are returned. ISO8601 date-time format specified int RFC 3339. example: 2022-11-26T00:00:00'
        name: endTime
        in: query
      - description: Specify whether or not to include the geojson geometry for each alert.
        required: false
        schema:
          type: boolean
          title: Excludegeometry
          description: Specify whether or not to include the geojson geometry for each alert.
          default: false
        name: excludeGeometry
        in: query
      - description: Specify whether or not to include total number of alerts.
        required: false
        schema:
          type: boolean
          title: Showtotal
          description: Specify whether or not to include total number of alerts.
          default: false
        name: showTotal
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoJsonAlertResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - clientCredentials: []
    servers:
    - url: https://wxbulletin.api.dtn.com
  /v2/metadata:
    get:
      tags:
      - Endpoints
      summary: Metadata
      description: "```shell \nGET https://wxbulletin.api.dtn.com/v2/metadata\n```\nThis endpoint provides metadata from each national meteorological agency, \ndetailing what events are published and in which languages, allowing developers to understand the range and scope of \navailable bulletins.\n\nUnderstanding and Utilizing Key Query Parameters:\n\n- Access this endpoint to retrieve a comprehensive list of all available meteorological agencies, \nthe events they publish, and the languages they support. As we continuously integrate support for new agencies into \nthis API, this endpoint serves as an excellent resource to stay updated on the most recent agencies and \ntheir corresponding published events.\n- event: Use this parameter to pinpoint a particular event. It also aids in identifying which agencies \nbroadcast that specific event type.\n\nQuery Example: `https://wxbulletin.api.dtn.com/v2/metadata?country=US&event=Flash`"
      operationId: get_metadata_v2_metadata_get
      parameters:
      - description: 'Specify the country of the event type example: US'
        required: false
        schema:
          items:
            type: string
          type: array
          title: Country
          description: 'Specify the country of the event type example: US'
        name: country
        in: query
      - description: 'Specify the agency of the event type example: NWS'
        required: false
        schema:
          items:
            type: string
          type: array
          title: Agency
          description: 'Specify the agency of the event type example: NWS'
        name: agency
        in: query
      - description: 'Specify the language of the event types follow RFC 3066. example: en-US'
        required: false
        schema:
          items:
            type: string
          type: array
          title: Language
          description: 'Specify the language of the event types follow RFC 3066. example: en-US'
        name: language
        in: query
      - description: 'When specified, the API allows filtering based on specific event types. This can be used to narrow down search result. example: event=flood would return events like Flash Flood Watch, Flood Warning, Flash Flood Statement, Severe Flood Warning'
        required: false
        schema:
          items:
            type: string
          type: array
          title: Event
          description: 'When specified, the API allows filtering based on specific event types. This can be used to narrow down search result. example: event=flood would return events like Flash Flood Watch, Flood Warning, Flash Flood Statement, Severe Flood Warning'
        name: event
        in: query
      - description: 'When specified, the API allows filtering based on specific dtnEvent. This can be used to narrow down search result. example: dtnEvent=Wind would return events like Brisk Wind Advisory, Extreme Wind Warning, Lake Wind Advisory, High Wind Warning'
        required: false
        schema:
          items:
            type: string
          type: array
          title: Dtnevent
          description: 'When specified, the API allows filtering based on specific dtnEvent. This can be used to narrow down search result. example: dtnEvent=Wind would return events like Brisk Wind Advisory, Extreme Wind Warning, Lake Wind Advisory, High Wind Warning'
        name: dtnEvent
        in: query
      - description: 'When specified, the API allows filtering based on specific dtnEventCode. This can be used to narrow down search result. example: dtnEventCode=1 would return events under Snow likeLake Effect Snow Watch, Lake Effect Snow Warning, Lake Effect Snow Advisory, Snow Squall Warning'
        required: false
        schema:
          items:
            type: string
          type: array
          title: Dtneventcode
          description: 'When specified, the API allows filtering based on specific dtnEventCode. This can be used to narrow down search result. example: dtnEventCode=1 would return events under Snow likeLake Effect Snow Watch, Lake Effect Snow Warning, Lake Effect Snow Advisory, Snow Squall Warning'
        name: dtnEventCode
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - clientCredentials: []
    servers:
    - url: https://wxbulletin.api.dtn.com
  /v2/metadata/dtn:
    get:
      tags:
      - Endpoints
      summary: Metadata/dtn
      description: "```shell \nGET https://wxbulletin.api.dtn.com/v2/metadata/dtn\n```\nThis endpoint provides metadata of dtn events.\n\nUnderstanding and Utilizing Key Query Parameters:\n\n- Access this endpoint to retrieve a comprehensive list of all available dtn events. \n- dtnEvent: Use this parameter to pinpoint a particular dtn event.\n\nQuery Example: `https://wxbulletin.api.dtn.com/v2/metadata/dtn?dtnEvent=Snow`"
      operationId: get_metadata_dtn_v2_metadata_dtn_get
      parameters:
      - description: 'Specify the event code of dtn event example: NWS'
        required: false
        schema:
          items:
            type: string
          type: array
          title: Dtneventcode
          description: 'Specify the event code of dtn event example: NWS'
        name: dtnEventCode
        in: query
      - description: 'Specify the event name of dtn event example: Low Temperature'
        required: false
        schema:
          items:
            type: string
          type: array
          title: Dtnevent
          description: 'Specify the event name of dtn event example: Low Temperature'
        name: dtnEvent
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataDTNResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - clientCredentials: []
    servers:
    - url: https://wxbulletin.api.dtn.com
  /v1:
    get:
      tags:
      - Endpoints
      summary: Stream
      description: "\n```shell \nGET wss://wxbulletin-ws.api.dtn.com/v1/\n```\n\nThis endpoint returns the latest active weather bulletins from the requested national meteorological agency. \nIt is the primary source of information for real-time weather alerts and updates.\n\nUnderstanding and Utilizing Key Query Parameters:\n- **country:** \nUse this parameter to access all active weather bulletins within a specific country. \nThis parameter accepts ISO 3166-1 alpha-2 codes. This parameter cannot be used with the `lat/lon/radius` or the `bbox` parameters.<br>\nExample: `country=US`\n\n- **lat**, **lon**:\nUse these parameters to access all active weather bulletins that intersect a point location in the map. When used with,\nthe `radius` parameter, the active bulletins intersecting a circle with the lat/lon at the center and the radius in\nkilometers will be returned. This combination cannot be used with the `country` or the `bbox` parameters.<br>\nExample: `lat=52.52&lon=13.40`, `lat=52.52&lon=13.40&radius=50` \n\n- **bbox**:\nUse this parameter to access all active weather bulletins that intersect a bounding box with the format `minLon,minLat,maxLon,maxLat`.\nThis combination cannot be used with the `country` or the `lat/lon/radius` parameters.<br>\nExample: `bbox=30.1,45.1,30.5,45.5`, `bbox=13.10,52.66,13.77,52.37`\n\n- **excludeGeometry:**\nThis parameter is crucial and is set to false by default, meaning the response will include detailed geometry of the \npolygons corresponding to each active warning. This can be particularly useful for understanding the exact impacted \nareas or for visualizing warnings in GIS applications. However, be mindful that including this detailed information \nmight substantially increase the payload size when dealing with numerous active bulletins. \nIf you prefer to exclude the detailed geometry and reduce payload size, set this parameter to true.<br>\nExample: `excludeGeometry=True`\n\nQuery Examples: <br>\n- `wss://wxbulletin-ws.api.dtn.com/v1?country=US&excludeGeometry=true` <br>\n- `wss://wxbulletin-ws.api.dtn.com/v1?lon=13.4&lat=52.52&radius=5.5` <br>\n- `wss://wxbulletin-ws.api.dtn.com/v1?bbox=13.10,52.66,13.77,52.37` <br>\n"
      operationId: get_v1_stream
      security:
      - clientCredentials: []
      parameters:
      - name: country
        in: query
        required: true
        schema:
          title: country
          description: 'Specify the country code of the alerts request. This is a required parameter. The reference for acceptable values is ISO 3166 two-letter codes (alpha-2). '
          maxLength: 2
          minLength: 2
          pattern: ^[a-zA-Z]*$
          examples:
          - US
          - DE
          - CA
          - AU
          - FR
          required: true
          type: string
        description: 'Specify the country code of the alerts request. This is a required parameter. The reference for acceptable values is ISO 3166 two-letter codes (alpha-2). '
      - name: lat
        in: query
        required: false
        schema:
          title: latitude
          description: The latitude in decimal degrees. When specified, it must be used together with the `lon` parameter. This parameter can also be used with the `radius` parameter. This parameter cannot be used with the `country` or the `bbox` parameters.
          minimum: -90
          maximum: 90
          examples:
          - 35.67
          type: number
        description: The latitude in decimal degrees. When specified, it must be used together with the `lon` parameter. This parameter can also be used with the `radius` parameter. This parameter cannot be used with the `country` or the `bbox` parameters.
      - name: lon
        in: query
        required: false
        schema:
          title: longitude
          description: The longitude in decimal degrees. When specified, it must be used together with the `lat` parameter. This parameter can also be used with the `radius` parameter. This parameter cannot be used with the `country` or the `bbox` parameters.
          minimum: -180
          maximum: 180
          examples:
          - 139.65
          type: number
        description: The longitude in decimal degrees. When specified, it must be used together with the `lat` parameter. This parameter can also be used with the `radius` parameter. This parameter cannot be used with the `country` or the `bbox` parameters.
      - name: radius
        in: query
        required: false
        schema:
          title: radius
          description: The radius in km. When specified, alerts intersecting the circle with the POINT(`lon`,`lat`) as the center will be returned.This parameter cannot be used with the `country` or the `bbox` parameters.
          exclusiveMinimum: 0
          maximum: 3000
          examples:
          - 10
          - 15.5
          - 30
          - 50.25
          type: number
        description: The radius in km. When specified, alerts intersecting the circle with the POINT(`lon`,`lat`) as the center will be returned.This parameter cannot be used with the `country` or the `bbox` parameters.
      - name: bbox
        in: query
        required: false
        schema:
          title: bbox
          description: The bounding box coordinates in the format `minLon,minLat,maxLon,maxLat`. This parameter cannot be used with the `country` or the `lat/lon/radius` parameters.
          examples:
          - 30.1,45.1,30.5,45.5
          - 13.10,52.66,13.77,52.37
          type: array
          items:
            type: number
        description: The bounding box coordinates in the format `minLon,minLat,maxLon,maxLat`. This parameter cannot be used with the `country` or the `lat/lon/radius` parameters.
      - name: language
        in: query
        required: false
        schema:
          title: language
          description: 'Specify the language to use in the text values of the alert. Values should follow RFC 3066. '
          maxLength: 5
          minLength: 5
          pattern: ^[a-zA-Z]{2}-[a-zA-Z]{2}$
          examples:
          - en-US
          - en-GB
          - de-DE
          - fr-FR
          - en-AU
          - en-CA
          type: string
        description: 'Specify the language to use in the text values of the alert. Values should follow RFC 3066. '
      - name: agency
        in: query
        required: false
        schema:
          title: agency
          description: 'Specify the agency of the alert request. '
          maxLength: 20
          minLength: 3
          pattern: ^[a-zA-Z]*$
          examples:
          - NWS
          - DWD
          - BOM
          - UKMO
          - METEOALARM
          - ENVCA
          - UKENVA
          type: string
        description: 'Specify the agency of the alert request. '
      - name: event
        in: query
        required: false
        schema:
          title: event
          description: 'When specified, the API will return only alerts that match the specified event types. '
          examples:
          - Flood Warning
          - Severe Thunderstorm Warning, Gale Warning
          type: array
          items:
            type: string
        description: 'When specified, the API will return only alerts that match the specified event types. '
      - name: excludeGeometry
        in: query
        required: false
        schema:
          title: excludeGeometry
          description: Specify whether or not to include the root geojson geometry for each alert.
          default: false
          examples:
          - true
          - false
          type: boolean
        description: Specify whether or not to include the root geojson geometry for each alert.
      responses:
        '101':
          description: Successful Response
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    title: id
                    description: The identifier of the alert message
                  agency:
                    type: string
                    title: agency
                    description: Agency issuing the alert
                  country:
                    type: string
                    title: country
                    description: Country code of the alert
                  type:
                    type: string
                    title: type
                    description: Type of the GeoJSON object
                    default: Feature
                  geometry:
                    anyOf:
                    - type: object
                    title: Geometry
                    description: Geometry of the alert area
                  properties:
                    properties:
                      identifier:
                        type: string
                        title: Identifier
                        description: The identifier of the alert message
                      sender:
                        type: string
                        title: Sender
                        description: The identifier of the sender of the alert message
                      sent:
                        type: string
                        format: date-time
                        title: Sent
                        description: The time and date of the origination of the alert message
                      status:
                        type: string
                        title: Status
                        description: The code denoting the appropriate handling of the alert message
                      msgType:
                        type: string
                        title: Msgtype
                        description: The code denoting the nature of the alert message
                      scope:
                        type: string
                        title: Scope
                        description: The code denoting the intended distribution of the alert message
                      code:
                        type: string
                        title: Code
                        description: The code denoting the special handling of the alert message
                      source:
                        type: string
                        title: Source
                        description: The text identifying the source of the alert message
                      updated:
                        type: string
                        format: date-time
                        title: Updated
                        description: Date when the alert was last updated
                      restriction:
                        type: string
                        title: Restriction
                        description: The text describing the rule for limiting distribution of the restricted alert message
                      addresses:
                        type: string
                        title: Addresses
                        description: The group listing of intended recipients of the alert message
                      note:
                        type: string
                        title: Note
                        description: The text describing the purpose or significance of the alert message
                      references:
                        type: string
                        title: References
                        description: The group listing identifying earlier message(s) referenced by alert message
                      info:
                        items:
                          properties:
                            event:
                              type: string
                              title: Event
                              description: The text denoting the type of the subject event of the alert message
                            eventCode:
                              items:
                                properties:
                                  valueName:
                                    type: string
                                    title: Valuename
                                    description: Value name
                                  value:
                                    type: string
                                    title: Value
                                    description: Actual value
                                type: object
                                required:
                                - valueName
                                - value
                                title: EventCode
                              type: array
                              title: Eventcode
                              description: A system- specific code identifying the event type of the alert message
                            category:
                              type: string
                              title: Category
                              description: The code denoting the category of the subject event of the alert message
                            language:
                              type: string
                              title: Language
                              description: The code denoting the language of the info sub- element of the alert message
                            urgency:
                              type: string
                              title: Urgency
                              description: The code denoting the urgency of the subject event of the alert message
                            severity:
                              type: string
                              title: Severity
                              description: The code denoting the severity of the subject event of the alert message
                            certainty:
                              type: string
                              title: Certainty
                              description: The code denoting the certainty of the subject event of the alert message
                            responseType:
                              type: string
                              title: Responsetype
                              description: The code denoting the type of action recommended for the target audience
                            effective:
                              type: string
                              format: date-time
                              title: Effective
                              description: The effective time of the information of the alert message
                            onset:
                              type: string
                              format: date-time
                              title: Onset
                              description: The expected time of the beginning of the subject event of the alert message
                            expires:
                              type: string
                              format: date-time
                              title: Expires
                              description: The expiry time of the information of the alert message
                            audience:
                              type: string
                              title: Audience
                              description: The text describing the intended audience of the alert message
                            senderName:
                              type: string
                              title: Sendername
                              description: The text naming the originator of the alert message
                            headline:
                              type: string
                              title: Headline
                              description: The text headline of the alert message
                            description:
                              type: string
                              title: Description
                              description: The text describing the subject event of the alert message
                            instruction:
                              type: string
                              title: Instruction
                              description: The text describing the recommended action to be taken by recipients of the alert message
                            web:
                              type: string
                              title: Web
                              description: The identifier of the hyperlink associating additional information with the alert message
                            contact:
                              type: string
                              title: Contact
                              description: The text describing the contact for follow-up and confirmation of the alert message
                            parameters:
                              items:
                                properties:
                                  valueName:
                                    type: string
                                    title: Valuename
                                    description: Value name
                                  value:
                                    type: string
                                    title: Value
                                    description: Actual value
                                type: object
                                required:
                                - valueName
                                - value
                                title: Parameters
                              type: array
                              title: Parameters
                              description: A system- specific additional parameter associated with the alert message
                            area:
                              items:
                                properties:
                                  areaDesc:
                                    type: string
                                    title: Areadesc
                                    description: The text describing the affected area of the alert message
                                  polygon:
                                    type: object
                                    title: Polygon
                                    description: The paired values of points defining a polygon that delineates the affected area of the alert message
                                  circle:
                                    type: string
                     

# --- truncated at 32 KB (833 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dtn/refs/heads/main/openapi/dtn-endpoints-api-openapi.yml