August 28

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  warning and an empty response array.

All tropical cyclones via the hurricane API

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   parameter options. If you need to query by the originating basin, then you should use the   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   or use the basin’s two-letter abbreviation,  .

Likewise, for the West Pacific, you would pass   or  :

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  . 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   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: , 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

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   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   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   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   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:


  1. August 31, 2018 at 5:46 pm

    […] recently introduced the new Hurricane API, including the tropical cyclones endpoint, within our Aeris Weather API. And while real-time, […]

  2. September 1, 2018 at 4:33 am

    […] Aeris API. Here’s an excerpt from one of the weather-tech companies I’m involved with, AerisWeather: “Tropical season has started off busy, at least in the Pacific basin, with Category 4 […]

  3. September 1, 2018 at 7:58 pm

    […] Aeris API. Here’s an excerpt from one of the weather-tech companies I’m involved with, AerisWeather: “Tropical season has started off busy, at least in the Pacific basin, with Category 4 […]

  4. September 10, 2018 at 6:25 pm

    […] the traditional peak of the tropical season underway, we have been busy with the release of the new tropical API addition to the Aeris Weather API and new tropical map layers within the Aeris Maps Platform (AMP). […]

  5. September 11, 2018 at 11:17 pm

    […] been releasing several new products related to tropical cyclones recently, such as our new Aeris Weather API tropical cyclone endpoints and Aeris Maps Platform (AMP) tropical layers. And continuing this trend, we’ve also released […]

  6. September 12, 2018 at 3:50 pm

    Any plans to add to the endpoint, or map layers, to also include model forecasts, to show the popular “spaghetti model” of possible other tracks a system can take? Would also love to see windfields (current and forecast).

    • Lee Huffman
      September 12, 2018 at 4:12 pm

      Thanks for the checking out our new tropical features. You’ll be excited to know that we’re already planning on adding wind fields and forecast models in future updates!

  7. October 4, 2018 at 8:57 pm

    […] provides rich data support for active global tropical systems. You can get all the details in the full rundown of the cool new Tropical Cyclones endpoint blog. With v2.5.0 of the Aeris Android SDK, we’ve baked in the usual support to help get […]

  8. Samuel Mack
    January 1, 2019 at 6:18 am

    Thanks for the information.

  9. July 13, 2019 at 4:30 am

    […] flooding has been (by far) the biggest killer: “…My plan…is to create a plan.” Hurricane season is here. Do you live in Hurricane Alley? Coastal residents bear the brunt of hurricane winds and […]

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.