Querying for historical tropical cyclone data with the Xweather API

Our powerful tropicalcyclones/archive endpoint provides access to the complete Xweather 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 tropicalcyclones/archive, 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.

Building your API query

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

Now let's break down the above API query and examine what each part is doing so you can easily start creating your own custom queries.

When using the closest action with the tropical cyclone archive, the API will return systems that tracked closest to the requested location, sorted by closest to furthest track from the location in question.

Note that when providing the place/location to query for the closest historical cyclone tracks, the location can be any of the following:

• City, state

• Latitude, longitude

• Zip code

• Any other API-supported place format

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 another of the API’s supported distance units.

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 page through the results by adding the skip parameter to your querying method. As the API fetches 50 cyclones at a time, you know that all have been fetched if/when the API returns less than 50.

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.

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

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.

What's next?

Querying the API for tropical cyclone data is simple and powerful. The truly inspiring part comes with implementing the data into your user interface. Use our other tropical-focused tutorials - linked below - to create and customize tropical queries and maps to fit your specific needs.

Check out our tropical cyclone endpoints using the Xweather API – you can sign up for a free developer account to get started. Happy coding!