Documentation

OpenWeather alerts API

Product concept

OpenWeather Alerts service provides users with alerts about the occurrence of certain weather conditions and phenomena on a particular territory. Weather alerts can include both extreme weather events and non-extreme ones.

OpenWeather Alerts are based on our unique OpenWeather ML forecasting model which uses a number of data sources - radars, models from global meteorological agencies (e.g., Met Office, NOAA, ECMWF), weather satellites, and a vast network of weather stations.

Alert is a notification of the occurrence of specified weather conditions or phenomena in an area located or intersecting with the user’s location. The alert is generated based on OpenWeather data or data from the national weather agency.

For each forecasted weather condition and phenomenon, the product contents the following information:

Alert description (Hail, Tornado, Extreme low temperature, Air Quality Alert etc.)
Affected area that is presented as exact coordinates of the polygon to which the alert applies
Date and time of the event
Source of data (Source of alert: government, OpenWeather)
Severity (The condition of being severe. There are 5 types of severity: unknown, minor, moderate, severe, extreme. Please find more details in the "Supporting information" chapter).
Certainty (Alert’s probability level. There are 5 types of certainty: observed, likely, possible, unlikely, unknown. Please find more details in the "Supporting information" chapter).
Urgency (The urgency level of taking the alert to actions. There are 4 types of urgency: immediate, expected, future, unknown. Please find more details in the "Supporting information" chapter).
Tag (weather phenomena type, the full list of tags is listed below):

Coastal_event
Extreme_low_temperature
Extreme_high_temperature
Wind
Flood
Sand_dust
Rain
Fire_warning
Marine_event
Avalanches
Fog
Air_quality
Tornado
Cyclone
Snow_ice
Thunderstorm
Hail

Insight (A parameter that describes what decision/action should be taken when the weather conditions specified in the trigger occur. Each insight will correspond to one specific industry and one weather phenomenon. Please find few examples in the "Supporting information" chapter "Alerts insights and weather conditions" section).

OpenWeather provides a pull API method to allow clients to request alerts data as frequently as required.

Product update time: hourly

Data format: JSON

Product has global coverage.

The service provide users an opportunity to filter alerts by:

Area of interest - can be specified as a point, or polygon
Weather parameters or specific phenomenon (alerts tag)
Data source
Industry
Urgency
start_date and end_date

How it works

Initially, OpenWeather engineers and meteorologists team select weather parameters and phenomena and their values and establish tailored weather triggers based on critical weather parameters and phenomena relevant to the user's industry and specific circumstances.

Subsequently, the system generates prompt and readily accessible alerts containing forecasted weather information spanning up to 5 days in advance. Each forecasted day is segmented into 24 1-hour intervals, enabling the collection of active alert data for each hour. Consequently, this results in the creation of up to 5*24 hourly segments for the forthcoming 5 days. The system undergoes hourly updates to produce a fresh set of hourly segments for the next 5 days. The most recent set of hourly segments is actual. Forecast duration can be extended upon request.

The system undergoes hourly updates to produce a fresh set of hourly segments for the next 5 days. The most recent set of hourly segments is actual.

Users have the flexibility to customize their received alerts by specifying:

start_date and end_date
A geographical area of interest
Preferred weather conditions
Severity levels
Other relevant parameters

If the user's chosen area of interest intersects with the alert zone, they will receive notifications containing relevant geometrical data pertaining to forecasted or observed weather parameters and phenomena.

Read chapter below to find how to make an API call to get weather alerts.

How to make an API call

In this section you will find detailed information on how to make requests to the OpenWeather Alerts API, examples of API calls and API responses. If you need to make an API call to the location type Point please use the section "API call to the location type Point". If you need to make an API call to the location type Polygon please use the section "API call to the location type Polygon".

API call to the location type Polygon

To get access to OpenWeather alerts to the location type Polygon please use this section of documentation. If you are interested in OpenWeather alerts to the location type Point please use the section "API call to the location type Point".

In this section you will find detailed information on how to make request to the OpenWeather Alerts API, examples of API call and API response.

API call

https://api.openweathermap.org/alerts/1.0?location={"type":"Polygon","coordinates":[[[lon,lat]...]]}&appid={API key}

Parameters
location	required	Location of interest with a pair of coordinates: lon - longitude of the coordinates, decimal (-180; 180); lat - latitude of the coordinates, decimal (-90; 90). Location must correspond to the geometry field geojson
source	optional	Source of alert. Available values: owm, government. To choose all possible sources of alerts leave this field empty
industry	optional	Industry of interest. Please contact us to customize this parameter in accordance with your needs.
start_date	optional	Date and time starting from which alerts will be returned in the ISO format. Current time is used if the parameter is not specified.Example: 2024-01-01T12:30:00+00:00
end_date	optional	Date and time in ISO format up to which need to get alerts. Next hour is used if the parameter is not specified.Example: 2024-01-01T12:30:00+00:00
tags	optional	One or more particular types of weather phenomenon to look for. Available values : coastal_event, extreme_low_temperature, extreme_high_temperature, wind, flood, sand_dust, rain, fire_warning, marine_event, avalanches, fog, air_quality, tornado, cyclone, snow_ice, thunderstorm, hail. To choose all possible tags leave this field empty.Weather phenomenon should be listed in the format: tags=parameter1,parameter2,...parameterNExample: tags=snow,ice,thunderstorm
severity	optional	Severity of the alert. Available values: unknown, minor, moderate, severe, extreme. To choose all possible severity levels leave this field empty
certainty	optional	Certainty of the alert. Available values: unknown, unlikely, possible, likely, observed. To choose all possible certainty levels leave this field empty
urgency	optional	Urgency of the alert. Available values: unknown, future, expected, immediate. To choose all possible urgency levels leave this field empty
show_location	optional	Displaying the location, specified in the API request, in the API response. Available values: false, true. If you do not use the `show_location` parameter, `true` will be applied by default

Example of API call

https://api.openweathermap.org/alerts/1.0?location={"type":"Polygon","coordinates":[[[109.072266,-9.62148],[108.896484,-44.787594],[157.060547,-44.787594],[157.763672,-9.62148],[109.072266,-9.62148]]]}&appid={API key}

Example of API response

To view the API response, expand the example by clicking the triangle.

Fields in API response

alert_ID - alert ID
source - source of alert
title- title of the alert
industry- alerts industries

industry_name - name of the industry

description - description of the insight for the industry
severity - severity of the alert for the industry

tag - One or more particular types of weather phenomenon to look for
location - representation of the area, where the alert is forecasted

type - the type of geometry. Possible values: point; polygon
coordinates - List of the coordinates of the polygons vertices

certainty - Certainty of the alert. May be one of Observed, Likely, Possible, Unlikely, Unknown
urgency - urgency of the alert. May be one of Immediate, Expected, Future, Unknown

API call to the location type Point

To get access to OpenWeather alerts to the location type Point please use this section of documentation. If you are interested in OpenWeather alerts to the location type Polygon please use the section "API call to the location type Polygon".

In this section you will find detailed information on how to make request to the OpenWether Alerts API, examples of API call and API response.

API call

https://api.openweathermap.org/alerts/1.0?location={"type":"Point","coordinates":[lon,lat]}&appid={API key}

Parameters
location	required	Location of interest with a pair of coordinates: lon - longitude of the coordinates, decimal (-180; 180); lat - latitude of the coordinates, decimal (-90; 90). Location must correspond to the geometry field geojson
source	optional	Source of alert. Available values: owm, government. To choose all possible sources of alerts leave this field empty
industry	optional	Industry of interest. Please contact us to customize this parameter in accordance with your needs.
start_date	optional	Date and time starting from which alerts will be returned in the ISO format. Current time is used if the parameter is not specified.Example: 2024-01-01T12:30:00+00:00
end_date	optional	Date and time in ISO format up to which need to get alerts. Next hour is used if the parameter is not specified.Example: 2024-01-01T12:30:00+00:00
tags	optional	One or more particular types of weather phenomenon to look for. Available values : coastal_event, extreme_low_temperature, extreme_high_temperature, wind, flood, sand_dust, rain, fire_warning, marine_event, avalanches, fog, air_quality, tornado, cyclone, snow_ice, thunderstorm, hail. To choose all possible tags leave this field empty.Weather phenomenon should be listed in the format: tags=parameter1,parameter2,...parameterNExample: tags=snow,ice,thunderstorm
severity	optional	Severity of the alert. Available values: unknown, minor, moderate, severe, extreme. To choose all possible severity levels leave this field empty
certainty	optional	Certainty of the alert. Available values: unknown, unlikely, possible, likely, observed. To choose all possible certainty levels leave this field empty
urgency	optional	Urgency of the alert. Available values: unknown, future, expected, immediate. To choose all possible urgency levels leave this field empty
show_location	optional	Displaying the location, specified in the API request, in the API response. Available values: false, true. If you do not use the `show_location` parameter, `true` will be applied by default

Example of API call

https://api.openweathermap.org/alerts/1.0?&location={"type":"Point","coordinates":[125.850425,-28.464529]}&appid={API key}

Example of API response

To view the API response, expand the example by clicking the triangle.

Fields in API response

count - Number of alerts matched with given filters
items

hour - number of hour
date - date in ISO format
alerts - alert related information

alert_ID - alert ID
source - source of alert
title- title of the alert
industry- alerts industries

industry_name - name of the industry

description - description of the insight for the industry
severity - severity of the alert for the industry

tag - One or more particular types of weather phenomenon to look for
location - representation of the area, where the alert is forecasted

type - the type of geometry. Possible values: point; polygon
coordinates - List of the coordinates of the polygons vertices

certainty - Certainty of the alert. May be one of Observed, Likely, Possible, Unlikely, Unknown
urgency - urgency of the alert. May be one of Immediate, Expected, Future, Unknown

Supporting information

This chapter contains information about Urgency, Certainty, Severity content and their usage as well as alerts insights and weather conditions description.

Urgency content and usage

Type of urgency	General description
`immediate`	Is calling for immediate attention means right now of or relating to the here and now occurring, acting, or accomplished without loss or interval of time
`expected`	There is some time for preparation. is calling for attention to events expected in the nearest days
`future`	Is calling for future attention
`unknown`	Used for case where urgency is not specified

Certainty content and usage

Type of certainty	General description
`observed`	For events which have been started in the past or started and continuing
`likely`	Show high probability of event occurrence
`possible`	Show medium probability of event occurrence
`unlikely`	Show low probability of event occurrence
`unknown`	Used for case where certainty is not specified

Severity content and usage

Type of severiry	General description
`unknown`	Used for case where severity is not specified
`minor`	Probability of serious consequences is small
`moderate`	Probability of serious consequences is medium
`severe`	Probability of serious consequences is high
`extreme`	Probability of serious consequences is very high

Alerts insights and weather conditions examples

Name of weather alert	Severity	Weather condition	Industry insight
`Extreme high temperature`	Extreme	temp > 39	Extreme high temperatures can strain power grids as demand peaks for cooling, potentially leading to grid outages due to increased load.
`Extreme low temperature`	Extreme	temp<= -11	Extreme low temperatures can significantly elevate heating energy demand, putting additional strain on the power grid and increasing the risk of grid outages.
`Coastal event`	Variable	YES	Coastal events, including storms and high winds, can lead to power grid outages due to damage to coastal infrastructure and power lines.

API errors

Structure of API errors

In case of incorrected API call you will receive an API error response. Error response payload returned for all types of errors with the structure below.

Example of error response

          
{
"code":400,
"message":"Invalid parameter format",
"parameters": [
  "lat"
  ]
}

Fields in error response

code - Code of error
message - Description of error
parameters(optional) - List of request parameters names that are related to this particular error

Errors list

API calls return an error 400

Bad Request. Either some mandatory parameters in the request are missing or some of the request parameters have incorrect format or values out of allowed range. List of all parameters names that are missing or incorrect will be returned in the parameters attribute of the ErrorResponse object.
API calls return an error 401

Unauthorized. You can get 401 error if API token was not provided in the request or in case API token provided in the request does not grant access to this API. You must add an API token with granted access to the product to the request before returning it.
API calls return an error 404

Not Found. Returned in case data identified with request parameters does not exist in the service database. You must not retry the same request.
API calls return an error 500

Internal Server Error. Returned in case of internal service error that prevented processing the request. Please refer to the message text for details. You may retry the request which led to this error.

Parameters

location

required

Location of interest with a pair of coordinates: lon - longitude of the coordinates, decimal (-180; 180); lat - latitude of the coordinates, decimal (-90; 90). Location must correspond to the geometry field geojson

source

optional

Source of alert. Available values: owm, government. To choose all possible sources of alerts leave this field empty

industry

optional

Industry of interest. Please contact us to customize this parameter in accordance with your needs.

start_date

optional

Date and time starting from which alerts will be returned in the ISO format. Current time is used if the parameter is not specified.Example: 2024-01-01T12:30:00+00:00

end_date

optional

Date and time in ISO format up to which need to get alerts. Next hour is used if the parameter is not specified.Example: 2024-01-01T12:30:00+00:00