Hurricane API now Available in the AerisWeather API

Tropical season has started off busy, at least in the Pacific basin, with Category 4 Hurricane Hector, Category 5 Hurricane Lane, and Super Typhoon Maria. The peak of the Atlantic and East Pacific tropical seasons are only a couple weeks away, so we are excited to announce the release of tropical cyclone support within the AerisWeather API.   The new tropical cyclone endpoints create a great hurricane API that includes global tropical cyclone information within both the AerisWeather API and our AerisWeather Mapping Platform (AMP).

This blog will be part of a series of entries discussing hurricanes, typhoons, tropical storms and other tropical cyclones. First off, we’ll concentrate on the new tropical cyclone endpoint within the AerisWeather API.

What are Tropical Cyclones?

As stated by the National Hurricane Center, a tropical cyclone is a rotating, organized system of clouds and thunderstorms that originates over tropical or subtropical waters and has a closed low-level circulation. We often hear of these systems as tropical storms, hurricanes, and typhoons. Per NOAA, the difference between a hurricane and a typhoon is the region where it occurs. Intense tropical cyclones within the Atlantic, East and Central Pacific are called hurricanes, whereas they’re referred to as typhoons in the West Pacific.

Tropical cyclones tend to occur during a specified season when environmental factors and more favorable. In the Atlantic basin, the season extends from June 1st through November 30th. For the East Pacific, the season runs from May 15th through November 30th. The tropical season in the Southern Hemisphere basin starts November 1st and runs through April 30th.

Tropical Cyclones Endpoint

The first endpoint of the new hurricane API is the tropical cyclones endpoint and provides information on active global tropical systems, including hurricanes, typhoons, tropical storms and tropical depressions. The endpoint uses data from both the National Hurricane Center (NHC) and the Joint Typhoon Warning Center (JTWC). This endpoint is available for use by AerisWeather API Premium users, as well as the free developer trials.

This endpoint returns a variety of information, such as latest reported position, previous track, forecast track and forecast error cone for active tropical cyclones. Additionally, systems in the Atlantic, East Pacific and Central Pacific may include coastal alerts, known as advisory breakpoints, if the storm may affect nearby coasts. The endpoint documentation provides a full breakdown of the available response properties.

Fetching Active Tropical Cyclones

Fetching active storms is as simple as calling the endpoint directly without specifying an action. Within the tropical cyclone documentation, we label this the :all action.

This query will return all active cyclones across the globe. If there are no active cyclones, the API will return a warn_no_data warning and an empty response array.

Fetching Cyclones by Basin

Tropical systems are grouped into basins including the Atlantic, East Pacific (western coast of North America), Central Pacific (including Hawaii), West Pacific (eastern coast of Asia), Indian Ocean and the Southern Hemisphere/Southern Pacific (including Australia).

The API includes the ability to obtain cyclones by one or more basins using the available filter  parameter options. If you need to query by the originating basin, then you should use the query  parameter.

Cyclones by Basin Using Filters

You can pass one or more basin filters to the API. For example, to obtain all active systems within the Atlantic basin, you would use filter=atlantic  or use the basin’s two-letter abbreviation, filter=al .

Likewise, for the West Pacific, you would pass filter=westpacific  or filter=wp :

You can also fetch active cyclones from more than one basin by separating the basin names or codes with a semicolon. To obtain active storms in either the Atlantic or the East Pacific basins:

A semicolon within the AerisWeather API acts as a logical OR . Therefore, we are asking the API for active cyclones that are currently located in the Atlantic or the East Pacific basin in the above example.

Active Cyclones by Originating Basin

Within the Pacific, a storm may cross into two or three basins. For instance, this year Hurricane Lane started in the Eastern Pacific then moved into the Central Pacific to affect Hawaii. Because of this, you may prefer to query storms based on the basin they originated within. The API allows for this using the query  parameter. The following example will active storms that originated within the Eastern Pacific even if they may currently be within another basin:

Querying by Cyclone ID

Each tropical cyclone has an individual cyclone identifier, which follows the format: YEAR-BASIN-EVENTNUMBER, where:

• YEAR is the tropical season year of the storm
• BASIN is the originating basin for the storm
• EVENTNUMBER is the event number of the storm in the originating basin which increases incrementally with each new tropical cyclone

For example, Hurricane Lane has the cyclone ID of 2018-EP-15

To query a tropical cyclone directly, just pass the cyclone’s unique identifier to the endpoint:

Nearby Active Tropical Systems

A unique feature of the hurricane API is the ability to query by a location and obtain any tropical systems that are nearby. The feature can be advantageous when a tropical cyclone is near coastal areas.

Nearby via Current Position

The following query would return any active cyclones whose current positions are within 300 miles of Miami, Florida:

Any of the AerisWeather API’s supported location formats can be used, including city, US zip code and latitude/longitudes.

Nearby via Forecast

While the above example will find nearby storms based on their current position, you can also obtain active cyclones that are forecast to move within a specific radius of a location. To do so, just add filter=forecast  to your request:

This query will return all active systems that are forecast to move within 300 miles of Miami, Florida.

Cities within the Error Cone

Active tropical cyclones will normally have a forecast track and associated forecast error cone. Another unique feature of the AerisWeather API is the ability to obtain cities within this error cone via the affects  action. The cities returned or sorted descending based on population.

This feature is very useful when a storm is expected to move over land, as you can obtain the cities within the error cone. For this feature you need to pass in the storm identifier:

If you want to return cities with a minimum estimated population, add query=pop:#  where #  is the minimum population. The following will return up to 100 cities with a minimum population of 100,000 that are within the requested cyclone’s forecast error cone:

If the tropical cyclone is not forecast to move over land, there are no cities within the error cone and the API will return a warn_no_data  warning and an empty response array.

Start Adding Tropical Cyclones to Your Apps!

The new tropical cyclone endpoint is a great addition and is available to all AerisWeather API Premium users. If you’re not yet a subscriber, try out the new hurricane API with our free developer trial.

Share this post: