Convective Outlook

URL Path

https://data.api.xweather.com/convective/outlook/

Data Coverage

Continental US

Update Interval

Time Range

+8 days

The convective/outlook endpoint provides convective outlook information based on SPC Convective Outlooks (opens in a new tab). Convective outlooks provide information on potential severe weather, including thunderstorms, tornadoes, damaging high winds, and hail. Coverage for this endpoint is available for the US only.

Requests

Every request to the endpoint must include one of the supported actions in the url.

https://data.api.xweather.com/convective/outlook/{action}?client_id={client_id}&client_secret={client_secret}&{params}

Supported Actions

The following actions are supported with the /convective/outlook endpoint:

Action	Description
:id	Type: stringTypically used for passing a geographical location name or identifier such as city name, lat/long, or even US and Canadian postal codes. Learn more.
affects	Type: stringReturns a list of locations that are currently affected by a weather event. Criteria for the location(s) can be determined in your query parameters. Learn more.
contains	Type: stringUsed with polygon based products (convective outlook, drought monitor, etc.) to determine if the queried location is inside of an impacted area. Learn more.
search	Type: stringA generalized action that is determined with the endpoints query parameters. Learn more.

Response

The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.

Properties

id (string)

The unique identifier for the event

details (object)

Object containing details about the event

details.product (string)

The product type. Should normally be "convective"

details.category (string)

The outlook category type.

details.day (number)

Valid coverage day. Value from 1-8

details.range (object)

Object of the valid coverage period information

details.range.minTimestamp (number)

The minimum timestamp of the valid coverage period

details.range.maxTimestamp (number)

The maximum timestamp of the valid coverage period

details.range.minDateTimeISO (string)

The ISO 8601 date time string of the minimum timestamp

details.range.maxDateTimeISO (string)

The ISO 8601 date time string of the maximum timestamp

details.issuedTimestamp (number)

The timestamp of when the event was issued

details.issuedDateTimeISO (string)

The ISO 8601 date time string of when the event was issued

details.risk (object)

Object of the risk associated with the outlook. NULL if no associated risk

details.risk.type (string)

The abbreviated risk type

details.risk.name (string)

The full risk name as provided by SPC

details.risk.code (number)

The coded version of the risk type

geoPoly (object)

GeoJSON object, normally a Polygon or MultiPolygon, for the coverage area. NULL if the geo filter is not provided AND / OR there is no associated risk with the outlook.
Null if not requested (i.e. if filter=geo not provided)

geoPoly.type (string)

The GeoJSON type of the object, Normally "Polygon" or "MultiPolygon"

geoPoly.coordinates (array)

The GeoJSON coordinates array. Normally a 2D array of coordinates, but can be 3D if the type is "MultiPolygon"

[
  {
    "id": "657b42b5c61a2b7ca0acb4d6",
    "details": {
      "product": "convective",
      "category": "cat",
      "day": 1,
      "range": {
        "minTimestamp": 1702571400,
        "maxTimestamp": 1702641600,
        "minDateTimeISO": "2023-12-14T16:30:00+00:00",
        "maxDateTimeISO": "2023-12-15T12:00:00+00:00"
      },
      "issuedTimestamp": 1702571040,
      "issuedDateTimeISO": "2023-12-14T16:24:00+00:00",
      "risk": {
        "type": "general",
        "name": "general thunderstorms risk",
        "code": 1
      }
    },
    "geoPoly": {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [
              -101.31,
              30.07
            ],
            [
              -102.72,
              30.72
            ],
            [
              -104.01,
              31.52
            ],
            [
              -105.34,
              32.21
            ],
            [
              -106.42,
              32.99
            ],
            [
              -107.66,
              34.31
            ],
            [
              -108,
              35.07
            ],
            [
              -108.16,
              35.88
            ],
            [
              -107.96,
              36.33
            ],
            [
              -107.14,
              36.57
            ],
            [
              -106.02,
              36.58
            ],
            [
              -103.04,
              36.76
            ],
            [
              -101.48,
              37.49
            ],
            [
              -99.66,
              38.45
            ],
            [
              -98.18,
              38.15
            ],
            [
              -97.31,
              36.26
            ],
            [
              -96.93,
              34.37
            ],
            [
              -97.45,
              32.91
            ],
            [
              -98.33,
              31.25
            ],
            [
              -99.65,
              30.55
            ],
            [
              -101.31,
              30.07
            ]
          ]
        ],
        [
          [
            [
              -96.729273,
              27.64428
            ],
            [
              -96.796,
              27.579
            ],
            [
              -97.017,
              27.081
            ],
            [
              -96.876,
              26.595
            ],
            [
              -96.749,
              25.948
            ],
            [
              -97.075,
              25.799
            ],
            [
              -97.23,
              25.659
            ],
            [
              -97.68,
              25.837
            ],
            [
              -98.218,
              25.934
            ],
            [
              -98.509,
              26.039
            ],
            [
              -99.103,
              26.254
            ],
            [
              -99.357,
              26.519
            ],
            [
              -99.489,
              26.804
            ],
            [
              -99.612,
              27.039
            ],
            [
              -99.617736,
              27.056007
            ],
            [
              -97.49,
              27.65
            ],
            [
              -96.729273,
              27.64428
            ]
          ]
        ],
        [
          [
            [
              -79.749811,
              26.362662
            ],
            [
              -79.766,
              26.228
            ],
            [
              -79.812,
              25.576
            ],
            [
              -79.965,
              25.158
            ],
            [
              -80.143,
              24.859
            ],
            [
              -80.331,
              24.705
            ],
            [
              -80.635,
              24.487
            ],
            [
              -81.054,
              24.361
            ],
            [
              -81.782,
              24.208
            ],
            [
              -82.816,
              24.169
            ],
            [
              -83.288,
              24.221
            ],
            [
              -83.28,
              24.513
            ],
            [
              -83.276623,
              24.535917
            ],
            [
              -81.51,
              24.8
            ],
            [
              -80.78,
              25.19
            ],
            [
              -80.11,
              26.14
            ],
            [
              -79.749811,
              26.362662
            ]
          ]
        ]
      ]
    }
  }
]

Endpoints