--- updatedAt: 2026-08-12T15:27:00.000Z agentTools: siteIndex: https://docs.here.com/llms.txt projectIndex: https://docs.here.com/destination-weather/llms.txt --- # Weather alerts Weather alerts along the route or around a single location. # OpenAPI definition ```json { "openapi": "3.0.2", "info": { "title": "Weather API v3", "version": "3.0.0", "description": "NOTE: Accessing Weather Radar and Weather Alerts requires Weather Premium product permissions.\n\nThe HERE Weather API is a RESTful API that:\n\n- provides weather forecasts and reports on current weather conditions.\n- provides information on severe weather alerts along a specified route or a single car location.\n- provides weather radar images in an area.\n\nExamples of information that may be available in weather reports include:\n\n- Descriptions of the overall weather, temperature, precipitation, and wind in supported languages.\n- Numerical data on temperature, humidity, dew point, precipitation, wind and visibility.\n- Forecast alerts, severe warnings and watches for supported NWS alert types and for supported global alert types.\n- Icon name and link for the report.\n\nA weather report typically contains at least the temperature, comfort level, wind speed and direction, and a description, but there can be variation in the responses. The HERE Destination Weather API provides solutions for the following high-level use cases:\n\n- Get current weather reports or weather forecasts for a specific location.\n- Check for severe weather alerts at a specific location.\n- Check when the sun and moon rise and set at a specific location.\n\nWeather data is intended to be used by connected in-vehicle infotainment systems to provide weather information to drivers.\n\nWeather premium is restricted to automotive use cases only.\n" }, "externalDocs": { "description": "The developer guide and release notes are available here.", "url": "https://www.here.com/docs/category/destination-weatherv3" }, "security": [ { "Bearer": [] }, { "ApiKey": [] } ], "tags": [ { "name": "Weather Alerts", "description": "Weather alerts issued by country goverment" } ], "paths": { "/alerts": { "post": { "tags": [ "Weather Alerts" ], "summary": "Weather alerts", "description": "Weather alerts along the route or around a single location.", "operationId": "Weather API v3 weatherAlert", "parameters": [ { "$ref": "#/components/parameters/X-Request-Id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WeatherAlertRequestGeoJson" }, "examples": { "singleLocationExample": { "$ref": "#/components/examples/WeatherAlertsSingleLocationRequestExample" }, "routeExample": { "$ref": "#/components/examples/WeatherAlertsRouteRequestExample" } } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WeatherAlertGeoJson" }, "examples": { "alertExample": { "$ref": "#/components/examples/WeatherAlertsResponseExample" } } } } }, "400": { "$ref": "#/components/responses/Error400AlertsResponse" }, "401": { "$ref": "#/components/responses/Error401Response" }, "403": { "$ref": "#/components/responses/Error403Response" }, "500": { "$ref": "#/components/responses/Error500Response" }, "502": { "$ref": "#/components/responses/Error502Response" }, "503": { "$ref": "#/components/responses/Error503Response" }, "504": { "$ref": "#/components/responses/Error504Response" } } } } }, "servers": [ { "url": "https://weather.hereapi.com/v3", "description": "Production environment URL" } ], "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request.\n\nFor more information on how to get a bearer token, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html.\n" }, "ApiKey": { "type": "apiKey", "in": "query", "name": "apiKey", "description": "A key generated specifically to authenticate API requests. For more information on how to get an API key, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html.\n" } }, "headers": { "X-Correlation-Id": { "description": "Auto-generated unique identifier to identify this request.", "schema": { "type": "string" }, "example": "4d173a1e-6f1b-459b-b74f-23686354aaea" }, "X-Request-Id": { "description": "User-provided token that can be used to trace a request or a group of requests sent to the service.\n", "schema": { "type": "string" } } }, "parameters": { "X-Request-Id": { "name": "X-Request-Id", "in": "header", "description": "User-provided token that can be used to trace a request or a group of requests sent to the service.", "schema": { "type": "string" } } }, "responses": { "Error400AlertsResponse": { "description": "Invalid parameters were provided.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "badRequestExample": { "$ref": "#/components/examples/BadRequestAlertExample" } } } } }, "Error401Response": { "description": "API response in case of lacking valid authorization credentials.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" }, "example": { "error": "Unauthorized", "error_description": "No credentials found" } } } }, "Error403Response": { "description": "API response in case of insufficient credentials for access to the requested resource.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" }, "example": { "error": "Forbidden", "error_description": "These credentials do not authorize access" } } } }, "Error500Response": { "description": "API response in case of internal server error", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "errorResponseExample": { "$ref": "#/components/examples/InternalServerErrorExample" } } } } }, "Error502Response": { "description": "API response in case of bad gateway", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "errorResponseExample": { "$ref": "#/components/examples/502errorResponseExample" } } } } }, "Error503Response": { "description": "API response in case of service unavailable", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": 503, "code": "E611001", "title": "Service not available", "cause": "Service current not available", "action": "Retry later", "correlationId": "efefe455-d2e3-4e23-86aa-4e9a8a1680d4" } } } }, "Error504Response": { "description": "API response in case of gateway timeout.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/X-Correlation-Id" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "errorResponseExample": { "$ref": "#/components/examples/504errorResponseExample" } } } } } }, "schemas": { "Feature": { "description": "Feature object.", "properties": { "geometry": { "$ref": "#/components/schemas/Geometry" }, "id": { "type": "string", "example": "w-1234", "description": "Unique weather alert ID." }, "properties": { "$ref": "#/components/schemas/FeatureProperties" }, "type": { "enum": [ "Feature" ], "type": "string" } }, "required": [ "type", "geometry" ], "title": "Feature", "type": "object", "example": { "type": "Feature" } }, "FeatureRequest": { "description": "Feature object for alerts request body.", "properties": { "geometry": { "$ref": "#/components/schemas/GeometryRequest" }, "properties": { "$ref": "#/components/schemas/FeatureRequestProperties" }, "type": { "enum": [ "Feature" ], "type": "string" } }, "required": [ "type", "geometry" ], "title": "Feature", "type": "object", "example": { "type": "Feature" } }, "WeatherAlertGeoJson": { "description": "Weather alerts geojson response.", "properties": { "features": { "items": { "$ref": "#/components/schemas/Feature" }, "type": "array" } }, "title": "FeatureCollection", "type": "object" }, "WeatherAlertRequestGeoJson": { "description": "Weather alerts geojson request.", "properties": { "features": { "items": { "$ref": "#/components/schemas/FeatureRequest" }, "type": "array" } }, "title": "FeatureCollection", "type": "object" }, "Geometry": { "description": "Geometry object.", "oneOf": [ { "$ref": "#/components/schemas/GeoJsonPolygonType" }, { "$ref": "#/components/schemas/GeoJsonMultiPolygonType" } ], "title": "Geometry", "type": "object", "discriminator": { "propertyName": "type", "mapping": { "Polygon": "#/components/schemas/GeoJsonPolygonType", "MultiPolygon": "#/components/schemas/GeoJsonMultiPolygonType" } } }, "GeometryRequest": { "description": "Geometry object.", "oneOf": [ { "$ref": "#/components/schemas/GeoJsonPointType" }, { "$ref": "#/components/schemas/GeoJsonLineStringType" } ], "title": "Geometry", "type": "object" }, "GeoJsonPointType": { "description": "GeoJson geometry.", "properties": { "type": { "enum": [ "Point" ], "type": "string" }, "coordinates": { "items": { "$ref": "#/components/schemas/Point2D" }, "type": "array", "maxItems": 1, "minItems": 1 } }, "required": [ "type" ], "title": "Point", "type": "object", "example": [ 11.125, 23.456 ] }, "GeoJsonLineStringType": { "description": "GeoJson geometry.", "properties": { "type": { "enum": [ "LineString" ], "type": "string" }, "coordinates": { "items": { "$ref": "#/components/schemas/Point2D" }, "type": "array" } }, "required": [ "type" ], "title": "LineString", "type": "object", "example": [ [ 19.122004508972168, 48.72310386355342 ], [ 19.123892784118652, 48.72324541933301 ], [ 19.125652313232422, 48.72313217474119 ], [ 19.125566482543945, 48.72259425944797 ], [ 19.12621021270752, 48.72267919382413 ] ] }, "GeoJsonPolygonType": { "description": "GeoJson geometry.", "properties": { "type": { "enum": [ "Polygon" ], "type": "string" }, "coordinates": { "items": { "items": { "$ref": "#/components/schemas/Point2D" }, "type": "array" }, "type": "array" } }, "required": [ "type" ], "title": "Polygon", "type": "object", "example": [ [ [ 148.2204, -36.6264 ], [ 148.214811, -36.638078 ], [ 148.210563, -36.646957 ], [ 148.208364, -36.651551 ], [ 148.199408, -36.670267 ] ] ] }, "GeoJsonMultiPolygonType": { "description": "GeoJson geometry.", "properties": { "type": { "enum": [ "MultiPolygon" ], "type": "string" }, "coordinates": { "items": { "items": { "items": { "$ref": "#/components/schemas/Point2D" }, "type": "array" }, "type": "array" }, "type": "array" } }, "required": [ "type" ], "title": "MultiPolygon", "type": "object" }, "NumberItems": { "title": "NumberItems", "type": "number" }, "Point2D": { "description": "Point in 2D space", "items": { "$ref": "#/components/schemas/NumberItems" }, "maxItems": 2, "minItems": 2, "title": "Point2D", "type": "array" }, "FeatureProperties": { "type": "object", "properties": { "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } } } }, "FeatureRequestProperties": { "type": "object", "properties": { "width": { "type": "integer", "format": "int32", "example": 3000, "default": 50000, "minimum": 1000, "maximum": 100000 } } }, "Warning": { "description": "Warning details", "type": "object", "properties": { "severity": { "type": "integer", "format": "int32", "enum": [ 0, 1, 2, 3, 4, 5 ], "example": 2, "description": "The severity of the event. One of:\n- 0 Event doesn't have significance by nature.\n- 1 There are no alerts for the location.\n- 2 Minor Severity, the event is potentially dangerous but not usual.\n- 3 Medium Severity, the event is dangerous.\n- 4 High Severity, The event is very dangerous.\n- 5 Emergency. Take immediate action to protect life.\n" }, "type": { "type": "integer", "format": "int32", "example": 3, "description": "Event type\n|Event Type|Description|\n|---|---|\n|1|Extremely high temperature|\n|2|Extremely low temperature|\n|3|Fog|\n|4|Ice or freezing rain|\n|5|Rain|\n|6|Snow|\n|7|Thunderstorm|\n|8|Wind|\n|9|Air quality|\n|10|Volcanic ashfall|\n|11|Avalanche|\n|12|Tsunami|\n|13|Dust storm or sandstorm|\n|14|Earthquake|\n|15|Fire danger|\n|16|Flood|\n|17|High waves|\n|18|High UV index|\n|19|Low water|\n|20|Smoke or smog|\n|21|Volcano|\n|22|Ice in waterway|\n|23|Coastal event|\n|24|Civil danger|\n|25|Evacuation|\n|26|Hazardous materials|\n|27|Radiological hazard|\n|28|Shelter in place|\n|29|Warning|\n" }, "country": { "type": "string", "example": "JP", "description": "ISO-3166-1 2-letter country code." }, "startTime": { "type": "integer", "format": "int32", "example": 1598510460, "description": "Start time of the event in UNIX time." }, "endTime": { "type": "integer", "format": "int32", "example": 1598536800, "description": "End time of the event in UNIX time. \nIf not present, warning is valid until it is not removed from the feed by national weather institutes (valid until warning is present in the response).\n" }, "messages": { "description": "An array of localized textual descriptions of the event.", "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "Message": { "description": "Warning message.", "type": "object", "properties": { "language": { "type": "string", "example": "en-AU", "description": "Language code." }, "text": { "type": "string", "example": "Minor Flood Warning", "description": "Human readable weather warning description." } } }, "ErrorResponse": { "type": "object", "properties": { "status": { "type": "integer", "format": "int32", "description": "The HTTP status code." }, "title": { "type": "string", "description": "Human-readable error description." }, "code": { "type": "string", "description": "Error code" }, "cause": { "type": "string", "description": "Human-readable explanation for the error." }, "action": { "type": "string", "description": "Human-readable action for the user." }, "correlationId": { "type": "string", "description": "Auto-generated ID univocally identifying this request." } }, "required": [ "status", "title", "code", "cause", "action", "correlationId" ] }, "AuthError": { "description": "Error object reported in case of authentication or authorization errors.", "type": "object", "properties": { "error": { "type": "string", "description": "Error message." }, "error_description": { "type": "string", "description": "Detailed information about the error." } }, "example": { "Type": "Unauthorized", "Message": "ApiKey invalid. ApiKey not found." } } }, "examples": { "WeatherAlertsResponseExample": { "value": { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "Polygon", "coordinates": [ [ [ 148.2204, -36.6264 ], [ 148.214811, -36.638078 ], [ 148.210563, -36.646957 ], [ 148.208364, -36.651551 ], [ 148.199408, -36.670267 ] ] ] }, "properties": { "warnings": [ { "severity": 3, "startTime": 1602043140, "country": "AU", "endTime": 1602162000, "type": 29, "messages": [ { "language": "en-AU", "text": "Warning to Sheep Graziers for Mallee, Wimmera, Northern Country, North Central, North East, South West, Central and West and South Gippsland forecast districts" } ] } ] } } ] } }, "WeatherAlertsSingleLocationRequestExample": { "value": { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ 15.256, 23.456 ] }, "properties": { "width": 30000 } } ] } }, "WeatherAlertsRouteRequestExample": { "value": { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [ -87.64652354220011, 41.87554760399442 ], [ -87.70047592527803, 41.87510123848884 ], [ -87.74084030076565, 1.87197659266343 ], [ -87.80778122050994, 41.87346453829784 ], [ -87.87771949486996, 41.87033981245949 ], [ -87.90609445189584, 41.873613330956374 ], [ -87.93866570538339, 41.8490578559865 ], [ -87.94865688743465, 41.84474107094087 ] ] }, "properties": { "width": 3000 } } ] } }, "BadRequestAlertExample": { "value": { "status": 400, "title": "Invalid Request", "cause": "Request body is empty.", "action": "Please provide valid json request body.", "code": "E611310", "correlationId": "dfe3b1a5-214f-49a9-b8a0-d78bd623bac0" } }, "InternalServerErrorExample": { "value": { "status": 500, "title": "Internal Server Error", "cause": "There was some issue processing the request.", "action": "Please retry after some time.", "code": "E611101", "correlationId": "dfe3b1a5-214f-49a9-b8a0-d78bd623bac0" } }, "502errorResponseExample": { "value": { "title": "Bad Gateway", "status": 502, "code": "E611201", "cause": "Bad Gateway", "action": "Failure of communication with external system.", "correlationId": "dfe3b1a5-214f-49a9-b8a0-d78bd623bac0" } }, "504errorResponseExample": { "value": { "title": "Gateway timeout", "status": 504, "code": "E611101", "cause": "Gateway Timeout", "action": "Did not receive a timely response from an upstream server", "correlationId": "dfe3b1a5-214f-49a9-b8a0-d78bd623bac0" } } } } } ```