Skip to content

Favorites

Weather API Documentation

Introduction

The weatherUSA Weather API is a REST/KVP interface for retrieving weather data for locations across the United States. Real-time weather, historical weather, forecasts, and climate information are available via the API. The API accepts standard HTTP requests and returns standard HTTP response codes and JSON response messages for most endpoints. User management, custom, and batch processing endpoints are also available.

The Weather API is also used to communicate with our databases for WeatherNet Aware and our white-label alerting service, allowing you to create and modify weather alert subscriptions for your locations by remote calls.

Authorization

All API requests must use a key, OAuth2 token, or session cookie to authorize access to the API. All requests using these methods must operate over HTTPS to provide security for the key. Never embed your account key in a client-facing program, such as JavaScript code. Contact your Account Manager to request a public key that can be restricted to operation on your domain names or over regular HTTP.

Response codes and errors

HTTP Status CodeDescription
200 OKSuccess, situation normal
400 Bad RequestThe request was unacceptable, often due to a missing parameter. Please check the documentation for the requested feed type.
401 UnauthorizedNo valid authorization provided
403 ForbiddenThe given API key or client domain have been blocked
404 Not FoundThe requested resource is invalid. Please contact Support for assistance.
409 ConflictThe request conflicts with a previous request (only for processing requests with unique identifiers)
429 Too Many RequestsToo many requests have pinged the API using this key and are being rate limited
500 Internal Server Error
503 Service Unavailable
504 Gateway Timeout
Something's amiss on our end. If the error occurs again in a few minutes, please contact Support for assistance.

Feeds

The base Weather API URL is:

https://api.weatherusa.net/feed?type=[feed type]

The Weather API currently offers the following types of data and resources:

Feed typeDescription
obsSurface weather observations from weather stations around the world, by MADIS station ID.
obshistoryHistorical weather observations up to one month in advance.
placeUS place names database & geocoding, including cities, ZIP codes, and all non-historic places in the USGS GNIS.
stationlistNearby weather station IDs from a latitude/longitude pair or inside a bounding box.
forecastHourly and daily forecasts up to 7-days for US locations and territories including Hawaii, Alaska, Puerto Rico.
alertsWeather alerts from the National Weather Service.
alert_textFull message body using an alert identifier from the alerts endpoint.
skycamsNearby live weather cameras and cached thumbnail images from the weatherUSA SkyCams database.
lsrPreliminary Local Storm Reports from National Weather Service local offices.
aqiCombined Air Quality Index at a location.
uvUltraviolet Index estimate at a location.

Feed type: obs

Example URL

https://api.weatherusa.net/feed?type=obs&station_id=KCMH

Attributes

station_id
required
Comma-separated list of one or more station IDs

Feed type: obshistory

Example URL

https://api.weatherusa.net/feed?type=obshistory&q=40.00,-83.02&var=maxt

Attributes

q
required
Coordinates, decimal in the format latitude,longitude
var
required
Variable to summarize for the range given by time. Currently available are: maxt (Maximum temperature), mint (minimum temperature), precip (total precipitation).
time
optional
Time range to compute variable across. Use "s" suffix for seconds, "h" for hours, and "d" for days (e.g. "24h")

Feed type: place

Example URL

https://api.weatherusa.net/feed?type=place&q=Colum

Attributes

q
required
Place name (forward or reverse) to look up. Can be any of the following:
  • Full place name, state
  • Partial city name to return a list of matches (auto-suggest)
  • ZIP code
  • GNIS place ID
  • METAR Airport code
  • Coordinates to find nearest place name
exact
optional
Boolean (1 or 0). Match name exactly, don't try to correct for misspellings or suggest more than one location.

Feed type: stationlist

Example URL

https://api.weatherusa.net/feed?type=stationlist&q=40.00,-83.02

Attributes

q
required
Coordinates, decimal in the format latitude,longitude

Feed type: forecast

Example URL

https://api.weatherusa.net/feed?type=forecast&q=40.00,-83.02&daily=0&units=e&maxtime=7d

Attributes

q
required
Coordinates, decimal in the format latitude,longitude
daily
optional
Boolean (1 or 0). Return daily data including the day's high, low, predominant weather type, and chance of precipitation.
units
optional
Return forecast units in English (e) or Metric (m).
maxtime
optional
Maximum forecast time range to return. Can be in hours ("24h") or days ("7d"). Maximum of 8 days.

Feed type: alerts

Example URL

https://api.weatherusa.net/feed?type=alerts&q=39.937%2C-83.110&wxzone=OHZ055&fire_zone=OHZ055&fips=39049

Attributes

q
optional
Coordinates, decimal in the format latitude,longitude
fips
optional
County FIPS code. Use the place endpoint to find this code for a particular location.
wxzone
optional
NWS Weather Zone code. Use the place endpoint to find this code for a particular location.
fire_zone
optional
NWS Fire Zone code. Use the place endpoint to find this code for a particular location.
data
optional
Boolean (1 or 0) to include full message text in the response.

Feed type: alert_text

Example URL

https://api.weatherusa.net/feed?type=alert_text&id=46101549

Attributes

id
required
The identifier of the alert from the alerts endpoint.

Feed type: skycams

Example URL

https://api.weatherusa.net/feed?type=skycams&q=40.00,-83.02

Attributes

q
required
Coordinates, decimal in the format latitude,longitude

Feed type: lsr

Example URL

https://api.weatherusa.net/feed?type=lsr&delta_t=43200

Attributes

delta_t
optional
Fetch local storm reports for the last delta_t seconds. Default is 64800 seconds (18 hours).

Feed type: aqi

Example URL

https://api.weatherusa.net/feed?type=aqi&q=40.00,-83.02

Attributes

q
required
Coordinates, decimal in the format latitude,longitude

Feed type: uv

Example URL

https://api.weatherusa.net/feed?type=uv&q=40.00,-83.02

Attributes

q
required
Coordinates, decimal in the format latitude,longitude

User & Alerting Subscription API

weatherUSA offers an API to create and update recipient types (e.g. e-mail, text message) in our white-label alerting service, and subscribe those recipients to alerts by creating triggers.

https://api.weatherusa.net/v1/user/[option]
OptionDescription
recipientAdd or update a recipient to your user account
alertsSubscribe recipient to alerts
alerts-productsFetch list of current NWS and weatherUSA Alert Products

Resource: recipient

List recipients in account

Example URL

https://api.weatherusa.net/v1/user/recipient/list?access_token=
https://api.weatherusa.net/v1/user/recipient/list/9999?access_token=

Attributes

Recipient ID
optional
Filter by recipient ID
Recipient Name
optional
Filter by recipient address (e.g. recipient/list/test@example.com)

Create a new recipient

Example URL

https://api.weatherusa.net/v1/user/recipient/new?type=email&recipient=test@example.com&access_token=

Attributes

type
required
Current message types are:
  • email
  • sms
  • voice
  • mq
recipient
required
Recipient address, usually an e-mail address, phone number, or device ID
alias
optional
Customize the name associated with this recipient address
grouping
optional, default true
Group an alert for multiple locations into a single text message

Update an existing recipient

Example URL

https://api.weatherusa.net/v1/user/recipient/edit/9999?recipient=test2@example.com&access_token=

Attributes

recipient ID
required
Recipient ID as returned by a recipient list query or previously stored
recipient
optional
Updated recipient address, usually an e-mail address, phone number, or device ID
alias
optional
Customize the name associated with this recipient address
grouping
optional, default true
Group an alert for multiple locations into a single text message

Delete an existing recipient

Example URL

https://api.weatherusa.net/v1/user/recipient/delete/9999?access_token=

Attributes

recipient ID
required
Recipient ID as returned by a recipient list query or previously stored

Resource: alerts

List alert triggers for recipients

Example URL

https://api.weatherusa.net/v1/user/alerts/list/9999?access_token=

Attributes

Recipient ID
optional
Filter by recipient ID
Recipient Name
optional
Filter by recipient address (e.g. recipient/alerts/test@example.com)

Create a new alert trigger

Example URL

https://api.weatherusa.net/v1/user/alerts/new?recipient_id=9999&access_token=

Attributes

recipient_id
required
Recipient ID as returned from the recipient resource
type
required
Alert Product ID, e.g. "TOR" or "FL.W" or "TCP_U". See below List of possible alert product identifiers.
q
required
Location identifier. County ID (FIPS code) or coordinates
time_start
optional
Hour, in UTC, to leave quiet time (activate alerts)
time_end
optional
Hour, in UTC, to enter quiet time (silence alerts)
alias
optional
Alias for location or facility, e.g. "Retail Store #1283"
extras
optional
Required if type is "WXUSA_TFC" (Forecast Trigger) or "WXUSA_TOB" (Observation Trigger). For WXUSA_TFC, the following required parameters, separated by commas:
  • maxtime: Maximum forecast time range to search for a matching condition. Can be in hours ("24h") or days ("7d"). Maximum of 8 days.
  • variable: Weather variable to monitor. Currently one of temperature, wgust (max wind gust), precip (precipitation, liquid equivalent), snow (estimated snowfall).
  • operator: Comparison to perform, one of gt (greater than), lt (less than), eq (equal to), gte (greater than or equal), lte (less than or equal), range, or not-range
  • value: Value to compare. For all operators except range/not-range, a single integer or float. For range/not-range, two integers or floats separated by two dots "..".

Example: Trigger an alert if the forecast for the next 24 hours at the given location (q) has a temperature less than 30 F.
24h,temperature,lt,30

Example: Trigger an alert if precipitation is expected in the next 24 hours at the given location (q).
24h,precip,gt,0.00

Example: Trigger an alert if the forecast for the next 96 hours predicts a temperature at location (q) to exceed the range 20 F - 90 F.
3d,temperature,range,20.0..80.0

Update an alert trigger

Example URL

https://api.weatherusa.net/v1/user/alerts/edit/9999?q=OHZ055&access_token=

Attributes

Trigger ID
required
ID of the trigger from subscription list query or previously stored
type
optional
Alert Product ID, e.g. "TOR" or "FL.W" or "TCP_U". See below List of possible alert product identifiers.
q
optional
Location identifier. County ID (FIPS code) or coordinates
time_start
optional
Hour, in UTC, to leave quiet time (activate alerts)
time_end
optional
Hour, in UTC, to enter quiet time (silence alerts)
alias
optional
Alias for location or facility, e.g. "Retail Store #1283"

Delete an alert trigger

Example URL

https://api.weatherusa.net/v1/user/alerts/delete/9999?access_token=

Attributes

Trigger ID
required
Trigger ID as returned by a subscription list query or previously stored

Metadata: List of possible alert product identifiers

URL

https://api.weatherusa.net/v1/user/alerts/product-types?access_token=

Attributes

No attributes for this endpoint.

Response Format

A JSON formatted response will be returned.

idProduct ID
nameProduct Name
typeOne of local, national, national_location. Some products are targeted to a local area (point, county) and some for a region (Atlantic), or other geographic descriptors.
descriptionHTML-formatted description of the alert product.
support_smstrue if SMS alerts are supported for this product.
support_emailtrue if e-mail alerts are supported for this product.
support_voicetrue if voice call alerts are supported for this product.