Weather - Get Weather Along Route

Use to get a locationally precise, up-to-the-minute forecast that includes weather hazard assessments and notifications along a route.
The Get Weather Along Route API is an HTTP GET request that returns hyper local (one kilometer or less), up-to-the-minute weather nowcasts, weather hazard assessments, and notifications along a route described as a sequence of waypoints. This includes a list of weather hazards affecting the waypoint or route, and the aggregated hazard index for each waypoint might be used to paint each portion of a route according to how safe it is for the driver. When submitting the waypoints, it is recommended to stay within, or close to, the distance that can be traveled within 120-mins or shortly after. Data is updated every five minutes.

The service supplements Azure Maps Route Service that allows you to first request a route between an origin and a destination and use that as an input for Weather Along Route endpoint.

In addition, the service supports scenarios to generate weather notifications for waypoints that experience an increase in intensity of a weather hazard. For example, if the vehicle is expected to begin experiencing heavy rain as it reaches a waypoint, a weather notification for heavy rain will be generated for that waypoint allowing the end product to display a heavy rain notification before the driver reaches that waypoint. The trigger for when to display the notification for a waypoint could be based, for example, on a geofence, or selectable distance to the waypoint.

The API covers all regions of the planet except latitudes above Greenland and Antarctica.

GET {endpoint}/weather/route/json?api-version=1.1&query={query}

GET {endpoint}/weather/route/json?api-version=1.1&query={query}&language={language}

URI Parameters

Request Header

Responses

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.

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

Scopes

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: header

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

Successfully retrieve detailed weather casts along a route described as a sequence of waypoints

GET https://atlas.microsoft.com/weather/route/json?api-version=1.1&query=38.907,-77.037,0:38.907,-77.009,10:38.926,-76.928,20:39.033,-76.852,30:39.168,-76.732,40:39.269,-76.634,50:39.287,-76.612,60

{
  "summary": {
    "hazards": {
      "maxHazardIndex": 0
    },
    "iconCode": 35
  },
  "waypoints": [
    {
      "cloudCover": 70,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 38,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Mostly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 90,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 3.4
      },
      "wind": {
        "direction": {
          "degrees": 142
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 2
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 3
        }
      }
    },
    {
      "cloudCover": 65,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 38,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Mostly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 77,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 3.4
      },
      "wind": {
        "direction": {
          "degrees": 166
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 1
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 2
        }
      }
    },
    {
      "cloudCover": 43,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 35,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Partly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 44,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 3.2
      },
      "wind": {
        "direction": {
          "degrees": 163
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 2
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 2
        }
      }
    },
    {
      "cloudCover": 34,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 35,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Partly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 32,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 1.6
      },
      "wind": {
        "direction": {
          "degrees": 189
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 2
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 4
        }
      }
    },
    {
      "cloudCover": 54,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 38,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Mostly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 36,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 0.5
      },
      "wind": {
        "direction": {
          "degrees": 202
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 4
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 5
        }
      }
    },
    {
      "cloudCover": 46,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 35,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Partly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 38,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 2.4
      },
      "wind": {
        "direction": {
          "degrees": 222
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 4
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 5
        }
      }
    },
    {
      "cloudCover": 39,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 35,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Partly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 43,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 2.3
      },
      "wind": {
        "direction": {
          "degrees": 231
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 4
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 5
        }
      }
    }
  ]
}

Definitions

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

ErrorResponse

Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).

HazardDetail

One entry in WeatherHazards.hazardDetails describing a single weather hazard at the location (route-level when carried on WeatherAlongRouteSummary.hazards, or per-waypoint when carried on WaypointForecast.hazards). Combines a hazardCode identifying the specific hazard type, a hazardIndex rating its individual severity on the 0-4 scale, and a shortPhrase suitable for display in a UI.

HazardIndex

The aggregated severity/hazard index for each waypoint can be utilized to color-code segments of a route, indicating the safety level for drivers.

• 0: No hazard
• 1: Be informed, be aware
• 2: Pay attention, be prepared
• 3: Take action
• 4: Life-threatening, emergency

IconCode

The numeric weather-condition code that identifies which icon to display. Each value in this enumeration corresponds to an Azure Maps weather icon (such as Sunny, Cloudy, or Thunderstorms) and pairs with a human-readable iconPhrase returned alongside it. The same code can appear in current, hourly, daily, quarter-day, and minute-by-minute responses, allowing applications to render a consistent icon set across all weather services.

For the complete list of codes, the icons they map to, and example imagery, see Weather services in Azure Maps.

JsonFormat

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

SunGlare

The sun-glare driving hazard at a single waypoint, returned as WaypointForecast.sunGlare. Reports a glareIndex from 0 to 100 measuring the intensity of glare a driver would experience at the waypoint, together with the calculatedVehicleHeading used to compute it - the heading is either the value supplied for the waypoint in the request or, if none was supplied, one inferred from the neighboring waypoints.

UnitType

An integer value associated with the type of unit being displayed. For example, 17 for Celsius, 18 for Fahrenheit. Can be used for unit translation. For more information, see Weather services in Azure Maps.

WaypointForecast

The detailed forecast for one waypoint along a road route, returned as one entry per requested waypoint in WeatherAlongRouteResult.waypoints (same order as the waypoints supplied in the request). Reports the conditions at that location: a representative iconCode and shortPhrase, whether it is day or night, cloud cover, temperature, wind and wind-gust details, precipitation type and intensity, a lightning-strike count, the sun glare hazard for the driver, the WeatherHazards aggregated at the waypoint, and any free-form hazard notifications.

WeatherAlongRoutePrecipitation

The expected precipitation at a single waypoint along the route, returned as WaypointForecast.precipitation. Reports the forecast intensity as radar reflectivity (dbz) together with the precipitation type (rain, snow, ice, hail, or mix). A dbz of 0 indicates no precipitation, in which case type may still be returned to indicate the precipitation type that would occur if any fell at the waypoint (for example, snow during cold weather).

WeatherAlongRouteResult

The response returned by the Get Weather Along Route operation, providing the forecast for a sequence of waypoints along a road route. Includes a top-level summary with the highest hazard index across the route and a representative weather icon, plus a waypoints array containing one detailed forecast per requested waypoint - cloud cover, temperature, wind, precipitation, lightning count, sun glare, hazards, and notifications.

WeatherAlongRouteSummary

The route-level summary on WeatherAlongRouteResult.summary, giving a single high-level snapshot of conditions across the entire route. Includes a representative weather iconCode for the route and an aggregated hazards block reporting the maximum hazard index and the specific hazard types encountered at any waypoint. Use this when a single route-level indicator is needed; for per-waypoint detail, use WeatherAlongRouteResult.waypoints.

WeatherHazards

A summary of the significant weather hazards at a single location. The same shape is used in two places by the Get Weather Along Route response: on WeatherAlongRouteSummary.hazards, where it aggregates across the entire route (max severity at any waypoint), and on WaypointForecast.hazards, where it describes the hazards at one specific waypoint. Conveys both a top-level maxHazardIndex rating the worst hazard in scope (from 0 - no hazard - to 4 - life-threatening) and a hazardDetails array enumerating each specific hazard type encountered (rain, snow, ice, hail, sun glare, lightning, wind, and severe weather warnings such as floods, tornadoes, tsunamis, and severe thunderstorms).

WeatherNotification

One free-form hazard notification raised at a single waypoint along the route, returned as an entry in WaypointForecast.notifications. Each notification combines a type classifying the notification, a hazardCode identifying the specific hazard, a hazardIndex rating its severity on the 0-4 scale, and a shortPhrase suitable for display. Notifications complement WaypointForecast.hazards - the latter enumerates every active hazard at the waypoint, while notifications carries only the ones the service has flagged as worth surfacing to the driver.

WeatherValue

Values for weather-related metrics such as temperature, dew point, and wind speed, presented in either metric or imperial units, as specified in the unit URI parameter. For more information, see Unit types in the article Weather services in Azure Maps.

WindDetails

Provides the forecasted wind speed, measured in units such as kilometers per hour (km/h) or miles per hour (mph), depending on the unit specified in the request. Also indicates the wind direction measured in azimuth degrees, starting at true North and moving clockwise. North corresponds to 0°, east to 90°, south to 180°, and west to 270°. Possible values range from 0° to 359°.

WindDirection

Provides details about wind direction, including the direction in azimuth degrees and a localized abbreviation of the wind direction.