Endpoint: advisories/summary

The advisories/summary endpoint provides an overall summary of the currently active advisories within the USA and Canada based on search/filter criteria. Example use cases include obtaining the total number of active weather zones or counties with active advisories, the types of active advisories,  what states currently have active advisories and more. Coverage area includes the 50 US states, Puerto Rico and Canada.

https://api.aerisapi.com/advisories/summary

Data CoverageUSA, Canada

Included With API Developer,  API Premium

Supported Advisory Types

Please refer to the full list of available advisories, type and color codes:
http://www.aerisweather.com/support/docs/aeris-overlays/reference/advisory-types/

The advisory type codes may be passed in the type element of the query parameter and correspond to the details.type in the response output.

Supported Actions

The following actions are supported with the advisories/summary endpoint:

:id Requesting data by using the :id action is used for returning data for a particular item that has an ID associated with it. This is the primary method for requesting general weather information for a single location (observations, forecasts, advisories, etc.) as the location's name or a zip code serves as the id. Other endpoints may expect a certain value for the ID, such as storm cells whose ID value is a combination of the radar site identifier and unique identifier assigned to every storm cell. Refer to an enpoint's detailed documentation for specific information regarding how to use the :id action.
search The search action is used as a more general query method and expects the query to be defined with the custom query for the request. Unlike the closest action, results will not be returned in any particular order.
within The within action allows for returning data within a variety of different geometrical regions. Currently supported geometries include a circle (requires a center point and radius), square (requires two coordinate points defining the top-left and bottom-right corners) and polygon (requires at least three coordinate points). Unlike the closest action, the results will not be returned in any particular order based on distance.

Supported Parameters

The following parameters are options unless otherwise noted:

callback callback=:functionName Used with JSONP implementation.

Defines the callback function to use for the response. The response will be enclosed as C(response), where C is the callback function provided.
fields fields=:string Provides a comma separated list of values for the API to return. This parameter is often used to limit the amount of data returned. See Reducing Output.
filter filter=:string Predefined filters for limiting the results. The filter value can be a single, comma-delimited or a semicolon delimited string of filter names.
limit limit=:total The total number of results to return as an integer. Each endpoint may have a set maximum for this value depending on usage.

The default limit is 1 if not specified.
query query=:string Used to filter results based on certain fields in the data set. See Advanced Queries for more details.
radius radius=:distance:unit When requesting the closest results within a circle, the radius determines how far from the specified location to search. A valid unit value must be included in your radius value, e.g., "5mi", "10km", "25miles". If no unit is provided, your value is assumed to be in meters by default.

Most endpoints utilize a default radius of 50 miles, though some endpoints, such as lightning, may have tighter restrictions specified.

Supported Filters

The following filters can be passed to the filter parameter to reduce the results that are returned:

county Some advisories such as Tornado warnings, severe thunderstorm warnings, flash flood warnings, flood warnings are issued county based, but include a small polygon of the coverage area within the county that is being affected. By default, if this small polygon exists, the API will only return the advisory, if the requested latitude/longitude is within the provided small polygon.

Using the filter=county option will make the API ignore any small polygon within the warning and return the warning based on the larger county coverage area.
warning Returns all warnings.

A warning is issued when a hazardous weather or hydrologic event is occurring, imminent, or likely. A warning means weather conditions pose a threat to life or property. People in the path of the storm need to take protective action.
watch Returns all watches.

A watch is used when the risk of a hazardous weather or hydrologic event has increased significantly, but its occurrence, location, or timing is still uncertain. It is intended to provide enough lead time so those who need to set their plans in motion can do so. A watch means that hazardous weather is possible. People should have a plan of action in case a storm threatens and they should listen for later information and possible warnings especially when planning travel or outdoor activities.
advisory Returns all advisories.

An advisory is issued when a hazardous weather or hydrologic event is occurring, imminent, or likely. Advisories are for "less serious" conditions than warnings that may cause significant inconvenience, and if caution is not exercised could lead to situations that may threaten life or property.
outlook Returns all outlooks.

An outlook is issued daily to indicate that a hazardous weather or hydrologic event may occur in the next several days. The outlook will include information about potential severe thunderstorms, heavy rain or flooding, winter weather, extremes of heat or cold, etc., that may develop over the next 7 days with an emphasis on the first 24 hours of the forecast. It is intended to provide information to those who need considerable lead time to prepare for the event.
statement Returns all special weather statements.
severe Returns all severe-related advisories:
- severe thunderstorm
- tornado
flood Returns all flood/hydro-related advisories:
- debris flow
- flood, flash flood
- hydrologic
tropical Returns all tropical-related advisories:
- tropical storm, hurricane, typhoon
- tropical storm wind
- hurricane wind
- extreme wind
winter Returns all winter-related advisories:
- blizzard, winter storm, winter weather
- snow, heavy snow
- lake effect snow
- snow and blowing snow
- ice pellets, freezing rain, ice storm
- wind chill
marine Returns all marine/coastal-related advisories:
- marine
- freezing spray, heavy freezing spray
- small craft
- small craft for winds
- small craft for hazardous seas
- small craft for rough bar
- gale
- hazardous seas
- hurricane force winds
- lakeshore flood
- coastal flood, high surf
- tsunami
- low water
- dense fog, dense smoke, ashfall (marine)
nonprecip Returns all non-precipitation-related advisories:
- blowing dust/dust storm
- wind, high wind, lake wind
- dense smoke
- dense fog, freezing fog
- freeze, frost
- heat, excessive heat, extreme cold
forecast Returns forecasts, normally short-term forecasts.
all Return all warnings, watches, advisories, statements, outlooks and forecasts.
wind Returns wind-related advisories.
fire Returns fire-related advisories.
tsunami Returns tsunami-related advisories.
beach Returns beach-related alerts, such as rip current statements.
now Returns advisories that are currently in effect.
synopsis Returns a synopsis of the advisories.
tornado Returns tornado related advisories (Tornado watches/warnings)
emergency Returns emergency-specific advisories.
canada Returns only Canadian alerts. Equivalent to query=country:ca
usa Returns only USA alerts. Equivalent to query=country:us
allcountries Returns alerts for all countries (the default).
hassmallpoly Returns alerts that have a small polygon (US severe thunderstorm, tornado, flash flood etc)
distinct Returns a summary based on counting alerts issued for multiple locations once.

Supported Query Properties

Use the following supported property keys when creating custom queries for your requests:

type Used to query the advisory type. The value should be set to the VTEC Code or the WMO if no VTEC code exists. Review the list of allowed Advisory Types.

Examples:
/advisories/minneapolis,mn?query=type:TO.W will return only the tornado warnings
/advisories/minneapolis,mn?query=type:TO.W;type:NOW will return tornado warnings and short-term forecasts
wxzone Used to query by the zone id the alert is issued for. Normally will be a NOAA public weather zone that looks similar to: VAZ014 or if issued for a specific county : VAC023
state Used to query by state, useful for requesting all advisories for a specific state. Two letter, lower case state abbreviation.
sig Used to query by the one character coded significance of an advisory type.
W = Warning
A = Watch
Y = Advisory
S = Statement
O = Outlook
F = Forecast

Examples:
/advisories/minneapolis,mn?query=sig:W,sig:A (returns only warnings and advisories for Minneapolis, MN)
sigp Used to query by the numeric representation of an advisory type. A lower number has higher significance.
1 = Warning
3 = Watch
5 = Advisory
7 = Statement
9 = Forecast (Short term)
11 = Outlook

Examples:
/advisories/minneapolis,mn?query=sigp:1:3 (returns only warnings and advisories for Minneapolis, MN)
name County name or weather zone name (lowercase) of the location the advisory has been issued for.
country Two letter country abbreviation (lowercase) of the location the advisory was issued for. (US only)
issued Used to query by the date the alert is issued for.
expires Used to query by the date the alert is scheduled to expire.
active Used to query active or inactive advisories.
0 = not active
1 = active
By default the API will not return in active advisories

Examples:
/advisories/minneapolis,min?query=active:0:0 (returns only warnings and advisories that are no longer active for Minneapolis, MN)
emergency Used to query emergency specific advisories, such as tornado emergencies.
true = emergency specific advisories
false = non emergency specific advisories
issued Used to query alerts based on the issued time. Values can be relative formats or dates. Times are not currently supported.

Examples:
/advisories/minneapolis,mn?query=issued:-10minutes&limit=100 (returns alerts issued within the past 10 minutes for Minneapolis, MN)
begins Used to query alerts based on the begins time of the alert. Some alerts such as winter storm warnings may be issued now, but do not go into effect until several hours later.
Values can be relative formats or dates. Times are not currently supported.

Examples:
/advisories/minneapolis,mn?query=begins:-6hours:6hours&limit=100 (returns active alerts that either went into effect in the past six hours or are set to go live in the next 6 hours for Minneapolis, MN)
expires Used to query alerts based on the expiration time. Values can be relative formats or dates. Times are not currently supported.

Examples:
/advisories/minneapolis,mn?query=expires:10minutes&limit=100 (returns alerts set to expire within the next 10 minutes for Minneapolis, MN)
added Used to query alerts based on the time they were added to the API database. Values can be relative formats or dates. Times are not currently supported.

Examples:
/advisories/minneapolis,mn?query=added:-10minutes&limit=100 (returns alerts received and added within the last 10 minutes for Minneapolis, MN)

Examples

The /[endpoint]/[action]? portion within the query template below can be exchanged with any of the examples. Also, please note you will need to input your client credentials in the [ID] and [SECRET] fields which can be found under the Apps section of the members area.

https://api.aerisapi.com/[endpoint]/[action]?client_id=[ID]&client_secret=[SECRET]

Return a summary for all active warnings, watches and advisories.
/advisories/summary?

Return a summary for all active warnings, watches and advisories within the state of Minnesota
/advisories/summary/search?query=state:mn&

Return a summary for all active warnings, watches and advisories within the state of Minnesota or Wisconsin.
Note the semicolon is used to represent a logical 'OR'.
/advisories/summary/search?query=state:mn;state:wi&

Return a summary for all active warnings, watches and advisories within a 50 mile radius of Minneapolis, MN
/advisories/summary/minneapolis,mn?

Return a summary for all active warnings, watches and advisories within a 100 mile radius of Minneapolis, MN
/advisories/summary/minneapolis,mn?radius=100miles&

Return a summary for all severe thunderstorm and tornado watches/warnings.
/advisories/summary/?filter=severe&

Return a summary for all watches, warnings and advisories for severe or flood related events.
Note the semicolon is used to represent a logical 'OR'.
/advisories/summary/?filter=severe;flood&

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.


{
   "summary":{
      "count":181,
      "states":[
         "ar",
         "az",
         "ca",
         "ct",
         "fl",
         "gu",
         "id",
         "il",
         "in",
         "la",
         "mi",
         "mn",
         "nv",
         "or",
         "pr",
         "tn",
         "tx",
         "wa",
         "wi"
      ],
      "typeCodes":[
         "EH.W",
         "FF.W",
         "FL.W",
         "FA.W",
         "FW.W",
         "FW.A",
         "FL.Y",
         "FA.Y",
         "HT.Y",
         "SU.Y",
         "LW.Y",
         "HY.S",
         "BH.S",
         "FFW",
         "AQA"
      ],
      "types":[
         {
            "type":"EXCESSIVE HEAT WARNING",
            "code":"EH.W",
            "count":13,
            "states":[
               "or",
               "wa"
            ],
            "zones":[
               "ORZ003",
               "ORZ004",
               "ORZ005",
               "ORZ006",
               "ORZ007",
               "ORZ008",
               "ORZ010",
               "ORZ012",
               "ORZ013",
               "WAZ504",
               "WAZ509",
               "WAZ511",
               "WAZ512"
            ]
         },
         {
            "type":"FLASH FLOOD WARNING",
            "code":"FF.W",
            "count":4,
            "states":[
               "ar"
            ],
            "zones":[
               "ARC031",
               "ARC055",
               "ARC075",
               "ARC121"
            ]
         },
         {
            "type":"FLOOD WARNING",
            "code":"FL.W",
            "count":51,
            "states":[
               "ar",
               "fl",
               "il",
               "in",
               "la",
               "mi",
               "mn",
               "tx"
            ],
            "zones":[
               "ARC011",
               "ARC013",
               "ARC027",
               "ARC063",
               "ARC067",
               "ARC075",
               "ARC121",
               "ARC139",
               "ARC145",
               "ARC147",
               "FLC115",
               "ILC025",
               "ILC051",
               "ILC055",
               "ILC059",
               "ILC077",
               "ILC159",
               "ILC185",
               "ILC199",
               "INC027",
               "INC051",
               "INC071",
               "INC083",
               "INC089",
               "INC091",
               "INC093",
               "INC111",
               "INC125",
               "INC141",
               "INC149",
               "INC175",
               "LAC001",
               "LAC003",
               "LAC005",
               "LAC019",
               "LAC033",
               "LAC039",
               "LAC053",
               "LAC055",
               "LAC063",
               "LAC079",
               "LAC097",
               "LAC099",
               "LAC113",
               "LAC119",
               "MIC077",
               "MNC019",
               "MNC053",
               "MNC171",
               "TXC321",
               "TXC481"
            ]
         },
         {
            "type":"FLOOD WARNING",
            "code":"FA.W",
            "count":20,
            "states":[
               "la",
               "nv",
               "wi"
            ],
            "zones":[
               "LAC001",
               "LAC005",
               "LAC023",
               "LAC033",
               "LAC039",
               "LAC045",
               "LAC047",
               "LAC053",
               "LAC055",
               "LAC063",
               "LAC077",
               "LAC093",
               "LAC095",
               "LAC097",
               "LAC099",
               "LAC113",
               "LAC121",
               "NVC003",
               "WIC011",
               "WIC121"
            ]
         },
         {
            "type":"RED FLAG WARNING",
            "code":"FW.W",
            "count":33,
            "states":[
               "ca",
               "or",
               "wa"
            ],
            "zones":[
               "CAZ253",
               "CAZ254",
               "CAZ255",
               "CAZ256",
               "CAZ258",
               "CAZ259",
               "CAZ260",
               "CAZ261",
               "CAZ262",
               "ORZ601",
               "ORZ602",
               "ORZ603",
               "ORZ604",
               "ORZ605",
               "ORZ606",
               "ORZ607",
               "ORZ608",
               "ORZ612",
               "WAZ601",
               "WAZ602",
               "WAZ604",
               "WAZ650",
               "WAZ652",
               "WAZ653",
               "WAZ654",
               "WAZ655",
               "WAZ656",
               "WAZ657",
               "WAZ658",
               "WAZ659",
               "WAZ660",
               "WAZ661",
               "WAZ675"
            ]
         },
         {
            "type":"FIRE WEATHER WATCH",
            "code":"FW.A",
            "count":10,
            "states":[
               "or",
               "wa"
            ],
            "zones":[
               "ORZ625",
               "WAZ650",
               "WAZ652",
               "WAZ654",
               "WAZ655",
               "WAZ656",
               "WAZ657",
               "WAZ658",
               "WAZ659",
               "WAZ661"
            ]
         },
         {
            "type":"FLOOD ADVISORY",
            "code":"FL.Y",
            "count":2,
            "states":[
               "mi"
            ],
            "zones":[
               "MIC065",
               "MIC077"
            ]
         },
         {
            "type":"FLOOD ADVISORY",
            "code":"FA.Y",
            "count":10,
            "states":[
               "az",
               "tn",
               "tx",
               "wi"
            ],
            "zones":[
               "AZC019",
               "TNC033",
               "TNC075",
               "TNC097",
               "TNC113",
               "TXC009",
               "TXC023",
               "TXC503",
               "WIC053",
               "WIC081"
            ]
         },
         {
            "type":"HEAT ADVISORY",
            "code":"HT.Y",
            "count":13,
            "states":[
               "ca",
               "or",
               "wa"
            ],
            "zones":[
               "CAZ080",
               "CAZ081",
               "ORZ001",
               "ORZ002",
               "ORZ014",
               "ORZ023",
               "ORZ024",
               "ORZ025",
               "ORZ026",
               "WAZ021",
               "WAZ507",
               "WAZ516",
               "WAZ517"
            ]
         },
         {
            "type":"HIGH SURF ADVISORY",
            "code":"SU.Y",
            "count":4,
            "states":[
               "gu"
            ],
            "zones":[
               "GUZ001",
               "GUZ002",
               "GUZ003",
               "GUZ004"
            ]
         },
         {
            "type":"LAKE WIND ADVISORY",
            "code":"LW.Y",
            "count":1,
            "states":[
               "id"
            ],
            "zones":[
               "IDZ021"
            ]
         },
         {
            "type":"HYDROLOGIC STATEMENT",
            "code":"HY.S",
            "count":1,
            "states":[
               "il"
            ],
            "zones":[
               "ILC101"
            ]
         },
         {
            "type":"STATEMENT",
            "code":"BH.S",
            "count":3,
            "states":[
               "ca"
            ],
            "zones":[
               "CAZ040",
               "CAZ041",
               "CAZ043"
            ]
         },
         {
            "type":"",
            "code":"FFW",
            "count":4,
            "states":[
               "pr"
            ],
            "zones":[
               "PRC071",
               "PRC081",
               "PRC115",
               "PRC131"
            ]
         },
         {
            "type":"AIR QUALITY ALERT",
            "code":"AQA",
            "count":12,
            "states":[
               "ca",
               "ct",
               "id"
            ],
            "zones":[
               "CAC019",
               "CAC029",
               "CAC031",
               "CAC039",
               "CAC047",
               "CAC077",
               "CAC099",
               "CAC107",
               "CTZ009",
               "CTZ010",
               "IDC013",
               "IDC025"
            ]
         }
      ]
   }
}
								

Response Properties

The following properties will be provided in every response object:

summary (object) Object containing the summary
summary.count (number) The total number of weather zones or FIPS that have active warnings, watches or advisories.
summary.states (array) Array of two letter US state abbreviations or Canadian province in the format of "ca.xx", that have active warnings, watches or advisories
summary.typeCodes (array) Array of active VTEC or WMO (if no VTEC) codes for the active warnings, watches, advisories.

Please refer to the full list of available advisories, type and color codes:
http://www.aerisweather.com/support/docs/aeris-overlays/reference/advisory-types/
summary.types (array) Array of each active advisory type, with summary information for each
summary.types[#].type (string) The advisory type name
summary.types[#].code (string) The VTEC or WMO (if no VTEC) codes for the advisory

Please refer to the full list of available advisories, type and color codes:
http://www.aerisweather.com/support/docs/aeris-overlays/reference/advisory-types/
summary.types[#].count (number) The total number of weather zones or FIPS that the advisory is active within.
summary.types[#].states (array) Array of two letter US state abbreviations or Canadian province in the format of "ca.xx",that the advisory is active within
summary.types[#].zones (array) Array of NOAA public weather zones and/or FIPS codes that the advisory is active within.