WCA

Live

WCA

+ Day(s) remaining in the trial

Overview

Weather Company Alerts APIs

Getting started

Overview

The Weather Company Alerts RESTful APIs provide an easy way for companies to register recipients to receive weather alert notifications for specified weather events. Alert notifications can be sent through preferred media, such as email, SMS text messaging, or posting alert data to user-predefined web services endpoints.

After you upload your recipient data, you can create, read, update, and delete assets by using the Weather Company Alerts APIs. The APIs are powered by IBM API Management. You can perform operations on subscription, asset, and endpoints entities. You can also update multiple assets at the same time by using the bulkupload operation.

Entity model

The Weather Company Alerts APIs implement the following entities:

subscription A subscription represents an organization (for example, a company) that purchases the Weather Company Alerts service. Each recipient of a subscription entity is represented by an asset entity. Subscription entities can be retrieved. When a subscription is created, the Weather Company Alerts service creates a unique ID to represent the subscription in the service.

asset An asset represents a recipient of the subscription. Assets can be created, edited, and deleted. When an asset is created, an ID that is unique within the subscription must be provided.

events Each subscription can define a list of events that must be monitored. The following are examples of some of the available events:

* Hail is greater than or equal to 25 millimeters in a 30-minute period
* Lightning flashes greater than or equal to 0.10 flashes per square kilometer in a 30-minute period
* Wind speed greater than or equal to 15 meters per second within a 10-minute to 24-hour time period
* Snow is greater than or equal to 5 centimeters in a 4-hour period
* Rain is greater than or equal to 50 millimeters in a 3-hour period

endpoints Each subscription can specify an optional list of endpoints, which can be used for receiving alert data when events that the subscription subscribed to are forecast to occur. The Weather Company Alerts APIs send POST requests to these endpoints with a list of affected assets of the subscription.

Customer Endpoint Design

A subscription can specify an optional list of endpoints, which can be used for receiving alert data when events that the subscription subscribed to are forecast to occur.

The Weather Company Alerts APIs send POST requests to these endpoints with a list of affected assets of the subscription.

For example, https://alerts.abcinc.com/notification might be supplied as an SSL-secured endpoint that can receive alerts. If username and password are specified our system will use Basic Auth to authenticate requests to your endpoint(s).

The JSON payload for each weather alert API is in the following structure:

{
  "peril":"HAIL_ZONE_30MIN_GTE1.00_IN",
  "timestamp": "2018-04-10T18:42:28.299Z",
  "impacts": ["A10445", "B10562"],
  "starttime": "2018-04-10T20:42:28.299Z",
  "endtime": "2018-04-10T21:42:28.299Z",
  "eventId": "somerandomid"
}



NOTE: WCA considers adding additional fields/attributes to the JSON payload to be backwards compatible. Endpoints consuming this payload need to be tolerant of additional json attributes.

In the example, above, three locations were affected by the heavy snow weather alert.

The size of the notification message depends on the number of assets affected by each event and the length of the identifier used by the subscription.

Security

Keys

Pick a key to use with this API. Make sure you are logged in with your IBM id for your keys to be populated in the dropdown below. By selecting a key, it will be pre-filled for each endpoint in the Documentation section that can be used with the built-in testing. If you want to change which key to use for a particular endpoint, you can do so at the endpoint in the Documentation section.
You can manage your API keys in the <MyAPIs> section. API keys authenticate you to your subscription, so make sure to keep them secret. Do not share the X-IBM-Client-Secret portion of any API key in publicly accessible places such as GitHub, or client-side code.



Manage your keys
 

asset

Create, retrieve, update, and delete operations on a single asset. An asset represents a recipient or a notification.
Create an asset.
Use this operation to create an asset.

POST   /assets

			https://api.ibm.com/insights/run/alerts/v1/assets
		
Keys
Request code
								
HttpResponse<String> response = Unirest.post("https://api.ibm.com/insights/run/alerts/v1/assets") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .body("{\"active\":true,\"description\":\"John's home\",\"id\":\"asset00123\",\"location\":{\"description\":\"The location of an asset. The location can be supplied in multiple ways, but minimum information is required to determine geo coordinates. If geo is provided, the other fields are optional. If geo is not provided, all address fields are required.\",\"properties\":{\"city\":\"Bankingtown\",\"country\":\"Canada\",\"geo\":{\"description\":\"The latitude and longitude coordinates of a specific location.\",\"properties\":{\"lat\":12.34,\"lon\":56.78},\"required\":[\"lat\",\"lon\"],\"type\":\"object\"},\"postalCode\":\"K2S 0C3\",\"provinceState\":\"Ontario\",\"street\":\"1103E Bank St.\"},\"type\":\"object\"},\"recipient\":{\"description\":\"The attributes of the owner of the asset.\",\"properties\":{\"description\":\"John Smith from Bankingtown\",\"id\":\"001-203-45678-9\",\"language\":\"en\",\"name\":\"John Smith\"},\"required\":[\"id\"],\"type\":\"object\"},\"type\":\"STATIC\"}") .asString();
Request model

active

BOOLEAN , optional

A Boolean that indicates whether an asset is active or not.

description

STRING , optional

The description of the asset.

id

STRING , required

The ID of the asset.

location

OBJECT , required

The location of an asset. The location can be supplied in multiple ways, but minimum information is required to determine geo coordinates. If geo is provided, the other fields are optional. If geo is not provided, all address fields are required.

city

STRING , optional

The city name.

country

STRING , optional

The country name.

geo

OBJECT , optional

The latitude and longitude coordinates of a specific location.

lat

FLOAT , required

The latitude of the location of the asset.

lon

FLOAT , required

The longitude of the location of the asset.

postalCode

STRING , optional

The postal code or ZIP code.

provinceState

STRING , optional

The province or state.

street

STRING , optional

The street name and number.

recipient

OBJECT , optional

The attributes of the owner of the asset.

description

STRING , optional

The policy description. This property is a general purpose property and can be used according to API client needs.

id

STRING , required

A unique identifier for the recipient.

language

STRING , optional

The language preference that is used for sending SMS text and email messages.

name

STRING , optional

The recipient name that is used for generating personalized notification messages. This property must not be empty.

type

STRING , optional

Whether the asset is static or mobile. Valid values are "STATIC" or "MOBILE". Default is "STATIC".

Request example
{
  "active": true,
  "description": "John's home",
  "id": "asset00123",
  "location": {
    "city": "Bankingtown",
    "country": "Canada",
    "geo": {
    "lat": 12.34,
    "lon": 56.78
  },
    "postalCode": "K2S 0C3",
    "provinceState": "Ontario",
    "street": "1103E Bank St."
  },
  "recipient": {
    "description": "John Smith from Bankingtown",
    "id": "001-203-45678-9",
    "language": "en",
    "name": "John Smith"
  },
  "type": "STATIC"
}
Response model

201

Asset created successfully.

Body

active

BOOLEAN , optional

A Boolean that indicates whether an asset is active or not.

description

STRING , optional

The description of the asset.

id

STRING , required

The ID of the asset.

location [Location]

OBJECT , required

The location of an asset. The location can be supplied in multiple ways, but minimum information is required to determine geo coordinates. If geo is provided, the other fields are optional. If geo is not provided, all address fields are required.

recipient [Recipient]

OBJECT , optional

The attributes of the owner of the asset.

city

STRING , optional

The city name.

country

STRING , optional

The country name.

geo [GeoLocation]

OBJECT , optional

The latitude and longitude coordinates of a specific location.

postalCode

STRING , optional

The postal code or ZIP code.

provinceState

STRING , optional

The province or state.

street

STRING , optional

The street name and number.

lat

FLOAT , required

The latitude of the location of the asset.

lon

FLOAT , required

The longitude of the location of the asset.

description

STRING , optional

The policy description. This property is a general purpose property and can be used according to API client needs.

id

STRING , required

A unique identifier for the recipient.

language

STRING , optional

The language preference that is used for sending SMS text and email messages.

name

STRING , optional

The recipient name that is used for generating personalized notification messages. This property must not be empty.

400

Bad Request.

Body

404

Resource not found.

Body

500

Internal server error.

Body

default

Internal server error.

Body

Response example

201

Asset created successfully.

								{
  "active" : boolean,
  "description" : string,
  "id" : string,
  "location" : {
    "city" : "Bankingtown",
    "country" : "Canada",
    "geo" : {
    "lat" : 12.34,
    "lon" : 56.78
  },
    "postalCode" : "K2S 0C3",
    "provinceState" : "Ontario",
    "street" : "1103E Bank St."
  },
  "recipient" : {
    "description" : "John Smith from Bankingtown",
    "id" : "001-203-45678-9",
    "language" : "en",
    "name" : "John Smith"
  }
}
							

400

Bad Request.

								
							

404

Resource not found.

								
							

500

Internal server error.

								
							

default

Internal server error.

								
							
Delete an asset.
Use this operation to delete an asset.

DELETE   /assets/{assetId}

			https://api.ibm.com/insights/run/alerts/v1/assets/{assetId}
		
Keys
Path and Query parameters

assetId

URL , required

The ID of the asset to be deleted.

Request code
								
HttpResponse<String> response = Unirest.delete("https://api.ibm.com/insights/run/alerts/v1/assets/{assetId}") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

204

Asset deleted successfully.

Body

400

Bad Request

Body

404

Resource not found

Body

500

Internal server error.

Body

default

Internal server error.

Body

Response example

204

Asset deleted successfully.

								
							

400

Bad Request

								
							

404

Resource not found

								
							

500

Internal server error.

								
							

default

Internal server error.

								
							
Get an asset.
Use this operation to retrieve an asset.

GET   /assets/{assetId}

			https://api.ibm.com/insights/run/alerts/v1/assets/{assetId}
		
Keys
Path and Query parameters

assetId

URL , required

The ID of the asset to be retrieved.

Request code
								
HttpResponse<String> response = Unirest.get("https://api.ibm.com/insights/run/alerts/v1/assets/{assetId}") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

200

Success.

Body

active

BOOLEAN , optional

A Boolean that indicates whether an asset is active or not.

description

STRING , optional

The description of the asset.

id

STRING , required

The ID of the asset.

location [Location]

OBJECT , required

The location of an asset. The location can be supplied in multiple ways, but minimum information is required to determine geo coordinates. If geo is provided, the other fields are optional. If geo is not provided, all address fields are required.

recipient [Recipient]

OBJECT , optional

The attributes of the owner of the asset.

city

STRING , optional

The city name.

country

STRING , optional

The country name.

geo [GeoLocation]

OBJECT , optional

The latitude and longitude coordinates of a specific location.

postalCode

STRING , optional

The postal code or ZIP code.

provinceState

STRING , optional

The province or state.

street

STRING , optional

The street name and number.

lat

FLOAT , required

The latitude of the location of the asset.

lon

FLOAT , required

The longitude of the location of the asset.

description

STRING , optional

The policy description. This property is a general purpose property and can be used according to API client needs.

id

STRING , required

A unique identifier for the recipient.

language

STRING , optional

The language preference that is used for sending SMS text and email messages.

name

STRING , optional

The recipient name that is used for generating personalized notification messages. This property must not be empty.

404

Resource not found.

Body

500

Internal server error.

Body

default

Internal server error.

Body

Response example

200

Success.

								{
  "active" : boolean,
  "description" : string,
  "id" : string,
  "location" : {
    "city" : "Bankingtown",
    "country" : "Canada",
    "geo" : {
    "lat" : 12.34,
    "lon" : 56.78
  },
    "postalCode" : "K2S 0C3",
    "provinceState" : "Ontario",
    "street" : "1103E Bank St."
  },
  "recipient" : {
    "description" : "John Smith from Bankingtown",
    "id" : "001-203-45678-9",
    "language" : "en",
    "name" : "John Smith"
  }
}
							

404

Resource not found.

								
							

500

Internal server error.

								
							

default

Internal server error.

								
							
Update an asset.
Use this operation to update an asset.

PUT   /assets/{assetId}

			https://api.ibm.com/insights/run/alerts/v1/assets/{assetId}
		
Keys
Path and Query parameters

assetId

URL , required

The ID of the asset to be updated.

Request code
								
HttpResponse<String> response = Unirest.put("https://api.ibm.com/insights/run/alerts/v1/assets/{assetId}") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .body("{\"active\":true,\"description\":\"John's home\",\"id\":\"asset00123\",\"location\":{\"description\":\"The location of an asset. The location can be supplied in multiple ways, but minimum information is required to determine geo coordinates. If geo is provided, the other fields are optional. If geo is not provided, all address fields are required.\",\"properties\":{\"city\":{\"description\":\"The city name.\",\"example\":\"Bankingtown\",\"type\":\"string\"},\"country\":{\"description\":\"The country name.\",\"example\":\"Canada\",\"type\":\"string\"},\"geo\":{\"description\":\"The latitude and longitude coordinates of a specific location.\",\"properties\":{\"lat\":{\"description\":\"The latitude of the location of the asset.\",\"example\":12.34,\"format\":\"float\",\"type\":\"number\"},\"lon\":{\"description\":\"The longitude of the location of the asset.\",\"example\":56.78,\"format\":\"float\",\"type\":\"number\"}},\"required\":[\"lat\",\"lon\"],\"type\":\"object\"},\"postalCode\":{\"description\":\"The postal code or ZIP code.\",\"example\":\"K2S 0C3\",\"type\":\"string\"},\"provinceState\":{\"description\":\"The province or state.\",\"example\":\"Ontario\",\"type\":\"string\"},\"street\":{\"description\":\"The street name and number.\",\"example\":\"1103E Bank St.\",\"type\":\"string\"}},\"type\":\"object\"},\"recipient\":{\"description\":\"The attributes of the owner of the asset.\",\"properties\":{\"description\":{\"description\":\"The policy description. This property is a general purpose property and can be used according to API client needs.\",\"example\":\"John Smith from Bankingtown\",\"type\":\"string\"},\"id\":{\"description\":\"A unique identifier for the recipient.\",\"example\":\"001-203-45678-9\",\"type\":\"string\"},\"language\":{\"description\":\"The language preference that is used for sending SMS text and email messages.\",\"example\":\"en\",\"type\":\"string\"},\"name\":{\"description\":\"The recipient name that is used for generating personalized notification messages. This property must not be empty.\",\"example\":\"John Smith\",\"type\":\"string\"}},\"required\":[\"id\"],\"type\":\"object\"},\"type\":\"STATIC\"}") .asString();
Request model

active

BOOLEAN , optional

A Boolean that indicates whether an asset is active or not.

description

STRING , optional

The description of the asset.

id

STRING , required

The ID of the asset.

location

OBJECT , required

The location of an asset. The location can be supplied in multiple ways, but minimum information is required to determine geo coordinates. If geo is provided, the other fields are optional. If geo is not provided, all address fields are required.

city

STRING , optional

The city name.

country

STRING , optional

The country name.

geo

OBJECT , optional

The latitude and longitude coordinates of a specific location.

lat

FLOAT , required

The latitude of the location of the asset.

lon

FLOAT , required

The longitude of the location of the asset.

postalCode

STRING , optional

The postal code or ZIP code.

provinceState

STRING , optional

The province or state.

street

STRING , optional

The street name and number.

recipient

OBJECT , optional

The attributes of the owner of the asset.

description

STRING , optional

The policy description. This property is a general purpose property and can be used according to API client needs.

id

STRING , required

A unique identifier for the recipient.

language

STRING , optional

The language preference that is used for sending SMS text and email messages.

name

STRING , optional

The recipient name that is used for generating personalized notification messages. This property must not be empty.

type

STRING , optional

Whether the asset is static or mobile. Valid values are "STATIC" or "MOBILE". Default is "STATIC".

Request example
{
  "active": true,
  "description": "John's home",
  "id": "asset00123",
  "location": {
    "city": "Bankingtown",
    "country": "Canada",
    "geo": {
    "lat": 12.34,
    "lon": 56.78
  },
    "postalCode": "K2S 0C3",
    "provinceState": "Ontario",
    "street": "1103E Bank St."
  },
  "recipient": {
    "description": "John Smith from Bankingtown",
    "id": "001-203-45678-9",
    "language": "en",
    "name": "John Smith"
  },
  "type": "STATIC"
}
Response model

200

Asset updated successfully.

Body

active

BOOLEAN , optional

A Boolean that indicates whether an asset is active or not.

description

STRING , optional

The description of the asset.

id

STRING , required

The ID of the asset.

location [Location]

OBJECT , required

The location of an asset. The location can be supplied in multiple ways, but minimum information is required to determine geo coordinates. If geo is provided, the other fields are optional. If geo is not provided, all address fields are required.

recipient [Recipient]

OBJECT , optional

The attributes of the owner of the asset.

city

STRING , optional

The city name.

country

STRING , optional

The country name.

geo [GeoLocation]

OBJECT , optional

The latitude and longitude coordinates of a specific location.

postalCode

STRING , optional

The postal code or ZIP code.

provinceState

STRING , optional

The province or state.

street

STRING , optional

The street name and number.

lat

FLOAT , required

The latitude of the location of the asset.

lon

FLOAT , required

The longitude of the location of the asset.

description

STRING , optional

The policy description. This property is a general purpose property and can be used according to API client needs.

id

STRING , required

A unique identifier for the recipient.

language

STRING , optional

The language preference that is used for sending SMS text and email messages.

name

STRING , optional

The recipient name that is used for generating personalized notification messages. This property must not be empty.

400

Bad Request.

Body

404

Resource Not Found.

Body

500

Internal server error.

Body

default

Internal server error.

Body

Response example

200

Asset updated successfully.

								{
  "active" : boolean,
  "description" : string,
  "id" : string,
  "location" : {
    "city" : "Bankingtown",
    "country" : "Canada",
    "geo" : {
    "lat" : 12.34,
    "lon" : 56.78
  },
    "postalCode" : "K2S 0C3",
    "provinceState" : "Ontario",
    "street" : "1103E Bank St."
  },
  "recipient" : {
    "description" : "John Smith from Bankingtown",
    "id" : "001-203-45678-9",
    "language" : "en",
    "name" : "John Smith"
  }
}
							

400

Bad Request.

								
							

404

Resource Not Found.

								
							

500

Internal server error.

								
							

default

Internal server error.

								
							
Update the asset's location address
Update the asset's location address

PUT   /assets/{assetId}/location/address

			https://api.ibm.com/insights/run/alerts/v1/assets/{assetId}/location/address
		
Keys
Path and Query parameters

assetId

URL , required

The id of the asset.

Request code
								
HttpResponse<String> response = Unirest.put("https://api.ibm.com/insights/run/alerts/v1/assets/{assetId}/location/address") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .body("{\"city\":\"Bankingtown\",\"country\":\"Canada\",\"postalCode\":\"K2S 0C3\",\"provinceState\":\"Ontario\",\"street\":\"1103E Bank St.\"}") .asString();
Request model

city

STRING , required

The city name.

country

STRING , required

The country name.

postalCode

STRING , required

The postal code or ZIP code.

provinceState

STRING , required

The province or state.

street

STRING , required

The street name and number.

Request example
{
  "city": "Bankingtown",
  "country": "Canada",
  "postalCode": "K2S 0C3",
  "provinceState": "Ontario",
  "street": "1103E Bank St."
}
Response model

200

Success.

Body

city

STRING , optional

The city name.

country

STRING , optional

The country name.

geo [GeoLocation]

OBJECT , optional

The latitude and longitude coordinates of a specific location.

postalCode

STRING , optional

The postal code or ZIP code.

provinceState

STRING , optional

The province or state.

street

STRING , optional

The street name and number.

lat

FLOAT , required

The latitude of the location of the asset.

lon

FLOAT , required

The longitude of the location of the asset.

400

Bad Request.

Body

404

Resource Not Found.

Body

500

Internal server error.

Body

default

Internal server error.

Body

Response example

200

Success.

								{
  "city" : "Bankingtown",
  "country" : "Canada",
  "geo" : {
    "lat" : 12.34,
    "lon" : 56.78
  },
  "postalCode" : "K2S 0C3",
  "provinceState" : "Ontario",
  "street" : "1103E Bank St."
}
							

400

Bad Request.

								
							

404

Resource Not Found.

								
							

500

Internal server error.

								
							

default

Internal server error.

								
							
Update the asset's location geo. Used primarily for moving assets.
Update the asset's location geo. Used primarily for moving assets.

PUT   /assets/{assetId}/location/geo

			https://api.ibm.com/insights/run/alerts/v1/assets/{assetId}/location/geo
		
Keys
Path and Query parameters

assetId

URL , required

The id of the asset.

Request code
								
HttpResponse<String> response = Unirest.put("https://api.ibm.com/insights/run/alerts/v1/assets/{assetId}/location/geo") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .body("{\"lat\":12.34,\"lon\":56.78}") .asString();
Request model

lat

FLOAT , required

The latitude of the location of the asset.

lon

FLOAT , required

The longitude of the location of the asset.

Request example
{
  "lat": 12.34,
  "lon": 56.78
}
Response model

200

Success.

Body

city

STRING , optional

The city name.

country

STRING , optional

The country name.

geo [GeoLocation]

OBJECT , optional

The latitude and longitude coordinates of a specific location.

postalCode

STRING , optional

The postal code or ZIP code.

provinceState

STRING , optional

The province or state.

street

STRING , optional

The street name and number.

lat

FLOAT , required

The latitude of the location of the asset.

lon

FLOAT , required

The longitude of the location of the asset.

400

Bad Request.

Body

404

Resource Not Found.

Body

500

Internal server error.

Body

default

Internal server error.

Body

Response example

200

Success.

								{
  "city" : "Bankingtown",
  "country" : "Canada",
  "geo" : {
    "lat" : 12.34,
    "lon" : 56.78
  },
  "postalCode" : "K2S 0C3",
  "provinceState" : "Ontario",
  "street" : "1103E Bank St."
}
							

400

Bad Request.

								
							

404

Resource Not Found.

								
							

500

Internal server error.

								
							

default

Internal server error.

								
							

Loading content...