Real-time Severe Weather Alerts (API)

Photo by NOAA on Unsplash

This article describes how to use a scalable real-time weather API built to track severe weather alerts for locations, using postal addresses or geolocation coordinates (latitude, longitude).

Introduction

Severe weather is becoming increasingly more common. With sudden winter storms, severe floods, extreme wildfires, and widespread flooding during hurricanes becoming more frequent and more intense (NASA article).

Access to realtime severe weather alerts is a helpful way to prepare, track, and analyze the impact of severe weather on companies. Especially companies that provide customer services through physical third-party locations (such as hospitals, clinics, laboratories, etc).

It’s easy to track severe weather when locations are clustered to regional areas. However, many companies engage with third-party locations that span across the US, which can make it difficult to manually track multiple weather events across tens (or hundreds) of locations.

Using this API, a company can proactively prepare for, monitor, and analyze the impact of severe weather events on the services they provide. Pulling severe weather event data via API also allows companies to easily integrate weather analytics into their existing analytical workflows (Tableau, AWS, etc).

How to use the API

The API can be used like any other REST API. Notably, the API allows for two primary forms of location search:

1. Geo-point Search

Geo-point search allows users to pull realtime relevant severe weather alerts using the locations latitudinal and longitudinal coordinates.

Sample request URL:

https://cfjavr0s5i.execute-api.us-east-1.amazonaws.com/FREE/location/alerts?search_format=lat_long&search_value=37.6506944,-119.0369831

Sample request via Python:

import requests
import json

url = 'https://cfjavr0s5i.execute-api.us-east-1.amazonaws.com/FREE/location/alerts'
headers = {'text':'test'}
data = {
    'search_format':'lat_long', 'search_value': '37.6506944,-119.0369831'
    }

content = requests.get(url, headers=headers, params=data)
response = json.loads(content.text)

2. Postal Address Search

Postal address search allows users to pull realtime relevant severe weather alerts using a locations postal address. Two address search options are available:

Structured Postal Address Search:

import requests
import json

url = 'https://cfjavr0s5i.execute-api.us-east-1.amazonaws.com/FREE/location/alerts'
headers = {'text':'test'}
data = {
    'search_format':'address', 
    'address_format':'structured', 
    'search_value': json.dumps(
        {
          'street' : '10001 Minaret Rd',
          'city' : 'Mammoth Lakes',
          'county' : '',
          'state' : 'CA',
          'country' :  'United States',
          'postalcode' : '93546'
          }
        )
    }

content = requests.get(url, headers=headers, params=data)
response = json.loads(content.text)

Flat Postal Address Search:

import requests
import json

url = 'https://cfjavr0s5i.execute-api.us-east-1.amazonaws.com/FREE/location/alerts'
headers = {'text':'test'}
data = {
    'search_format':'address', 
    'address_format':'flat', 
    'search_value': '10001 Minaret Rd, Mammoth Lakes, CA 93546, United States'
    }

content = requests.get(url, headers=headers, params=data)
response = json.loads(content.text)

Sample API Request Response

Below is a sample response from the API:

[{'notification_event': 'Snow showers to continue in Mono County - Up to 5 inches expected',
  'notification_start_date': 'Mar 24 2024, 07:52:00 UTC-07:00',
  'notification_end_date': 'Mar 24 2024, 20:00:00 UTC-07:00',
  'weather_start_date': 'Mar 24 2024, 07:52:00 UTC-07:00',
  'weather_end_date': None,
  'url': '',
  'impact': 'Moderate',
  'probability': 'Occured',
  'timing': 'Expected',
  'event_category': 'Urgent Weather Event',
  'recommendation': 'Proaction'}]

How it works

The API leverages a variety of data sources to transform and analyze the location (geo-point data, or postal address) relative to predefined Geographic Information System (GIS) geospatial polygons. The provided location is cross referenced against known geospatial polygon zones, and then analyzed to identify relevant severe weather alerts that are specific to the locations regional area.

Large Language Models (LLMs) are also used to help interpret edge-case weather events and simplify the event descriptions for users and pull the most relevant weather event web article (when applicable).

Important details (about the API)

It is important to note that the API details provided in this article use the free public version. Thus, the API requests are restricted to 1 request every 5 seconds and is WAF-enabled for IP address monitoring restrictions.

The API is also limited to only United States severe weather events. If your request does not go through, I recommend implementing a retry logic, especially during peak request times, or feel free to send me a message.

Existing API users that have a client account are not restricted by the same limitations as the public version of the API.

Thanks for reading ~