Skip to content

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 an access token (key). All requests must operate over HTTPS to provide security for the key and to protect private or restricted data. Never embed your account or server key in a client-facing program, such as JavaScript code. Use public keys for this purpose and restrict usage to your domain name(s). Authorize requests by placing the access token from your Account Settings in an HTTP Header:

Authorization: Bearer [access token]

Response codes and errors

HTTP Status CodeDescription
200 OKSuccess, situation normal
400 Bad RequestThe request was unacceptable, often due to a missing required parameter. Please check the documentation for the requested feed type.
401 UnauthorizedNo valid authorization provided. Either the access token is missing or expired.
403 Forbidden1) This feed/endpoint is not available to this account's access level;
2) The given API key or client domain have been blocked
404 Not FoundThe requested resource or ID doesn't exist. Check the response error message for details or contact Support for assistance.
409 ConflictThe request conflicts with a previous request (only for processing requests with unique identifiers)
429 Too Many RequestsToo many recent requests to the API using this key and calls 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.

Endpoints

The base Weather API URL is:

https://api.weatherusa.net/[version]/[endpoint]

Versioning

The current version of the API is:
v1.1 (2017-12-04)

weatherUSA will support all subversions of the most current version (e.g. 2.0-2.9 for v2) and the last 3 subversions of the previous version (e.g. 1.1-1.4 of v1).

Endpoint List

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.
fireWild fires within user specified distance of a location.
earthquakeEarthquakes within user specified distance of a location.

Feed type: obs

Example URL

https://api.weatherusa.net/v1/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/v1/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/v1/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/v1/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/v1/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/v1.2/alerts?q=39.937,-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/v1/alert_text?id=46101549

Attributes

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

Feed type: tropical

Example URL

https://api.weatherusa.net/v1.2/tropical?storm=active

Attributes

storm
required
Storm ID (BASSYYYY) or active for current tropical cyclones worldwide
"BA" is the 2-letter ocean basin ID: AT (North Atlantic), EP (Eastern Pacific), CP (Central Pacific), WP (West Pacific), IO (Indian Ocean), SH (Southern Hemisphere/Australia), LS (South Atlantic)
"SS" is the 2-digit storm ID starting from "00"
"YYYY" is the year the storm first began
Storm IDs follow the same numbering conventions as the NHC and JTWC.
records
optional
Record IDs to return, currently NULL or latest to filter just the latest cyclone observation for each storm.
models
optional
(Sunrise API access or higher)
Fetch latest computer model forecasts, contains all recently available model runs for this storm with track and data points in GeoJSON.

Feed type: skycams

Example URL

https://api.weatherusa.net/v1/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/v1/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/v1.2/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/v1/uv?q=40.00,-83.02

Attributes

q
required
Coordinates, decimal in the format latitude,longitude

Feed type: fire

Example URL

https://api.weatherusa.net/v1/fire?state=CA&acres=20000

Attributes

q
optional
Coordinates, decimal in the format latitude,longitude
radius
optional
max distance from wildfire to coordinates (meters). q required to use radius.
state
optional
return data by state (2-character abbrevation). Cannot be used with q.
acres
optional
minimum fire area in acres (approx. 0.4 ha)
cause
optional
Natural, Human, or Unknown
perimeters
optional
Boolean true or false. Default false. Whether to include fire boundary Polygons in the GeoJSON response, if available. If available, feature geometry will become a GeometryCollection containing the fire report point and fire boundary.

Feed type: earthquake

Example URL

https://api.weatherusa.net/v1/earthquake?q=40.09,-122.67&radius=200000&time=7d&magnitude=2.5

Attributes

q
optional
Coordinates, decimal in the format latitude,longitude
radius
optional
max distance from earthquake epicenter to coordinates (meters). q required to use radius.
time
optional
Time range to fetch earthquakes before current time. Use "s" suffix for seconds, "h" for hours, and "d" for days (e.g. "24h")
magnitude
optional
minimum magitude of earthquakes
Magnitude Earthquake effects
2.5 or lessUsually not felt, but can be recorded by seismograph.
2.5 to 5.4Often felt, but only causes minor damage.
5.5 to 6.0Slight damage to buildings and other structures.
6.1 to 6.9May cause a lot of damage in very populated areas.
7.0 to 7.9Major earthquake. Serious damage.
8.0 or greaterGreat earthquake. Can totally destroy communities near the epicenter.
Earthquake Magnitude Scale from UPSeis

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.