Querying the Xweather hurricane API endpoint

This blog will be part of a series of entries discussing tropical cyclones. First off, we'll concentrate on the features of the tropical cyclones endpoint, available through the Xweather API as a part of Xweather Flex subscriptions.

The tropical season of 2018 — when our tropical cyclones endpoint was first released — started with a boom, with Category 4 Hurricane Hector, Category 5 Hurricane Lane, and Super Typhoon Maria taking the Pacific basin by storm. The launch of the endpoint was timely then, and it's only become a more crucial part of severe weather preparedness for businesses in threatened areas since.

The tropical cyclone endpoint, available with the Xweather API, allows users to query global tropical cyclone information — and users can also leverage raster maps and MapsGL to create stunning hurricane and typhoon visuals.

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 know 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 and East and Central Pacific are called hurricanes, whereas in the West Pacific, they're referred to as typhoons.

Credit UK Met Office

Tropical cyclones tend to occur during a specified season when environmental factors are more favorable. Tropical cyclone seasons depend on the basin in question. A few of note:

• 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

• In the Southern Hemisphere basin, the season starts November 1st and runs through April 30th

About the tropical cyclones endpoint

The tropical cyclones endpoint 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 to any Xweather Flex subscriber, and can also be accessed in our free 30-day Flex trials.

tropicalcyclones 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 that include 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 query string 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, 2018's 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. This can be accomplished using the query parameter. The following example will return 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 tropicalcyclones endpoint 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 Xweather API's supported places formats can be used, including city, US zip code, and latitude/longitude.

Nearby via forecast

While the above example will find nearby storms based on their current position, you can also obtain active cyclones that are forecasted 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 Xweather API is the ability to obtain cities within this error cone via the affects action. The cities returned are 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, you'll 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.

Add tropical cyclones to your applications this hurricane season

The Xweather tropical cyclone endpoint is a great addition in a number of applications and is available to all Xweather Flex users. Test it out for yourself with our free 30-day trial. Happy coding!