Define Locations

Overview

A location is a property, building, business, or other asset that may be damaged by catastrophe events. When location coverage is applied to a location, that location is known as a location exposure.

A location is generally tied to a specific account, which identifies the cedants, underwriters, and policies that are applicable to that account. In general, a policy applies to every location belonging to an account. The Risk Modeler API provides numerous operations for defining details (e.g. policy conditions, reinsurance cessions) that mitigate coverage for a particular location.

Every location is defined by a set of location attributes (for example, property, address, postalCode) and optional building attributes, location conditions, reinsurance cessions, perils (earthquakes, floods, fires, etc.), and other attributes. Location coverage defines the liability of the underwriter for damages to entities (buildings, building contents, businesses) at a specific location due to catastrophe events.

Create location

The Create location operation enables you to create new locations and add that object to a specific EDM data source. The name of the datasource must be specified as a query in the endpoint.

curl --request POST \
     --url 'https://{host}/v1/locations?datasource=mydatasource' \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

All other parameters are specified in the body of the request.

The required property and address objects define the core attributes of a location.


{
  "property": {
	  "locationName": "LowRes location",
	    "yearBuilt": 1949,
	    "floorOccupancy": "",
	    "rentalPropertyIdentifier": {
	    	"id": 0,
	    	"name": ""
        },
      "buildingClass": {
	  	  "code": 2,
	  	  "name": "2 - Light Metal"
	  	},
	     "isPrimaryBldg": true,
	     "occupancyType": {
	  	   "id": 17,
	  	   "name": "17 - High Technology"
	  	   },
	    "accountId": 5,
	    "buildingClassScheme": {
	    	"code": "ATC",
	    	"name": "ATC"
	    	},
	    "nship": null,
	    "userGroundElev": -999,
	    "slope": null,
	    "heightUnit": {
	    	"id": 2,
	    	"name": ""
	    	},
	    "floodDefHtAboveGrnd": -999,
	    "occupancyTypeScheme": {
	    	"code": "ATC",
	    	"name": ""
	    	},
	    "expireDate": "9999-12-31T08:00:00.000Z",
	    "areaUnit": {
	    	"id": 2,
	    	"name": ""
	    	},
	    "siteName": {
	    	"code": "",
	    	"name": "Golden Gateway Apts"
	    	},
	    "stories": 4,
	    "mfdSubcategory": {
	    	"id": 0,
	    	"name": ""
	    	},
	    "bldgHeight": null,
	    "userBfe": -999,
	    "huZone": {
	    	"code": "B",
	    	"name": ""
	    	},
	    "floorArea": 1452.0,
	    "inceptDate": "9999-12-31T08:00:00.000Z",
	    "floodDefenseElevation": -999,
	    "contentLossTrigger": {
	    	"id": "",
	    	"name": ""
	    	},
	    "otherZone": "",
	    "locationNumber": "1",
	    "floodDefenseElevationUnit": {
	    	"id": 2,
	    	"name": ""
	    	},
	    "buildings": 1,
	    "dwellTime": null,
	    "useContentValue": {
		    "id": "",
		    "name": ""
		    }
      },
  "address": {
  	"geoResolutionCode": {
  		"id": 5,
  		"code": "",
  		"name": "ZIP Code"
  		},
  	"latitude": 37.796469
  	"admin1Name": "",
  	"block": "",
  	"addressType": {
  		"id": 1,
  		"name": ""
  		},
    "admin2Name": "SAN FRANCISCO COUNTY",
    "longitude": -122.399317,
    "countryRmsCode": "US",
    "admin3Name": "FILLMORE",
    "admin1Code": "CA",
    "admin4Name": "",
    "admin2Code": "071",
    "streetAddress": "185 Jackson Street",
    "admin3Code": "0716",
    "blockGroup": "",
    "cityName": "California",
    "country": {
  	  "code": "US",
  	  "name": "United States"
      },
    "postalCode": "94111",
    "cityCode": "14",
    "countryScheme": "ISO2A"
    },
  "currency": {
    "code": "USD",
    "name": "US Dollar"
    }
}

These objects define details about the precise location and vulnerabilities of an exposure, making DLM risk analysis possible.

The required address object defines the specific address of a location. The DLM uses specific information about the location to better assess the vulnerability of the location. To learn more, see the Address schema docs.
The required property object provides detailed information about a property including core building attributes, which enables the model to assess the vulnerability of the location to catastrophe events making for more accurate risk analysis. Additional building attribute details may be specified in the optional buildingAttribute and esdbAttribute parameters.
The currency parameter is an object that defines the currency used to calculate projected losses for the location.

The operation accepts several optional body parameters that can be defined when you define or update the location or separately using other Risk Modeler API operations. These operations enable you to define perils, building attributes, reinsurance cessions and other objects.

Add perils

A peril is a natural or man-made phenomenon at a particular location that may produce an insurance loss. Perils may defined whenever you create or update a location or they may be defined separately using a distinct API request.

Risk Modeler API supports the following peril operations:

The Create BI peril operation specifies a business interruption peril that is applied to a specific location. A business interruption identifies a disruption caused by damage to the structure, facility, or business location that results in the loss or reduction of income due to the suspension of operations.
The Create FL peril operation specifies a flood peril that is applied to a specific location.
The Create FR peril operation specifies a fire peril that is applied to a specific location. May produce Fire and Smoke sub-perils.
The Create EQ peril operation specifies a earthquake peril that is applied to a specific location. May produce Shake, Fire Following, Sprinkler Leakage, and Tsunami sub-perils.
The Create TO peril operation specifies a severe convective storm and winterstorm peril that is applied to a specific location. May produce Tornado, Hail, and Straight Lee Wind sub-perils.
The Create TR peril operation specifies a terrorism peril that is applied to a specific location.
The Create WS peril operation specifies a windstorm/hurricane/cyclone/typhoon peril that is applied to a specific location.

Perils applied to locations may be primary perils or secondary perils. A primary peril is the principal modeled peril, associated with or caused by the modeled phenomenon responsible for causing loss. For example, ground shaking is the main cause of loss and thus the primary peril in earthquakes. A secondary peril (or sub-peril) is an additional modeled peril that is associated with or caused by the original primary modeled phenomenon responsible for causing loss.

Add location conditions

A policy defines an insurance contract between an insurance company and a person or company with some potential for economic loss from property being damaged. The policy specifies the terms of a contract (e.g. the inception and expiration dates, blanket limits, deductibles, and reinsurance cession) that apply to an account for one peril.

The policy generally applies to every location belonging an account. A policy condition defines a set of "special conditions" that affect policy coverage (i.e. limits, deductibles) for certain locations. Depending on the policy condition type, the policy condition may be used to restrict all policy coverage the specified locations (i.e. a policy restriction) or restrict a portion of policy coverage (i.e. a sub-limit) to the specific locations.

The Create location condition operation enables you to define a location condition that maps a location with a policy condition that defines the criteria for applying the policy condition to that location. This mapping determines whether the location is subject to the terms of a policy that is applied to an account.

curl --request POST \
		 --url 'https://{host}/riskmodeler/v1/locations/345555/locationcondition?datasource=myEdm' \
		 --header 'Authorization: XXXXXXXXXX' \
		 --header 'accept: application/json' \
		 --header 'content-type: application/json' \

The request body maps the location to a policy condition, and specifies how a policy is applied to the location.

{
		 "locationId": 345555,
		 "conditionId": 45,
		 "isIncluded": "Included"
}

The locationId body parameter specifies the ID number of the location.
The conditionId body parameter specifies the ID number of a policy condition. A policy condition identifies special conditions that affect the way a policy applies to a location. The policy condition identifies a "special condition" that may affect whether a policy is applied to a specific location. A policy condition may be used to implement policy restrictions or sub-limits at a particular location. Use the Create policy condition to define policy conditions.
The isIncluded body parameter specifies how the policy condition is applied to a location. One of Included, NotIncluded, or UserIncluded. If Included, the policy condition applies to the location based on policy condition criteria associated with the policy condition. If NotIncluded, the policy condition does not apply to the specified location regardless of policy condition criteria. If UserIncluded, the policy condition applies to the location.

A policy may define multiple policy conditions, policy coverages, reinsurance cessions.

Add reinsurance cessions

The Create reinsurance cession operation enables you to define a reinsurance cession that applies to a specific location.

A reinsurance cession is a contract or agreement between two insurers that involves the purchase of insurance by an insurance (ceding) company from another insurance (reinsurance) company for the purpose of spreading risk and reducing the loss from a catastrophe event. The reinsurer assumes part of the risk initially assumed by another insurance company. An insurance company buys reinsurance for its own protection. The risk of loss is spread so a disproportionately large loss under a single policy does not fall on one company.

Add location coverages

The Create location coverage operation enables you to define the terms of risk or liability for losses such as buildings, personal property, and business interruptions at a specific location.

The id path parameter and datasource query parameter are required.

curl --request POST \
     --url https://{host}/v1/locations/id/coverage \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'content-type: application/json' \

All other parameters are specified in the request body. The location coverage object may be used to define the terms of location-level coverage for a specific location including maximum insurer liability, the perils covered, and coverage modifiers.

{
     "id": 0,
     "label": {
          "id": 0,
          "code": "string",
          "name": "string"
     },
     "eqslModifier": 0,
     "lossType": "Building",
     "percentSprinkler": 0,
     "value": 0,
     "biPoi": 0,
     "deductible": 0,
     "coverageModifier": {
          "id": 0,
          "code": "string",
          "name": "string"
     },
     "accumulation": "Building",
     "limit": 0,
     "peril": {
          "id": 0,
          "code": "string",
          "name": "string"
     },
     "percentageLossDeductibleAmount": 0,
     "isFranchiseDeductible": {
          "id": 0,
          "code": "string",
          "name": "string"
     },
     "isValid": true,
     "waitingPeriod": 0
}

All locationCoverage object properties are optional.

The biPoi attribute identifies the business interruption period of indemnity in months.
The deductible attribute specifies the location coverage deductible.
The eqsModifier attribute specifies the grade of contents covered by in case of an earthquake sprinkler leakage (EQSL) peril.
The id attribute defines the ID number of the covered location.
The isValid attribute is a boolean value that indicates whether coverage for a location is valid (1) or invalid (0).
The label attribute specifies an ExposureValue object that identifies peril detail.
The lossType attribute identifies the loss type covered. One of Building, Contents, BI, or CombinedCvg.
The percentSprinkler identifies the percentage of building contents that are beneath a sprinkler and susceptible to water damage.
The peril attribute identifies the perils covered.
The value attribute identifies the full replacement value of covered buildings and contents and the value of one year of income for business interruption coverage.
The waitingPeriod attribute specifies a waiting period deductible in days that applies to to business interruption coverage.

For detailed information on location coverage terms, see the RiskLink® and RiskBrowser® 18 and Risk Modeler™ 2.0 Database Schema in the Moody's RMS Support Center