Weather - Get Tropical Storm Forecast

Service:: Maps

API Version:: 1.1

Use to get a list of tropical storms forecasted by national weather forecasting agencies.

The Get Tropical Storm Forecasts API is an HTTP GET request that returns individual government-issued tropical storm forecasts. Information about the forecasted tropical storms includes, location, status, date the forecast was created, window, wind speed and wind radii.

GET https://atlas.microsoft.com/weather/tropical/storms/forecasts/json?api-version=1.1&year={year}&basinId={basinId}&govId={govId}

With optional parameters:

GET https://atlas.microsoft.com/weather/tropical/storms/forecasts/json?api-version=1.1&year={year}&basinId={basinId}&govId={govId}&unit={unit}&details={details}&radiiGeometry={radiiGeometry}&windowGeometry={windowGeometry}

URI Parameters

Name	In	Required	Type	Description
format	path	True	JsonFormat	Desired format of the response. Only `json` format is supported.
api-version	query	True	string	Version number of Azure Maps API.
basinId	query	True	basinId	The `basinId` enum categorizes the different ocean basins where tropical storms can originate. Each basin is assigned a unique identifier to help specify the location of the storm's origin.
govId	query	True	integer (int32)	Government storm Id
year	query	True	integer (int32)	Year of the cyclone(s)
details	query		boolean	When true, wind radii summary data is included in the response
radiiGeometry	query		boolean	When true, wind radii summary data and geoJSON details are included in the response
unit	query		WeatherDataUnit	Specifies to return the data in either metric units or imperial units. Default value is metric.
windowGeometry	query		boolean	When true, window geometry data (geoJSON) is included in the response

Request Header

Name	Required	Type	Description
x-ms-client-id		string	Indicates the account intended for use with the Microsoft Entra ID security model. This unique ID for the Azure Maps account can be obtained from the Azure Maps management plane Account API. For more information on using Microsoft Entra ID security in Azure Maps, see Manage authentication in Azure Maps.

Responses

Name	Type	Description
200 OK	StormForecastResult	OK
Other Status Codes	ErrorResponse	An unexpected error occurred.

Security

AADToken

These are the Microsoft Entra OAuth 2.0 Flows. When paired with Azure role-based access control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.

To implement scenarios, we recommend viewing authentication concepts. In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.

Notes

This security definition requires the use of the x-ms-client-id header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the Maps management API.

The Authorization URL is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Microsoft Entra ID configurations. * The Azure role-based access control is configured from the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs. * Usage of the Azure Maps Web SDK allows for configuration based setup of an application for multiple use cases.

For more information on Microsoft identity platform, see Microsoft identity platform overview.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

This is a shared key that is provisioned when you Create an Azure Maps account in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.

With this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.

For publicly exposed applications, our recommendation is to use the confidential client applications approach to access Azure Maps REST APIs so your key can be securely stored.

Type: apiKey
In: query

SAS Token

This is a shared access signature token is created from the List SAS operation on the Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.

With this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.

For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the Map account resource to limit rendering abuse and regularly renew the SAS Token.

Type: apiKey
In: header

Examples

Get Tropical Storm Forecasts

Sample request

HTTP

GET https://atlas.microsoft.com/weather/tropical/storms/forecasts/json?api-version=1.1&year=2021&basinId=NP&govId=2

Sample response

Status code:: 200

{
  "results": [
    {
      "dateTime": "2021-04-25T06:00:00+00:00",
      "initializedDateTime": "2021-04-24T18:00:00+00:00",
      "location": {
        "latitude": 22,
        "longitude": 137.8
      },
      "maxWindGust": {
        "value": 92.6,
        "unit": "km/h",
        "unitType": 7
      },
      "sustainedWind": {
        "value": 74.1,
        "unit": "km/h",
        "unitType": 7
      },
      "status": "Tropical Storm",
      "window": {
        "left": {
          "latitude": 22.56387,
          "longitude": 137.739517
        },
        "right": {
          "latitude": 21.4361,
          "longitude": 137.860489
        }
      }
    },
    {
      "dateTime": "2021-04-25T18:00:00+00:00",
      "initializedDateTime": "2021-04-24T18:00:00+00:00",
      "location": {
        "latitude": 23.7,
        "longitude": 142.4
      },
      "maxWindGust": {
        "value": 92.6,
        "unit": "km/h",
        "unitType": 7
      },
      "sustainedWind": {
        "value": 74.1,
        "unit": "km/h",
        "unitType": 7
      },
      "status": "Tropical Storm",
      "window": {
        "left": {
          "latitude": 24.45283,
          "longitude": 142.055313
        },
        "right": {
          "latitude": 22.94641,
          "longitude": 142.744675
        }
      }
    }
  ]
}

Definitions

Name	Description
basinId	Basin identifier
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
GeoJsonGeometry	A valid `GeoJSON` geometry object. The type must be one of the seven valid GeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Please refer to RFC 7946 for details.
GeoJsonGeometryCollection	A valid `GeoJSON GeometryCollection` object type. Please refer to RFC 7946 for details.
GeoJsonLineString	A valid `GeoJSON LineString` geometry type. Please refer to RFC 7946 for details.
GeoJsonMultiLineString	A valid `GeoJSON MultiLineString` geometry type. Please refer to RFC 7946 for details.
GeoJsonMultiPoint	A valid `GeoJSON MultiPoint` geometry type. Please refer to RFC 7946 for details.
GeoJsonMultiPolygon	A valid `GeoJSON MultiPolygon` object type. Please refer to RFC 7946 for details.
GeoJsonPoint	A valid `GeoJSON Point` geometry type. Please refer to RFC 7946 for details.
GeoJsonPolygon	A valid `GeoJSON Polygon` geometry type. Please refer to RFC 7946 for details.
JsonFormat	Desired format of the response. Only `json` format is supported.
LatLongPair	A location represented as a latitude and longitude.
RadiusSector	Bearing 0-90 = NE quadrant; 90-180 = SE quadrant; 180-270 = SW quadrant; 270-360 = NW quadrant.
StormForecast	The StormForecast object contains detailed Government-issued information about forecasted tropical storms, including the storm's location, status, forecast creation date, wind speed, and wind radii.
StormForecastResult	An array of StormForecast objects, each detailing individual storm forecasts issued by government authorities.
StormWindRadiiSummary	The StormWindRadiiSummary object provides a high-level overview of the wind distribution around a tropical storm. It includes the geometric representation of wind radii (radiiGeometry), detailed sector-based wind data (radiusSectorData), and the wind speeds at various distances from the storm's center (windSpeed). These properties collectively help in understanding the spatial extent and intensity of winds associated with the storm. Displayed when the request includes `details=true` or `radiiGeometry=true`.
UnitType	An integer representing the unit type. For example, 17 for Celsius, 18 for Fahrenheit. Can be used for unit translation. For a complete list, see Weather services in Azure Maps.
WeatherDataUnit	Specifies to return the data in either metric units or imperial units. Default value is metric.
WeatherUnit	Specific value of a given unit related to weather.
WeatherWindow	Forecast window for the storm

basinId

Enumeration

Basin identifier

Value	Description
AL	The Atlantic Ocean. Crucial for tracking hurricanes that affect the Americas and the Caribbean. It is one of the most active regions for tropical storms.
CP	The Central Pacific Ocean. This basin is used for storms affecting Hawaii and surrounding areas.
EP	The Eastern Pacific Ocean. This basin tracks storms impacting the western coast of the Americas, including Mexico and Central America. It is adjacent to the Central Pacific basin.
NI	The North Indian Ocean. This basin covers storms impacting South Asia, including countries like India and Bangladesh, which are frequently affected by cyclones.
NP	The Northwest Pacific Ocean. This basin is important for tracking typhoons that affect East Asia, including countries like China, Japan, and the Philippines. It is the most active tropical storm regions globally.
SI	The South Indian Ocean. This basin, positioned south of the equator, covers cyclones impacting Madagascar, Africa, and surrounding regions.
SP	The South Pacific Ocean. This basin, positioned south of the equator, is relevant for cyclones affecting Australia and the South Pacific islands.

ErrorAdditionalInfo

Object

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

Object

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Object

Error response

Name	Type	Description
error	ErrorDetail	The error object.

GeoJsonGeometry

Object

A valid GeoJSON geometry object. The type must be one of the seven valid GeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Please refer to RFC 7946 for details.

Name	Type	Description
type	GeoJsonObjectType	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonGeometryCollection

Object

A valid GeoJSON GeometryCollection object type. Please refer to RFC 7946 for details.

Name	Type	Description
geometries	GeoJsonGeometry[]: GeoJsonGeometryCollection[] GeoJsonLineString[] GeoJsonMultiLineString[] GeoJsonMultiPoint[] GeoJsonMultiPolygon[] GeoJsonPoint[] GeoJsonPolygon[]	Contains a list of valid `GeoJSON` geometry objects. Note that coordinates in GeoJSON are in x, y order (longitude, latitude).
type	string: GeometryCollection	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonLineString

Object

A valid GeoJSON LineString geometry type. Please refer to RFC 7946 for details.

Name	Type	Description
coordinates	number[] (double)	Coordinates for the `GeoJson LineString` geometry.
type	string: LineString	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonMultiLineString

Object

A valid GeoJSON MultiLineString geometry type. Please refer to RFC 7946 for details.

Name	Type	Description
coordinates	number[] (double)	Coordinates for the `GeoJson MultiLineString` geometry.
type	string: MultiLineString	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonMultiPoint

Object

A valid GeoJSON MultiPoint geometry type. Please refer to RFC 7946 for details.

Name	Type	Description
coordinates	number[] (double)	Coordinates for the `GeoJson MultiPoint` geometry.
type	string: MultiPoint	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonMultiPolygon

Object

A valid GeoJSON MultiPolygon object type. Please refer to RFC 7946 for details.

Name	Type	Description
coordinates	number[] (double)	Contains a list of valid `GeoJSON Polygon` objects. Note that coordinates in GeoJSON are in x, y order (longitude, latitude).
type	string: MultiPolygon	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonPoint

Object

A valid GeoJSON Point geometry type. Please refer to RFC 7946 for details.

Name	Type	Description
coordinates	number[] (double)	A `Position` is an array of numbers with two or more elements. The first two elements are longitude and latitude, precisely in that order. Altitude/Elevation is an optional third element. Please refer to RFC 7946 for details.
type	string: Point	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

GeoJsonPolygon

Object

A valid GeoJSON Polygon geometry type. Please refer to RFC 7946 for details.

Name	Type	Description
coordinates	number[] (double)	Coordinates for the `GeoJson Polygon` geometry type.
type	string: Polygon	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

JsonFormat

Enumeration

Desired format of the response. Only json format is supported.

Value	Description
json	The JavaScript Object Notation Data Interchange Format

LatLongPair

Object

A location represented as a latitude and longitude.

Name	Type	Description
latitude	number (double)	Latitude property
longitude	number (double)	Longitude property

RadiusSector

Object

Bearing 0-90 = NE quadrant; 90-180 = SE quadrant; 180-270 = SW quadrant; 270-360 = NW quadrant.

Name	Type	Description
beginBearing	number (double)	Bearing, in degrees, of the beginning of the quadrant.
endBearing	number (double)	Bearing, in degrees, of the end of the quadrant.
range	number (double)	The radius of the quadrant, in nautical miles.

StormForecast

Object

The StormForecast object contains detailed Government-issued information about forecasted tropical storms, including the storm's location, status, forecast creation date, wind speed, and wind radii.

Name	Type	Description
dateTime	string	Date and time that the current forecast is valid, displayed in ISO 8601 format (yyyy-mm-ddThh:mm:ss-hh:mm). For example, 2025-04-29T07:00:00-07:00.
initializedDateTime	string	Date and time that the forecast was created, displayed in ISO 8601 format (yyyy-mm-ddThh:mm:ss-hh:mm). For example, 2025-04-29T07:00:00-07:00.
location	LatLongPair	Specifies the geographical coordinates (latitude and longitude) of the storm's forecasted position.
maxWindGust	WeatherUnit	Specifies the expected maximum wind gust speed and direction expected during the storm, measured in kilometers per hour (km/h) or miles per hour (mph), based on the specified unit. Wind direction is given in azimuth degrees, ranging from 0° (true North) to 359°, moving clockwise. May be NULL.
status	string	Indicates the current state or condition of the storm. This property provides information on whether the storm is active, dissipating, or has reached another significant status. Possible values: Cyclonic storm Deep depression Depression Extremely severe cyclonic storm Hurricane category (1-5) Intense tropical cyclone Moderate tropical storm Post-tropical cyclone Potential tropical cyclone Severe cyclonic storm Severe tropical storm Subtropical Super cyclonic storm Tropical cyclone Tropical cyclone category (1-5) Tropical depression Tropical disturbance Tropical storm Typhoon Very intense tropical cyclone Very severe cyclonic storm Very strong typhoon Violent typhoon
sustainedWind	WeatherUnit	Specifies the maximum sustained wind speed expected during the storm, measured in kilometers per hour (km/h) or miles per hour (mph), based on the unit specified in the request. May be NULL.
windRadiiSummary	StormWindRadiiSummary[]	Contains an array of StormWindRadiiSummary objects, detailing wind radii in different quadrants around the storm's center. Displayed when `details=true` or `radiiGeometry=true` in the request.
window	WeatherWindow	Provides forecast details for the storm within the specified time frame. If the `windowGeometry` parameter is set to true in the API request, this property will include GeoJSON details for the window geometry.

StormForecastResult

Object

An array of StormForecast objects, each detailing individual storm forecasts issued by government authorities.

Name	Type	Description
nextLink	string	Contains the URL to fetch the next page of results if the response is paginated. This is useful when the response is too large to be returned in a single call, allowing users to navigate through multiple pages of results.
results	StormForecast[]	An array of forecast data for tropical storms, including predicted paths, intensities, and other relevant details. These forecasts are issued by government authorities.

StormWindRadiiSummary

Object

The StormWindRadiiSummary object provides a high-level overview of the wind distribution around a tropical storm. It includes the geometric representation of wind radii (radiiGeometry), detailed sector-based wind data (radiusSectorData), and the wind speeds at various distances from the storm's center (windSpeed). These properties collectively help in understanding the spatial extent and intensity of winds associated with the storm. Displayed when the request includes details=true or radiiGeometry=true.

Name	Type	Description
dateTime	string	Date and time that the wind radii summary data is valid, displayed in ISO 8601 format (yyyy-mm-ddThh:mm:ss-hh:mm). For example, 2025-04-29T07:00:00-07:00.
radiiGeometry	GeoJsonGeometry: GeoJsonGeometryCollection GeoJsonLineString GeoJsonMultiLineString GeoJsonMultiPoint GeoJsonMultiPolygon GeoJsonPoint GeoJsonPolygon	A GeoJSON object that is returned when the `radiiGeometry` parameter is set to true in the request. It provides detailed geographical information about the storm's wind radii, including the spatial representation of areas affected by different wind speeds.
radiusSectorData	RadiusSector[]	An array of RadiusSector objects. Each object contains detailed geographical information (in geoJSON format) needed to plot wind radius quadrants: 0-90° for NE, 90-180° for SE, 180-270° for SW, and 270-360° for NW.
windSpeed	WeatherUnit	The overall wind speed associated with the storm's wind radii data. This single wind speed value applies collectively to all the sectors within the radiusSectorData array, which provides detailed geographical information for the NE, SE, SW, and NW quadrants of the storm's wind radii.

UnitType

Enumeration

An integer representing the unit type. For example, 17 for Celsius, 18 for Fahrenheit. Can be used for unit translation. For a complete list, see Weather services in Azure Maps.

Value	Description
0	feet
1	inches
2	miles
3	millimeter
4	centimeter
5	meter
6	kilometer
7	kilometersPerHour
8	knots
9	milesPerHour
10	metersPerSecond
11	hectoPascals
12	inchesOfMercury
13	kiloPascals
14	millibars
15	millimetersOfMercury
16	poundsPerSquareInch
17	Celsius
18	Fahrenheit
19	kelvin
20	percent
21	float
22	integer
31	MicrogramsPerCubicMeterOfAir

WeatherDataUnit

Enumeration

Specifies to return the data in either metric units or imperial units. Default value is metric.

Value	Description
imperial	Return data using imperial units such as Fahrenheit (F) for temperature and mile (mi) for distance.
metric	Return data using metric units such as Celsius (C) for temperature and kilometer (km) for distance.

WeatherUnit

Object

Specific value of a given unit related to weather.

Name	Type	Description
unit	string	Type of unit for the returned value.
unitType	UnitType (int32)	An integer representing the unit type. For example, 17 for Celsius, 18 for Fahrenheit. Can be used for unit translation. For a complete list, see Weather services in Azure Maps.
value	number (float)	Rounded value.

WeatherWindow

Object

Forecast window for the storm

Name	Type	Description
beginDateTime	string (date-time)	DateTime of the beginning of the window of movement, displayed in ISO8601 format.
beginStatus	string	Storm status at the beginning of the window.
endDateTime	string (date-time)	DateTime of the end of the window of movement, displayed in ISO8601 format.
endStatus	string	Storm status at the end of the window.
geometry	GeoJsonGeometry: GeoJsonGeometryCollection GeoJsonLineString GeoJsonMultiLineString GeoJsonMultiPoint GeoJsonMultiPolygon GeoJsonPoint GeoJsonPolygon	Displayed when windowGeometry=true in request. GeoJSON object containing coordinates describing the window of movement during the specified timeframe.
left	LatLongPair	Location of the point on the left side of the window at the time of the timeframe.
right	LatLongPair	Location of the point on the right side of the window at the end of the timeframe.

Share via

Weather - Get Tropical Storm Forecast

URI Parameters

Request Header

Responses

Security

AADToken

Notes

Scopes

subscription-key

SAS Token

Examples

Get Tropical Storm Forecasts

Sample request

Sample response

Definitions

basinId

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

GeoJsonGeometry

GeoJsonGeometryCollection

GeoJsonLineString

GeoJsonMultiLineString

GeoJsonMultiPoint

GeoJsonMultiPolygon

GeoJsonPoint

GeoJsonPolygon

JsonFormat

LatLongPair

RadiusSector

StormForecast

StormForecastResult

StormWindRadiiSummary

UnitType

WeatherDataUnit

WeatherUnit

WeatherWindow