{"openapi":"3.1.0","info":{"title":"Agency Bulletin WebSocket API","description":"# Introduction \n \nWelcome to the DTN Agency Bulletin WebSocket API documentation. \n\n\nThe ABA WebSocket is designed to provide developers with a seamless and convenient way to access the latest weather bulletins \npublished by the national meteorological agencies across the globe (e.g. NWS, UKMO, BoM) all in a standardized and \neasily interpretable GeoJSON format. By unifying the global weather bulletins data into one standardized API, \nwe aim to simplify the process of working with such weather alerts, eliminating the need to understand \nmultiple systems or formats. \n\n\n**Key Features**\n\n* Near real-time delivery using secure WebSocket protocol (wss://) \n* Unified access to latest weather bulletins from national meteorological agencies worldwide.\n* Standardized GeoJSON format for all the weather bulletins, eliminating the need to grapple with various \ndata formats and data pipelines, facilitating easy data visualization and integration with mapping and GIS solutions. \n* Exact geometries of affected areas' polygons included in the response, facilitating precise and granular \nmapping of weather bulletins.\n* Inclusion of a Common Alerting Protocol (CAP) section in our GeoJSON response, preserving the original CAP data \nwhen issued by a national agency.\n\n**Applications**\n\nThis API caters to a wide range of users and applications, including:\n\n* Emergency alert systems\n* Software developers building weather applications\n* Travel planning websites\n* Climate research projects \n\n\nThis interactive documentation will get you up to speed on setting up requests, understanding responses, \nand leveraging the DTN Weather API for your needs.\n\n\n# Getting Started\n## Obtaining Credentials \nTo start making requests, you will first need your API credentials that includes your client ID and client secret. \nPlease contact an account manager or the [DTN sales team](https://www.dtn.com/contact-us/) to obtain these. \nThen, review the `Authentication` section to learn how to request an API access token. Do not share or use others' \nAPI credentials, since doing so may compromise information security.\n\n## Making requests\nStarting off your journey with the the Agency Bulletin API Websocket couldn't be easier. \nWe've provided a variety of options to suit your needs and comfort level:\nInteractive Documentation: Our interactive documentation is a great starting point. \nSimply navigate to the \"Authentication\" section, insert your credentials, and you'll obtain an access token behind \nthe scenes. Then, explore the API endpoints described in the Endpoints section.\n\n**a) Interactive Documentation:** Our interactive documentation is a great starting point. Simply navigate to \nthe `Authentication` section, insert your credentials, and you'll obtain an access token behind the scenes. \nThen, explore the API endpoints described in the `Endpoints` section.\n\n**b) Writing Code:** Ready to start coding? Try the Python example below, \nreplacing `client_id` and `client_secret` with proper credentials. \nThis creates a threaded websocket client that listens to new messages on the endpoint.\n\n\n\n\n\n```python\n#--- Initialize imports ---\nimport requests\nimport websocket\nimport json\nimport threading\nfrom datetime import datetime\n\n\n# Create a class to handle the WebSocket connection\nclass WSClient:\n    def __init__(self, url):\n        self.url = url\n        self.ws = None\n        self.messages = []\n        self.connected = False\n        \n    def on_message(self, ws, message):\n        \"\"\"Called when a message is received\"\"\"\n        try:\n            # Try to parse as JSON\n            data = json.loads(message)\n            print(f\"{datetime.now()}: {data}\")\n        except Exception as e:\n            print(f\"Error on {message}: {e}\")\n    \n    def on_error(self, ws, error):\n        \"\"\"Called when an error occurs\"\"\"\n        print(f\"Error: {error}\")\n    \n    def on_close(self, ws, close_status_code, close_msg):\n        \"\"\"Called when connection is closed\"\"\"\n        self.connected = False\n        print(f\"{datetime.now()}: Connection closed\")\n    \n    def on_open(self, ws):\n        \"\"\"Called when connection is established\"\"\"\n        self.connected = True\n        print(f\"{datetime.now()}: Connection opened\")\n    \n    def connect(self):\n        \"\"\"Establish WebSocket connection\"\"\"\n        self.ws = websocket.WebSocketApp(self.url,\n                                        on_open=self.on_open,\n                                        on_message=self.on_message,\n                                        on_error=self.on_error,\n                                        on_close=self.on_close)\n        \n        # Start WebSocket connection in a separate thread\n        self.thread = threading.Thread(target=self.ws.run_forever)\n        self.thread.daemon = True\n        self.thread.start()\n      \n    def close(self):\n        \"\"\"Close the WebSocket connection\"\"\"\n        if self.ws:\n            self.ws.close()\n\n\n# --- Obtain an API access token ---\nauth_url = 'https://api.auth.dtn.com/v1/tokens/authorize'\nbody = {\n    'grant_type': 'client_credentials',\n    'client_id': '...insert your client id here...',\n    'client_secret': '...insert your client secret here...',\n    'audience': 'https://weather.api.dtn.com'\n}\n\nresponse = requests.post(auth_url, json=body)\naccess_token = response.json()['data']['access_token']\n\n# Initialize the websocket endpoint and connection parameters\napi_base_url = 'wss://wxbulletin-ws.api.dtn.com/v1?'\nquery_parameters = '&'.join([\n    'lon=13.39',\n    'lat=52.52',\n    'radius=5.0',  # in km\n])\n\nendpoint = api_base_url + query_parameters + '&token=' + access_token\n\n\n# Initialize the WebSocket client\nclient = WSClient(endpoint)\nclient.connect()\n```","version":"1.0.0","x-logo":{"url":"https://www.dtn.com/wp-content/uploads/2019/03/dtn-logo-tag.png"}},"paths":{"/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","title":"Circle","description":"The paired values of a point and radius delineating the affected area of the alert message"},"ceiling":{"type":"number","title":"Ceiling","description":"The maximum altitude of the affected area of the alert message"},"altitude":{"type":"number","title":"Altitude","description":"The specific or minimum altitude of the affected area of the alert message"},"geocodes":{"items":{"properties":{"valueName":{"type":"string","title":"valueName","description":"Value name"},"value":{"type":"string","title":"value","description":"Actual value"}},"type":"object","required":["valueName","value"],"title":"Geocode"},"type":"array","title":"Geocodes","description":"The geographic code delineating the affected area of the alert message"}},"type":"object","required":["areaDesc"],"title":"GeoJsonAlertInfoArea"},"type":"array","title":"Area","description":"The container for all component parts of the area sub-element of the info sub- element of the alert message"}},"type":"object","required":["event","category","language","urgency","severity","certainty","expires","area"],"title":"GeoJsonAlertInfo"},"type":"array","title":"Info","description":"Additional information about the alert"}},"type":"object","required":["identifier","sender","sent","status","msgType","scope","updated","info"],"title":"GeoJsonAlertProperties"},"dtnInfo":{"properties":{"dtnMsgType":{"type":"string","title":"Dtnmsgtype","description":"Specifies the type of message generated by the DTN"},"dtnExpires":{"type":"string","format":"date-time","title":"Dtnexpires","description":"Specifies the date and time when the information in the alert message is set to expire, as generated by the DTN. This timestamp indicates until when the alert information remains valid and relevant."},"dtnEvent":{"type":"string","title":"Dtnevent","description":"Represents the type of event for which the alert message is generated within the DTN "},"dtnEventCode":{"type":"string","title":"Dtneventcode","description":"Provides a code associated with the specific event type, as defined by DTN, for which the alert message is generated."},"dtnDisclaimer":{"type":"string","title":"Dtndisclaimer","description":"Provides a disclaimer regarding the information included in the alert message."}},"type":"object","required":["dtnMsgType","dtnExpires","dtnEvent","dtnEventCode","dtnDisclaimer"],"title":"GeoJsonAlertDtnInfo"}},"type":"object","required":["id","agency","country","properties","dtnInfo"],"title":"GeoJsonAlert","example":{"id":"nws1364c1bdd210c7f036b66585590bcff39d46ea0f7c77a0a2e8f1db8651256caa","agency":"NWS","country":"US","type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-98,40],[-98,41],[-97,41],[-97,40],[-98,40]]]},"properties":{"identifier":"nws1364c1bdd210c7f036b66585590bcff39d46ea0f7c77a0a2e8f1db8651256caa","sender":"w-nws.webmaster@noaa.gov","sent":"2024-06-24T20:49:00","status":"Actual","msgType":"Update","scope":"Public","code":"IPAWSv1.0","updated":"2024-06-24T20:49:00","references":"w-nws.webmaster@noaa.gov,urn:oid:2.49.0.1.840.0.29e524a2edad47b728e81f62a538ac730e40e49a.001.1,2024-06-24T02:54:00-05:00","info":[{"event":"Heat Advisory","eventCode":[{"valueName":"SAME","value":"NWS"},{"valueName":"NationalWeatherService","value":"HTY"}],"category":"Met","language":"en-US","urgency":"Expected","severity":"Moderate","certainty":"Likely","responseType":"Execute","effective":"2024-06-24T20:49:00","onset":"2024-06-25T18:00:00","expires":"2024-06-26T00:00:00","senderName":"NWS Hastings NE","headline":"Heat Advisory issued June 24 at 3:49PM CDT until June 25 at 7:00PM CDT by NWS Hastings NE","description":"* WHAT...For the first Heat Advisory, heat index values up to 110\npossible. For the second Heat Advisory, heat index values around\n105 expected.\n\n* WHERE...In Kansas, Jewell, Mitchell, Osborne, Phillips, Rooks, and\nSmith Counties. In Nebraska, Nuckolls and Thayer Counties.\n\n* WHEN...For the first Heat Advisory, until 8 PM CDT this evening.\nFor the second Heat Advisory, from 1 PM to 7 PM CDT Tuesday.\n\n* IMPACTS...Hot temperatures and high humidity may cause heat\nillnesses.","instruction":"Take extra precautions when outside. Wear lightweight and loose\nfitting clothing. Try to limit strenuous activities to early morning\nor evening. Take action when you see symptoms of heat exhaustion and\nheat stroke. Drink plenty of fluids, stay in an air-conditioned\nroom, stay out of\nthe sun, and check up on relatives and neighbors.","web":"http://www.weather.gov","parameters":[{"valueName":"AWIPSidentifier","value":"NPWGID"},{"valueName":"WMOidentifier","value":"WWUS73 KGID 242049"},{"valueName":"NWSheadline","value":"HEAT ADVISORY REMAINS IN EFFECT UNTIL 8 PM CDT THIS EVENING... ...HEAT ADVISORY REMAINS IN EFFECT FROM 1 PM TO 7 PM CDT TUESDAY"},{"valueName":"BLOCKCHANNEL","value":"EAS,NWEM,CMAS"},{"valueName":"VTEC","value":"/O.CON.KGID.HT.Y.0002.240625T1800Z-240626T0000Z/"},{"valueName":"eventEndingTime","value":"2024-06-26T00:00:00+0000"},{"valueName":"CAPversion","value":"1.2"},{"valueName":"originalID","value":"2.49.0.1.840.0.f950770a5e0de71a60b45e3820f5c39fcdfe4222.001.2"}],"area":[{"areaDesc":"Phillips; Smith; Jewell; Rooks; Osborne; Mitchell; Nuckolls; Thayer","geocodes":[{"valueName":"UGC","value":"KSZ005"},{"valueName":"UGC","value":"KSZ006"},{"valueName":"UGC","value":"KSZ007"},{"valueName":"UGC","value":"KSZ017"},{"valueName":"UGC","value":"KSZ018"},{"valueName":"UGC","value":"KSZ019"},{"valueName":"UGC","value":"NEZ086"},{"valueName":"UGC","value":"NEZ087"}]}]}]},"dtnInfo":{"dtnMsgType":"Update","dtnExpires":"2024-06-26T00:00:00","dtnEvent":"Heat","dtnEventCode":"4","dtnDisclaimer":"Any DTN expiration dates, times, and message types shown here are automatically generated by the DTN's system, not by the alerting agencies themselves. Additionally, the dtnEvent and dtnEventCode are DTN's normalized event parameters for uniformity and do not necessarily reflect the exact terminology of the issuing agency. To access the original event name as published by the agency, please refer to the event parameter in the response."}}}}}},"401":{"content":{"application/json":{"schema":{"properties":{"detail":{"type":"string","title":"detail","description":"Details about the authorization error"}},"type":"object","required":["detail"],"title":"AuthorizationErrorResponse","example":{"detail":"Could not validate credentials"}}}},"description":"Unauthorized"},"422":{"content":{"application/json":{"schema":{"properties":{"detail":{"type":"string","title":"detail","description":"Details about the validation error including any invalid query parameters"}},"type":"object","required":["detail"],"title":"ValidationErrorResponse","example":{"detail":"Validation Error. ['language': invalid value. Examples: 'en-US', 'de-DE', 'fr-FR', 'es-ES', 'en-AU']"}}}},"description":"Unprocessable Entity"}}}}},"tags":[{"name":"Endpoints","description":"The the Agency Bulletin WebSocket API is designed on a single endpoint, offering unique functionalities tailored to your diverse weather bulletin data needs. Whether you require forecast and current data for a single point, country, or a bounding box, our API has got you covered. "}],"schemas":{"AuthorizationErrorResponse":{"properties":{"detail":{"type":"string","title":"detail","description":"Details about the authorization error"}},"type":"object","required":["detail"],"title":"AuthorizationErrorResponse","example":{"detail":"Could not validate credentials"}},"GeoJsonAlert":{"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","title":"Circle","description":"The paired values of a point and radius delineating the affected area of the alert message"},"ceiling":{"type":"number","title":"Ceiling","description":"The maximum altitude of the affected area of the alert message"},"altitude":{"type":"number","title":"Altitude","description":"The specific or minimum altitude of the affected area of the alert message"},"geocodes":{"items":{"properties":{"valueName":{"type":"string","title":"valueName","description":"Value name"},"value":{"type":"string","title":"value","description":"Actual value"}},"type":"object","required":["valueName","value"],"title":"Geocode"},"type":"array","title":"Geocodes","description":"The geographic code delineating the affected area of the alert message"}},"type":"object","required":["areaDesc"],"title":"GeoJsonAlertInfoArea"},"type":"array","title":"Area","description":"The container for all component parts of the area sub-element of the info sub- element of the alert message"}},"type":"object","required":["event","category","language","urgency","severity","certainty","expires","area"],"title":"GeoJsonAlertInfo"},"type":"array","title":"Info","description":"Additional information about the alert"}},"type":"object","required":["identifier","sender","sent","status","msgType","scope","updated","info"],"title":"GeoJsonAlertProperties"},"dtnInfo":{"properties":{"dtnMsgType":{"type":"string","title":"Dtnmsgtype","description":"Specifies the type of message generated by the DTN"},"dtnExpires":{"type":"string","format":"date-time","title":"Dtnexpires","description":"Specifies the date and time when the information in the alert message is set to expire, as generated by the DTN. This timestamp indicates until when the alert information remains valid and relevant."},"dtnEvent":{"type":"string","title":"Dtnevent","description":"Represents the type of event for which the alert message is generated within the DTN "},"dtnEventCode":{"type":"string","title":"Dtneventcode","description":"Provides a code associated with the specific event type, as defined by DTN, for which the alert message is generated."},"dtnDisclaimer":{"type":"string","title":"Dtndisclaimer","description":"Provides a disclaimer regarding the information included in the alert message."}},"type":"object","required":["dtnMsgType","dtnExpires","dtnEvent","dtnEventCode","dtnDisclaimer"],"title":"GeoJsonAlertDtnInfo"}},"type":"object","required":["id","agency","country","properties","dtnInfo"],"title":"GeoJsonAlert","example":{"id":"nws1364c1bdd210c7f036b66585590bcff39d46ea0f7c77a0a2e8f1db8651256caa","agency":"NWS","country":"US","type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-98,40],[-98,41],[-97,41],[-97,40],[-98,40]]]},"properties":{"identifier":"nws1364c1bdd210c7f036b66585590bcff39d46ea0f7c77a0a2e8f1db8651256caa","sender":"w-nws.webmaster@noaa.gov","sent":"2024-06-24T20:49:00","status":"Actual","msgType":"Update","scope":"Public","code":"IPAWSv1.0","updated":"2024-06-24T20:49:00","references":"w-nws.webmaster@noaa.gov,urn:oid:2.49.0.1.840.0.29e524a2edad47b728e81f62a538ac730e40e49a.001.1,2024-06-24T02:54:00-05:00","info":[{"event":"Heat Advisory","eventCode":[{"valueName":"SAME","value":"NWS"},{"valueName":"NationalWeatherService","value":"HTY"}],"category":"Met","language":"en-US","urgency":"Expected","severity":"Moderate","certainty":"Likely","responseType":"Execute","effective":"2024-06-24T20:49:00","onset":"2024-06-25T18:00:00","expires":"2024-06-26T00:00:00","senderName":"NWS Hastings NE","headline":"Heat Advisory issued June 24 at 3:49PM CDT until June 25 at 7:00PM CDT by NWS Hastings NE","description":"* WHAT...For the first Heat Advisory, heat index values up to 110\npossible. For the second Heat Advisory, heat index values around\n105 expected.\n\n* WHERE...In Kansas, Jewell, Mitchell, Osborne, Phillips, Rooks, and\nSmith Counties. In Nebraska, Nuckolls and Thayer Counties.\n\n* WHEN...For the first Heat Advisory, until 8 PM CDT this evening.\nFor the second Heat Advisory, from 1 PM to 7 PM CDT Tuesday.\n\n* IMPACTS...Hot temperatures and high humidity may cause heat\nillnesses.","instruction":"Take extra precautions when outside. Wear lightweight and loose\nfitting clothing. Try to limit strenuous activities to early morning\nor evening. Take action when you see symptoms of heat exhaustion and\nheat stroke. Drink plenty of fluids, stay in an air-conditioned\nroom, stay out of\nthe sun, and check up on relatives and neighbors.","web":"http://www.weather.gov","parameters":[{"valueName":"AWIPSidentifier","value":"NPWGID"},{"valueName":"WMOidentifier","value":"WWUS73 KGID 242049"},{"valueName":"NWSheadline","value":"HEAT ADVISORY REMAINS IN EFFECT UNTIL 8 PM CDT THIS EVENING... ...HEAT ADVISORY REMAINS IN EFFECT FROM 1 PM TO 7 PM CDT TUESDAY"},{"valueName":"BLOCKCHANNEL","value":"EAS,NWEM,CMAS"},{"valueName":"VTEC","value":"/O.CON.KGID.HT.Y.0002.240625T1800Z-240626T0000Z/"},{"valueName":"eventEndingTime","value":"2024-06-26T00:00:00+0000"},{"valueName":"CAPversion","value":"1.2"},{"valueName":"originalID","value":"2.49.0.1.840.0.f950770a5e0de71a60b45e3820f5c39fcdfe4222.001.2"}],"area":[{"areaDesc":"Phillips; Smith; Jewell; Rooks; Osborne; Mitchell; Nuckolls; Thayer","geocodes":[{"valueName":"UGC","value":"KSZ005"},{"valueName":"UGC","value":"KSZ006"},{"valueName":"UGC","value":"KSZ007"},{"valueName":"UGC","value":"KSZ017"},{"valueName":"UGC","value":"KSZ018"},{"valueName":"UGC","value":"KSZ019"},{"valueName":"UGC","value":"NEZ086"},{"valueName":"UGC","value":"NEZ087"}]}]}]},"dtnInfo":{"dtnMsgType":"Update","dtnExpires":"2024-06-26T00:00:00","dtnEvent":"Heat","dtnEventCode":"4","dtnDisclaimer":"Any DTN expiration dates, times, and message types shown here are automatically generated by the DTN's system, not by the alerting agencies themselves. Additionally, the dtnEvent and dtnEventCode are DTN's normalized event parameters for uniformity and do not necessarily reflect the exact terminology of the issuing agency. To access the original event name as published by the agency, please refer to the event parameter in the response."}}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ValidationErrorResponse":{"properties":{"detail":{"type":"string","title":"detail","description":"Details about the validation error including any invalid query parameters"}},"type":"object","required":["detail"],"title":"ValidationErrorResponse","example":{"detail":"Validation Error. ['language': invalid value. Examples: 'en-US', 'de-DE', 'fr-FR', 'es-ES', 'en-AU']"}}},"servers":[{"url":"http://wxbulletin-ws.api.dtn.com"},{"url":"http://agency-bulletin-ws.prd.wx.zones.dtn.com"}],"components":{"securitySchemes":{"clientCredentials":{"type":"oauth2","x-receive-token-in":"request-body","flows":{"clientCredentials":{"tokenUrl":"https://api.auth.dtn.com/v1/tokens/authorize"}},"description":"# Using DAIS for M2M/API Auth\nYou have been given a Client ID and a Client Secret, which are used to request a DTN Access Token. DTN Access Tokens are required when making calls to each and every DTN API endpoint. The following information provides additional details on these tokens and how they are generated.\n## What is an Access Token and how is it different from an API Key?\nAn API Key is a random string of characters that an API uses to authorize whether or not a calling client has approved access to an endpoint. These keys are a non-standard approach to API authorization and are generally issued on a per-API basis.\n\nAn Access Token is also a string of characters but is a base-64 encoded JavaScript Object Notation Web Token, or JWT. JWTs are a widely accepted standard that use OAuth concepts and approaches. \n\nBoth API Keys and Access Tokens are used in an Authorization Request Header as a Bearer, meaning there is no difference in where you put this string of characters when you make calls to DTN APIs.\n## How to generate an Access Token?\nWhen requested, an Access Token is generated for your specific Client (ID/Secret) and for a specific API. The DTN Auth and Identity Service (DAIS) generates new Access Tokens for your client. The DAIS endpoint is `POST https://api.auth.dtn.com/v1/tokens/authorize`.\n\nThis endpoint takes two Header parameters:\n  * `Content-Type: application/json`\n  * `Accept: application/json`\n\nThis endpoint takes four parameters in the Request Body:\n  * `grant_type`: this should always be client_credentials for generating machine-to-machine tokens.\n  * `client_id`: this is the Client ID or Application ID using the token and is given to you by DTN's Identity Team. This ID will never change for your client/application.\n  * `client_secret`: this is the Client Secret that is associated with the Application ID and is given to you by DTN's Identity Team. This key is subject to rotation for security purposes but always with the client's knowledge.\n  * `audience`: this is the API for which this Access Token will be used. For the DTN ABA WebSocket, you need to use the following audience: https://weather.api.dtn.com\n\nYou can use this CURL command template as a reference for obtaining an access token:\n  ```\n  curl --location --request POST 'https://api.auth.dtn.com/v1/tokens/authorize' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n\"grant_type\": \"client_credentials\",\n\"client_id\": \"insert your client id here\",\n\"client_secret\": \"insert your client secret here\",\n\"audience\": \"insert your audience here\"\n}' \n  ```\n\n*This document, for demonstration purposes, supplies a client_id and client_secret in all code examples. This client/application is for a fictitious API and cannot be used in practice to gain unauthorized access to any other DTN API.*\nUpon generating a new Access Token, you should receive an HTTP Response from DAIS similar to this:\n  ```\n  {\n    \"data\": {\n          \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InpfX21pZW13NGhoTmdvQWQxR3N6ciJ9.eyJodHRwczovL2F1dGguZHRuLmNvbS9jdXN0b21lcklkIjoiMTIzNDU2Nzg5MERlbW8iLCJodHRwczovL2F1dGguZHRuLmNvbS9wcm9kdWN0Q29kZSI6IkRlbW9BcGlQIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcmVxdWVzdGVySXAiOiIxOC4yMTMuMTc0LjI3IiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcnBzIjoiMTAwIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vdGllciI6IkJhc2ljIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcXVvdGEiOiI5OTk5OTkiLCJpc3MiOiJodHRwczovL2lkLmF1dGguZHRuLmNvbS8iLCJzdWIiOiJuZnlPM0tpS1BSOE4wREtSNUNMOGpTOUdGQkNEZXlGTUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9kZW1vLWFwaS5hdXRoLmR0bi5jb20vIiwiaWF0IjoxNjU2MDk5MDY4LCJleHAiOjE2NTYwOTkxNTgsImF6cCI6Im5meU8zS2lLUFI4TjBES1I1Q0w4alM5R0ZCQ0RleUZNIiwic2NvcGUiOiJyZWFkOmRlbW8gY3JlYXRlOmRlbW8gdXBkYXRlOmRlbW8iLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJwZXJtaXNzaW9ucyI6WyJyZWFkOmRlbW8iLCJjcmVhdGU6ZGVtbyIsInVwZGF0ZTpkZW1vIl19.0VHdyp1w9PPFVI0FPheAwuKZwb5C25rwP-LPMXcSNoRmouvga1DZtNLA67ZzE_sAlc_VpaDRr6daLKr_Alw4347mw9sdjP8wKR27kCZa9JZK5PGQMmXHscATbzBEJYpCPklfyGaajgymqTBGnedcv8F0UvlRzQPsFeRPnVoX7BWOSXpMbyToGiXWkQLBQT7r96KAmLZOPJFZspPtjw-wH2mSL2WNa_nkB4j5vMGhGxlKiNRsKb30TH_WAel2hsxNlcPK3XHCmrMTYsNnu7HNqOTMn2i0__0rvBrhSWEw-_grqQDmWFJuWd7Qhi1q81AaJcdqgoSa_efz93QFclJUNw\",\n          \"scope\": \"read:demo create:demo update:demo\",\n          \"expires_in\": 90,\n          \"token_type\": \"Bearer\"\n      },\n      \"meta\": {\n          \"date_time\": \"2022-06-24T19:09:42.963Z\",\n          \"name\": \"v1.tokens.authorize\",\n          \"uuid\": \"ee6f9feb-dcf8-4421-a6fd-efd6beabdaa9\",\n          \"start_timestamp\": 1656097782509,\n          \"end_timestamp\": 1656097782963,\n          \"execution_time\": 454\n      }\n  }\n  ```\nLooking at this Response, you will see:\n  * `access_token`: contains the JWT Access Token string you will use as your Bearer token.\n  * `scope`: contains the scopes that this Access Token gives you permissions to access.\n  * `expires_in`: contains the length of time before this Access Token will expire, in seconds.\n  * `token_type`: verifies that this Access Token should be used as a Bearer token.\n\n## How to use an Access Token after one is generated?\nOnce a new Access Token is obtained, it is used in each call to a DTN API endpoint as a Bearer token in an Authorization Request Header. For example:\n  ```\n  Header: 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InpfX21pZW13NGhoTmdvQWQxR3N6ciJ9.eyJodHRwczovL2F1dGguZHRuLmNvbS9jdXN0b21lcklkIjoiMTIzNDU2Nzg5MERlbW8iLCJodHRwczovL2F1dGguZHRuLmNvbS9wcm9kdWN0Q29kZSI6IkRlbW9BcGlQIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcmVxdWVzdGVySXAiOiIxOC4yMTMuMTc0LjI3IiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcnBzIjoiMTAwIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vdGllciI6IkJhc2ljIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcXVvdGEiOiI5OTk5OTkiLCJpc3MiOiJodHRwczovL2lkLmF1dGguZHRuLmNvbS8iLCJzdWIiOiJuZnlPM0tpS1BSOE4wREtSNUNMOGpTOUdGQkNEZXlGTUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9kZW1vLWFwaS5hdXRoLmR0bi5jb20vIiwiaWF0IjoxNjU2MDk5MDY4LCJleHAiOjE2NTYwOTkxNTgsImF6cCI6Im5meU8zS2lLUFI4TjBES1I1Q0w4alM5R0ZCQ0RleUZNIiwic2NvcGUiOiJyZWFkOmRlbW8gY3JlYXRlOmRlbW8gdXBkYXRlOmRlbW8iLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJwZXJtaXNzaW9ucyI6WyJyZWFkOmRlbW8iLCJjcmVhdGU6ZGVtbyIsInVwZGF0ZTpkZW1vIl19.0VHdyp1w9PPFVI0FPheAwuKZwb5C25rwP-LPMXcSNoRmouvga1DZtNLA67ZzE_sAlc_VpaDRr6daLKr_Alw4347mw9sdjP8wKR27kCZa9JZK5PGQMmXHscATbzBEJYpCPklfyGaajgymqTBGnedcv8F0UvlRzQPsFeRPnVoX7BWOSXpMbyToGiXWkQLBQT7r96KAmLZOPJFZspPtjw-wH2mSL2WNa_nkB4j5vMGhGxlKiNRsKb30TH_WAel2hsxNlcPK3XHCmrMTYsNnu7HNqOTMn2i0__0rvBrhSWEw-_grqQDmWFJuWd7Qhi1q81AaJcdqgoSa_efz93QFclJUNw'\n  ```\n\n## Deconstructing the Access Token\nA DTN Access Token carries information within its JWT Body that is available on every API call. By deconstructing the JWT token, our Access Tokens will resemble:\n  ```\n  {\n    \"https://auth.dtn.com/customerId\": \"1234567890Demo\",\n    \"https://auth.dtn.com/productCode\": \"DemoApiP\",\n    \"https://auth.dtn.com/requesterIp\": \"18.213.174.27\",\n    \"https://auth.dtn.com/rps\": \"100\",\n    \"https://auth.dtn.com/tier\": \"Basic\",\n    \"https://auth.dtn.com/quota\": \"999999\",\n    \"iss\": \"https://id.auth.dtn.com/\",\n    \"sub\": \"nfyO3KiKPR8N0DKR5CL8jS9GFBCDeyFM@clients\",\n    \"aud\": \"https://demo-api.auth.dtn.com/\",\n    \"iat\": 1656099068,\n    \"exp\": 1656099158,\n    \"azp\": \"nfyO3KiKPR8N0DKR5CL8jS9GFBCDeyFM\",\n    \"scope\": \"read:demo create:demo update:demo\",\n    \"gty\": \"client-credentials\",\n    \"permissions\": [\n      \"read:demo\",\n      \"create:demo\",\n      \"update:demo\"\n    ]\n  }\n  ```\n### Description of Claims\n\n  | Claim                              | Type                                        | Description                                                                                                                                                                                                                |\n  | -----------------------------------| --------------------------------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n  | `https://auth.dtn.com/customerId`  | String                                      | Custom DTN claim containing the Customer ID found in the DTN Order Management/Salesforce system associated with this token.                                                                                                |\n  | `https://auth.dtn.com/productCode` | String                                      | Custom DTN claim containing the Identity product code associated with this token.                                                                                                                                          |\n  | `https://auth.dtn.com/requesterIp` | String                                      | Custom DTN claim containing the IP address of the requesting client.                                                                                                                                                       |\n  | `https://auth.dtn.com/rps`         | String                                      | Custom DTN claim containing the maximum rate per second this customer is authorized to utilize.                                                                                                                            |\n  | `https://auth.dtn.com/tier`        | String                                      | Custom DTN claim containing the data tier the customer purchased for the requested access.                                                                                                                                 |\n  | `https://auth.dtn.com/quota`       | String                                      | Custom DTN claim containing the maximum yearly quota the customer purchased for calling DTN endpoints for the specific product.                                                                                            |\n  | `iss`                              | String (URI)                                | The Security Token Service (STS) that issues and returns the token. If this value is not from `https://id.auth.dtn.com/`, the token should not be considered trusted.                                                      |\n  | `sub`                              | String (URI)                                | The principle about which the token asserts information (the User ID or Client ID within the Identity Provider). A User ID will start with a prefix of `auth0\\|`, while the Client ID will end with the suffix `@clients`. |\n  | `aud`                              | String \\| Array (Strings) (URI \\| [URI, …]) | Identifies the intended recipient(s) of the token – its audience. The token should be rejected if the audience does not contain values expected by the calling application.                                                |\n  | `iat`                              | Number (Timestamp)                          | “Issued At” indicates when the authentication for this token occurred.                                                                                                                                                     |\n  | `exp`                              | Number (Timestamp)                          | The “expiration time” on or after which the JWT must not be accepted for processing.                                                                                                                                       |\n  | `azp`                              | String                                      | The application/client ID of the client using the token. The application can cat as itself or on behalf of a user.                                                                                                         |\n  | `gty`                              | String (Space-delimited)                    | The grant type that was used to request the token – not an RFC 7519 registered claim (Auth0-specific).                                                                                                                     |\n  | `permissions`                      | Array (Strings)                             | The grant type that was used to request the token – not an RFC 7519 registered claim (Auth0-specific).                                                                                                                     |\n\n  "}}}}