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 Code | Description |
|---|---|
| 200 OK | Success, situation normal |
| 400 Bad Request | The request was unacceptable, often due to a missing required parameter. Please check the documentation for the requested feed type. |
| 401 Unauthorized | No valid authorization provided. Either the access token is missing or expired. |
| 403 Forbidden | 1) 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 Found | The requested resource or ID doesn't exist. Check the response error message for details or contact Support for assistance. |
| 409 Conflict | The request conflicts with a previous request (only for processing requests with unique identifiers) |
| 429 Too Many Requests | Too 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 type | Description |
|---|---|
| obs | Surface weather observations from weather stations around the world, by MADIS station ID. |
| obshistory | Historical weather observations up to one month in advance. |
| place | US place names database & geocoding, including cities, ZIP codes, and all non-historic places in the USGS GNIS. |
| stationlist | Nearby weather station IDs from a latitude/longitude pair or inside a bounding box. |
| forecast | Hourly and daily forecasts up to 7-days for US locations and territories including Hawaii, Alaska, Puerto Rico. |
| alerts | Weather alerts from the National Weather Service. |
| alert_text | Full message body using an alert identifier from the alerts endpoint. |
| skycams | Nearby live weather cameras and cached thumbnail images from the weatherUSA SkyCams database. |
| lsr | Preliminary Local Storm Reports from National Weather Service local offices. |
| aqi | Combined Air Quality Index at a location. |
| uv | Ultraviolet Index estimate at a location. |
| fire | Wild fires within user specified distance of a location. |
| earthquake | Earthquakes 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:
|
| 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 less | Usually not felt, but can be recorded by seismograph. |
| 2.5 to 5.4 | Often felt, but only causes minor damage. |
| 5.5 to 6.0 | Slight damage to buildings and other structures. |
| 6.1 to 6.9 | May cause a lot of damage in very populated areas. |
| 7.0 to 7.9 | Major earthquake. Serious damage. |
| 8.0 or greater | Great earthquake. Can totally destroy communities near the epicenter. |
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]
| Option | Description |
|---|---|
| recipient | Add or update a recipient to your user account |
| alerts | Subscribe recipient to alerts |
| alerts-products | Fetch 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:
|
| 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:
Example: Trigger an alert if the forecast for the next 24 hours at the given location ( Example: Trigger an alert if precipitation is expected in the next 24 hours at the given location ( Example: Trigger an alert if the forecast for the next 96 hours predicts a temperature at location ( |
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.
| id | Product ID |
| name | Product Name |
| type | One 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. |
| description | HTML-formatted description of the alert product. |
| support_sms | true if SMS alerts are supported for this product. |
| support_email | true if e-mail alerts are supported for this product. |
| support_voice | true if voice call alerts are supported for this product. |
