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":[[[lat,lon]...]]}&appid={API key}

Parameters
`location`	required	Location of interest with a pair of coordinates: lat - latitude of the coordinates, decimal (-90; 90); lon - longitude of the coordinates, decimal (-180; 180). 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. Example: List [ "extreme_high_temperature" ]
`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

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

Example of API response

        
{
  "count": 2,
  "items": [
    {
      "hour": 0,
      "date": "2024-02-23T11:29:42.062536+00:00",
      "alerts": [
        {
          "alert_id": "65d881436757c95162b5b83e",
          "source": "Australian Government Bureau of Meteorology",
          "title": "Severe cyclone",
          "industries": {
            "global": {
              "description": "FLOODING POSSIBLE IN PARTS OF PILBARA AND GASCOYNE COAST RIVERS FROM SATURDAY MORNING\nFLOODING POSSIBLE IN GREENOUGH RIVER CATCHMENT FROM SUNDAY\n\nEx-Tropical Cyclone Lincoln is likely to redevelop into a cyclone to the north of the Pilbara today, and could be near the Gascoyne coast later on Saturday. It is expected to continue southeast into the inland Gascoyne or Central West on Sunday.\n\n\nCatchments in the Flood Watch area are relatively dry.\nWidespread rainfall totals of 40-80 mm with isolated totals above 160 mm are forecast for Saturday over the Pilbara and Gascoyne Coast River catchments. Further rainfall totals of 60-80 mm with isolated totals of 140 mm possible over parts of the Central West District and Gascoyne Coast catchments on Sunday.\nSignificant river, creek, and stream rises are likely with heavy rainfall, with flooding possible across the Pilbara and Gascoyne Coast Rivers from Saturday morning. Flooding is possible in parts of the Central West District Rivers, in the Greenough River catchment, from Sunday.\n\nMany roads, and possibly primary and secondary highways may be affected. Some communities and homesteads may become isolated. Check road conditions before travelling.",
              "severity": "severe"
            }
          },
          "tag": "cyclone",
          "location": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  114.0375,
                  -25.6625
                ],
                [
                  114.035,
                  -25.6625
                ],
                [
                  114.035,
                  -25.66
                ],
                [
                  114.0375,
                  -25.66
                ],
                [
                  114.0375,
                  -25.6625
                ]
              ]
            ]
          },
          "urgency": "unknown",
          "certainty": "likely"
        },
        {
          "alert_id": "65d8021c07fb7f9a482ba024",
          "source": "owm",
          "title": "High wind",
          "industries": {
            "power_saver_market": {
              "description": "High winds can lead to power line damage and infrastructure disruptions, increasing the risk of grid outages during stormy weather.",
              "severity": "moderate"
            }
          },
          "tag": "wind",
          "location": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  113.64385681987733,
                  -27.431248073205893
                ],
                [
                  113.74161689972185,
                  -27.431248073205893
                ],
                [
                  113.74161689972185,
                  -27.46016706784128
                ],
                [
                  113.83937697956637,
                  -27.46016706784128
                ],
                [
                  113.83937697956637,
                  -27.48907847898905
                ],
                [
                  113.93713705941089,
                  -27.48907847898905
                ],
                [
                  113.93713705941089,
                  -27.517982301278312
                ],
                [
                  114.00231044597389,
                  -27.517982301278312
                ],
                [
                  114.00231044597389,
                  -27.546878529347346
                ],
                [
                  114.06748383253692,
                  -27.546878529347346
                ],
                [
                  114.06748383253692,
                  -27.604648181423457
                ],
                [
                  114.10007052581842,
                  -27.604648181423457
                ],
                [
                  114.10007052581842,
                  -27.662387392506197
                ],
                [
                  114.13265721909994,
                  -27.662387392506197
                ],
                [
                  114.13265721909994,
                  -27.864234295260776
                ],
                [
                  114.10007052581842,
                  -27.864234295260776
                ],
                [
                  114.10007052581842,
                  -27.893038977797474
                ],
                [
                  114.0348971392554,
                  -27.893038977797474
                ],
                [
                  114.0348971392554,
                  -27.92183599724287
                ],
                [
                  114.00231044597389,
                  -27.92183599724287
                ],
                [
                  114.00231044597389,
                  -27.893038977797474
                ],
                [
                  113.90455036612938,
                  -27.893038977797474
                ],
                [
                  113.90455036612938,
                  -27.864234295260776
                ],
                [
                  113.87196367284787,
                  -27.864234295260776
                ],
                [
                  113.87196367284787,
                  -27.83542195487572
                ],
                [
                  113.83937697956637,
                  -27.83542195487572
                ],
                [
                  113.83937697956637,
                  -27.806601961894373
                ],
                [
                  113.80679028628485,
                  -27.806601961894373
                ],
                [
                  113.80679028628485,
                  -27.777774321577994
                ],
                [
                  113.77420359300336,
                  -27.777774321577994
                ],
                [
                  113.77420359300336,
                  -27.748939039196912
                ],
                [
                  113.74161689972185,
                  -27.748939039196912
                ],
                [
                  113.74161689972185,
                  -27.72009612003064
                ],
                [
                  113.70903020644035,
                  -27.72009612003064
                ],
                [
                  113.70903020644035,
                  -27.69124556936781
                ],
                [
                  113.67644351315883,
                  -27.69124556936781
                ],
                [
                  113.67644351315883,
                  -27.633521594752732
                ],
                [
                  113.64385681987733,
                  -27.633521594752732
                ],
                [
                  113.64385681987733,
                  -27.604648181423457
                ],
                [
                  113.61127012659583,
                  -27.604648181423457
                ],
                [
                  113.61127012659583,
                  -27.46016706784128
                ],
                [
                  113.64385681987733,
                  -27.46016706784128
                ],
                [
                  113.64385681987733,
                  -27.431248073205893
                ]
              ]
            ]
          },
          "urgency": "immediate",
          "certainty": "likely"
        }
      ]
    }
  ]
}

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

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":[lat,lon]}&appid={API key}

Parameters
`location`	required	Location of interest with a pair of coordinates: lat - latitude of the coordinates, decimal (-90; 90); lon - longitude of the coordinates, decimal (-180; 180). 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. Example : List [ "extreme_high_temperature" ]
`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

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

Example of API response

        
{
  "count": 1,
    "items": [
      {
        "hour": 0,
        "date": "2024-02-23T08:58:34.019565+00:00",
        "alerts": [
          {
            "alert_id": "65d856e47e117e4a4eabdc4c",
            "source": "Australian Government Bureau of Meteorology",
            "title": "Severe high temperature",
            "industries": {
              "global": {
                "description": "Severe heatwave conditions have eased over the Pilbara district, however, remain over central parts. Heatwave conditions will contract eastward and intensify over the next few days.  \n\nMaximum temperatures in the high thirties to mid to high forties and overnight minimum temperatures in the mid to high twenties, reaching the low thirties over northern parts.",
                "severity": "severe"
              }
            },
            "tag": "high_temperature",
            "location": {
              "type": "Polygon",
              "coordinates": [
                [
                  [
                    129.0017,
                    -23.431924144999982
                  ],
                  [
                    129.0017,
                    -24.0545
                  ],
                  [
                    129.00180000000012,
                    -24.0795
                  ],
                  [
                    129.00180000000012,
                    -25.8795
                  ],
                  [
                    129.0019,
                    -25.9045
                  ],
                  [
                    129.0019,
                    -26.0486
                  ],
                  [
                    129.00180000000012,
                    -26.0736
                  ],
                  [
                    129.00180000000012,
                    -26.9986
                  ],
                  [
                    129.0017,
                    -27.0236
                  ],
                  [
                    129.0017,
                    -27.9486
                  ],
                  [
                    129.0016,
                    -27.9736
                  ],
                  [
                    129.0016,
                    -28.9236
                  ],
                  [
                    129.0015,
                    -28.9486
                  ],
                  [
                    129.0014000000001,
                    -30.31236126699997
                  ],
                  [
                    126.10957130100007,
                    -30.15055894099993
                    ,
                    [
                      120.01578908800002,
                      -26.00042392699993
                    ],
                    [
                      121.27862901700007,
                      -23.440507305999972
                    ],
                    [
                      124.6777923520001,
                      -23.440411077999954
                    ],
                    [
                      129.0017,
                      -23.431924144999982
                    ]
                  ]
                ]
              },
            "urgency": "immediate",
            "certainty": "observed"
          }
        ]
      }
    ]
}

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

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.