Weather Alerts for Insurance

Live

Weather Alerts for Insurance

+ Day(s) remaining in the trial

Overview

The Weather Alerts for Insurance service provides alerts to insurance policy holders when monitored locations are forecast to experience weather of a particular type and severity.

Getting started

Overview

The Weather Alerts for Insurance RESTful APIs provide an easy way for insurance companies to register policy holders 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 policy holder data, you can create, read, update, and delete assets by using the Weather Alerts for Insurance APIs. The APIs are powered by IBM API Management. You can perform operations on subscription, asset, endpoints, and events entities. You can also update multiple assets at the same time by using the bulkupload operation.

Entity model

The Weather Alerts for Insurance APIs implement the following entities:

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

asset An asset represents a policyholder 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. Policyholder information is represented by the subscriber property of an asset. Notifications are a subentity of asset.

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

* 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 Alerts for Insurance APIs send POST requests to these endpoints with a list of affected assets of the subscription.

Authentication

To use the Weather Alerts for Insurance APIs, you must purchase the Weather Alerts for Insurance service. Buying the Weather Alerts for Insurance service registers your subscription in IBM Cloud Services. Then, you must sign in to API Explorer with the IBM ID that is registered against a subscription.

When you sign in to API Explorer with this IBM ID, your IBM-Client-Id and IBM-Client-Secret credentials are automatically filled into the header parameters and the TEST button is available for your use. The IBM-Client-Id and IBM-Client-Secret credentials are masked.

To use your keys, click Pick your key to select the plan to retrieve the keys for. Then, click Manage your keys. API Explorer opens a page where you can create, delete, regenerate, or retrieve your keys. Use the interface to show your keys, and then you can copy and paste them into your REST API calls.

Note: If you aren't signed in to API Explorer, click I already have a key and sign in.

Error Handling

The Weather Alerts for Insurance APIs use standard HTTP status codes.

The following status codes are used in this API:

  • 200 - Success.
  • 201 - Success (created).
  • 202 - Accepted (Request accepted, and queued for execution).
Client side errors:

  • 400 - Bad request.
  • 401 - Authentication failure.
  • 403 - Request forbidden.
  • 404 - Resource not found.
  • 405 - Method not allowed.
  • 409 - Conflict.
  • 412 - Precondition failed.
  • 413 - Request entity too large.
Server side errors:

  • 500 - Internal server error.
  • 501 - Not implemented.
  • 503 - Service unavailable.

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 Alerts for Insurance APIs send POST requests to these endpoints with a list of affected assets of the subscription.

For example, https://alerts.abcinsurance.com/notification might be supplied as an SSL-secured endpoint that can receive alerts.

The JSON payload for each weather alert API is similar to the following example:

{
"event": "Heavy snow forecast >= 5 cm cumulative in the next 4 hours.",
"timestamp": "2015-05-26T05:35:37.000Z",
"impacts":
[
"A10445",
"B10562",
"A40312"
]
}


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
 

Documentation

Weather Alerts for Insurance:

asset

Create an asset.
Use this operation to create an asset.

POST   /assets

			https://api.ibm.com/insights/run/alerts/v1/assets
		
Keys
Header parameters

X-IBM-Client-Id

HEADER , required

Client Id from the app

X-IBM-Client-Secret

HEADER , required

Cient Secret from the app

Request code
								
HttpResponse<String> response = Unirest.post("https://api.ibm.com/insights/run/alerts/v1/assets") .header("accept", "application/json") .header("content-type", "application/json") .header("x-ibm-client-secret", "SOME_STRING_VALUE") .header("x-ibm-client-id", "SOME_STRING_VALUE") .asString();
Request model

isActive

BOOLEAN , optional

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

id

STRING , required

The ID of the asset.

policyholder

object , optional

id

STRING , required

A unique identifier for the policy holder.

description

STRING , optional

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

name

STRING , optional

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

language

STRING , optional

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

notifications

ARRAY , optional

The notification methods for alerting an affected asset about the events that impact them. This property allows API consumers to specify multiple notification methods for each event.

value

STRING , required

Value of the - email address or cell phone number.

type

STRING , required

Type of notification media.

location

object , required

GeoLocation

object , optional

lon

DOUBLE , required

The longitude of the location of the asset.

lat

DOUBLE , required

The latitude 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.

country

STRING , optional

The country name.

city

STRING , optional

The city name.

description

STRING , optional

The description of the asset.

Request example
{
  "isActive": boolean,
  "id": string,
  "policyholder": {
    "id": string,
    "description": string,
    "name": string,
    "language": string
  },
  "notifications": [{
    "value": string,
    "type": email,sms
  }],
  "location": {
    "GeoLocation": {
    "lon": double,
    "lat": double
  },
    "postalCode": string,
    "provinceState": string,
    "street": string,
    "country": string,
    "city": string
  },
  "description": string
}
Response model

201

Success.

Body

isActive

BOOLEAN , optional

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

id

STRING , required

The ID of the asset.

policyholder [Policyholder]

object , optional

notifications [Notification]

ARRAY , optional

The notification methods for alerting an affected asset about the events that impact them. This property allows API consumers to specify multiple notification methods for each event.

location [LocationResponse]

object , required

description

STRING , optional

The description of the asset.

id

STRING , required

A unique identifier for the policy holder.

description

STRING , optional

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

name

STRING , optional

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

language

STRING , optional

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

value

STRING , required

Value of the - email address or cell phone number.

type

STRING , required

Type of notification media.

postalCode

STRING , optional

The postal code or ZIP code.

provinceState

STRING , optional

The province or state.

street

STRING , optional

The street name and number.

country

STRING , optional

The country name.

city

STRING , optional

The city name.

400

Bad Request.

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

404

Resource not found.

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

default

Internal server error.

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

Response example

201

Success.

								{
  "isActive" : boolean,
  "id" : string,
  "policyholder" : {
    "id" : string,
    "description" : string,
    "name" : string,
    "language" : string
  },
  "notifications" : [{
    "value" : string,
    "type" : email,sms
  }],
  "location" : {
    "postalCode" : string,
    "provinceState" : string,
    "street" : string,
    "country" : string,
    "city" : string
  },
  "description" : string
}
							

400

Bad Request.

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							

404

Resource not found.

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							

default

Internal server error.

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							
Delete an asset.
Use this operation to delete an asset.

DELETE   /assets/{assetId}

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

X-IBM-Cient-Id

HEADER , required

Client Id form the app

X-IBM-Client-Secret

HEADER , required

Client Secret from the app

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/%7BassetId%7D") .header("accept", "application/json") .header("content-type", "application/json") .header("x-ibm-cient-id", "SOME_STRING_VALUE") .header("x-ibm-client-secret", "SOME_STRING_VALUE") .asString();
Response model

200

Asset deleted successfully.

Body

message

STRING , required

A message that indicates that the asset was deleted successfully.

400

Bad Request

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

404

Resource not found

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

default

Internal server error.

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

Response example

200

Asset deleted successfully.

								{
  "message" : string
}
							

400

Bad Request

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							

404

Resource not found

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							

default

Internal server error.

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							
Get an asset.
Use this operation to retrieve an asset.

GET   /assets/{assetId}

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

X-IBM-Client-Secret

HEADER , required

Client Secret from the app

X-IBM-Client-Id

HEADER , required

Client Id from the app

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/%7BassetId%7D") .header("accept", "application/json") .header("content-type", "application/json") .header("x-ibm-client-id", "SOME_STRING_VALUE") .header("x-ibm-client-secret", "SOME_STRING_VALUE") .asString();
Response model

200

Success.

Body

isActive

BOOLEAN , optional

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

id

STRING , required

The ID of the asset.

policyholder [Policyholder]

object , optional

notifications [Notification]

ARRAY , optional

The notification methods for alerting an affected asset about the events that impact them. This property allows API consumers to specify multiple notification methods for each event.

location [LocationResponse]

object , required

description

STRING , optional

The description of the asset.

id

STRING , required

A unique identifier for the policy holder.

description

STRING , optional

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

name

STRING , optional

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

language

STRING , optional

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

value

STRING , required

Value of the - email address or cell phone number.

type

STRING , required

Type of notification media.

postalCode

STRING , optional

The postal code or ZIP code.

provinceState

STRING , optional

The province or state.

street

STRING , optional

The street name and number.

country

STRING , optional

The country name.

city

STRING , optional

The city name.

404

Resource not found.

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

default

Internal server error.

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

Response example

200

Success.

								{
  "isActive" : boolean,
  "id" : string,
  "policyholder" : {
    "id" : string,
    "description" : string,
    "name" : string,
    "language" : string
  },
  "notifications" : [{
    "value" : string,
    "type" : email,sms
  }],
  "location" : {
    "postalCode" : string,
    "provinceState" : string,
    "street" : string,
    "country" : string,
    "city" : string
  },
  "description" : string
}
							

404

Resource not found.

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							

default

Internal server error.

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							
Update an asset.
Use this operation to update an asset.

PUT   /assets/{assetId}

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

X-IBM-Cient-Id

HEADER , required

Client Id from the app

X-IBM-Client-Secret

HEADER , required

Client Secret from the app

Request code
								
HttpResponse<String> response = Unirest.put("https://api.ibm.com/insights/run/alerts/v1/assets/%7BassetId%7D") .header("accept", "application/json") .header("content-type", "application/json") .header("x-ibm-client-secret", "SOME_STRING_VALUE") .header("x-ibm-cient-id", "SOME_STRING_VALUE") .asString();
Request model

isActive

BOOLEAN , optional

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

id

STRING , required

The ID of the asset.

policyholder

object , optional

id

STRING , required

A unique identifier for the policy holder.

description

STRING , optional

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

name

STRING , optional

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

language

STRING , optional

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

notifications

ARRAY , optional

The notification methods for alerting an affected asset about the events that impact them. This property allows API consumers to specify multiple notification methods for each event.

value

STRING , required

Value of the - email address or cell phone number.

type

STRING , required

Type of notification media.

location

object , required

GeoLocation

object , optional

lon

DOUBLE , required

The longitude of the location of the asset.

lat

DOUBLE , required

The latitude 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.

country

STRING , optional

The country name.

city

STRING , optional

The city name.

description

STRING , optional

The description of the asset.

Request example
{
  "isActive": boolean,
  "id": string,
  "policyholder": {
    "id": string,
    "description": string,
    "name": string,
    "language": string
  },
  "notifications": [{
    "value": string,
    "type": email,sms
  }],
  "location": {
    "GeoLocation": {
    "lon": double,
    "lat": double
  },
    "postalCode": string,
    "provinceState": string,
    "street": string,
    "country": string,
    "city": string
  },
  "description": string
}
Response model

200

Asset updated successfully.

Body

message

STRING , required

A message that indicates that the asset was updated successfully.

400

Bad Request.

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

404

Resource Not Found.

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

default

Internal server error.

Body

message

STRING , optional

description

STRING , optional

code

STRING , optional

Response example

200

Asset updated successfully.

								{
  "message" : string
}
							

400

Bad Request.

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							

404

Resource Not Found.

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							

default

Internal server error.

								{
  "message" : string,
  "description" : string,
  "code" : string
}
							

Loading content...