Industries

Products

Developer

Blog

Blog

Querying for historical tropical cyclone data with the Xweather API

9.11.2023//SDKs, Tutorials, API & Mapping

Blog post banner

Access Xweather's historical archive for tropical systems using the tropicalcyclones/archive endpoint.

Lee Huffman

Head of DaaS

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:

Tropical Cyclones within 50 miles of New York, NY

Cyclone NameYear
Tropical Storm Fay2020
Hurricane Irene2011
Hurricane Gordon2000
Hurricane Floyd1999
Hurricane Bertha1996
Tropical Storm Chris1988
Hurricane Gloria1985
Hurricane Belle1976
Hurricane Agnes1972
Tropical Storm Doria1971
UNNAMED1961
Tropical Storm Brenda1960
Hurricane Diane1955
UNNAMED1934
UNNAMED1915
UNNAMED1900
UNNAMED1893
UNNAMED1888
UNNAMED1874
UNNAMED1872
UNNAMED1866

Expand

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.

Tropical Cyclones within 50 miles of Providence, RI

Cyclone NameYear
Hurricane Henri2021
Hurricane Elsa2021
Hurricane Hanna2008
Tropical Storm Hermine2004
Hurricane Charley2004
Hurricane Gordon2000
Hurricane Floyd1999
Hurricane Bertha1996
Tropical Storm Beryl1994
Hurricane Bob1991
Tropical Storm Henri1985
Hurricane Alma1966
Hurricane Cindy1959
Hurricane Carol1954
UNNAMED1944
UNNAMED1934
UNNAMED1916
UNNAMED1915
UNNAMED1908
UNNAMED1907
UNNAMED1902
UNNAMED1896
UNNAMED1894
UNNAMED1888
UNNAMED1888
UNNAMED1879
UNNAMED1876
UNNAMED1872
UNNAMED1869
UNNAMED1861
UNNAMED1858
UNNAMED1851

Expand

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.

Setting the endpoint and action

Setting the endpoint and action

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.

Setting the place

Setting the place

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

Setting a query radius

Setting a query radius

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.

Limiting results

Limiting results

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.

Sorting results

Sorting results

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.

Specifying a time range

Specifying a time range

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

Filtering output

Filtering output

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!

Lee Huffman

Head of DaaS

Related Resources

Related
Resources

Article

Adding custom styling to hurricane maps with the Tropical module

Article

How to display individual tropical cyclones with JavaScript SDKs

=

Next

Outdoor recreation: When weather makes the app