Querying for Historical Tropical Cyclone Data with the AerisWeather API

As Hurricane Henri approached the Northeastern US this past weekend, I wondered how often a tropical cyclone has come within 50 miles of New York City, Boston, or other cities. How many were hurricanes? To answer these questions, we can use the Tropical Cyclones Archive endpoint within the AerisWeather API. This endpoint provides access to the complete AerisWeather historical archive for tropical systems, with data from the late 1800s for the Atlantic basin and the mid-1900s for the Pacific basin.

When using the tropical cyclones archive endpoint, we find that 21 tropical cyclones have tracked within 50 miles of New York City, NY – the most recent being Tropical Storm Fay in 2020:

The same query performed for Providence, RI, shows us that 32 tropical cyclones have moved within 50 miles of the city, of which Hurricane Henri is the more recent.

The API Query

To find tropical cyclones that tracked within 50 miles of New York City, we will use the closest action:

tropicalcyclones/closest?p=New York,NY&radius=100miles&limit=50&sort=id:-1&from=-100years&to=now&fields=id,profile

Breaking the query down:

tropicalcyclones/archive/closest

Utilize the closest action with the tropical cyclone archive endpoint. The API will return the systems that tracked closest to the requested location, sorted by the closest cyclone to the furthest cyclone track.

p=New York,NY

Provide the place/location to query the archive for the closest cyclone tracks. The location can be “city, state”, “latitude, longitude”, a zip code, or any other API-supported place format.

radius=100miles

The radius, or maximum distance from the requested location, is used to compare tropical cyclone tracks. This value can be in miles, kilometers, meters, or any of the API’s supported distance units.

limit=50

The API defaults to returning a single response (limit=1) for most endpoints, so it’s good practice to pass a limit. The tropical cyclone endpoint will return a maximum of 50 results per query. For our purposes, most locations will have less than 50 nearby cyclones, and for those with more than 50, returning the closest 50 will be sufficient.

If there are more than 50 results and you require them all, you can make multiple queries to step (page) through the results, adding the skip parameter. As the API fetches 50 cyclones at a time, you know all have been fetched if/when the API returns less than 50.

sort=id:-1

The closest action will return results based on distance from closest to furthest. In this example, we care less about distance since we look at all systems that have tracked within 50 miles of our specified location. This parameter will sort based on the storm ID in descending order, thus returning the most recent systems first.

from=1900-01-01&to=now

Here we are specifying a time range to utilize when querying the archive. If no time range is provided, the API will utilize the past year, i.e., from=-1year&to=now, by default.

Since the AerisWeather archive includes cyclones since the 1940s, using a start date of Jan 1, 1900 through to the current date/time will query against the entire archive.

If you’d prefer a more limited date range such as the last 20 years, you can use: from=-20years&to=now

Or, if you prefer to look at systems from 2000-2020, use from=2000-01-01&to=2020-12-31

fields=id, profile

Cyclones may include a lot of information, and it’s often best to limit the results to the items needed. In our example, we limit the cyclone and the cyclone’s profile, including the name, lifespan, maximum wind speeds, and more.

Where To Go From Here?

Querying the API for tropical cyclone data is simple and powerful. The tricky part comes with implementing the data in a user interface. Stay tuned for our next segment, which will demonstrate how to query the tropical cyclones endpoint using the JavaScript SDK to enter a location, find tropical cyclones, and display them in a tabular view.

In the meantime, check out the AerisWeather API and the tropical cyclone endpoints – you can sign up for a free developer account to get started. Happy coding!

Share this post: