Overview

The Risk Data API exposes operations for retrieving metrics, statistics, and metadata from analysis results. Distinct operations may be used depending on the model (ALM, DLM, or HD) used to model the result data.

Platform API supports operations for retrieving analysis result data:

• A loss table returns output data (metrics, statistics, and metadata) for an EP or non-EP analysis. Loss tables are generated from analysis using both probabilistic and deterministic models. DLM analysis data is stored in an event loss table (ELT). HD analysis results are stored in a period loss table (PLT). EP metrics and statistics are based loss table data.
• EP metrics define quantitative measurements that represent probability that losses will exceed a certain amount. EP metrics are computed for DLM or HD analysis using probabilistic models.
• Statistics is a calculation based on loss table data. Platform returns statistics for both probabalistic and deterministic models.
• Result metadata is data about analysis including the financial perspectives, regions, cedants, and treaties that factored into the analysis result.

Distinct data is available in the result depending on the model (ALM, DLM, HD) and type (EP, non-EP) of the analysis.

Analysis Types

The Intelligent Risk Platform supports a variety of deterministic and probabalistic analysis types for each model type (ALM, DLM, HD).

Every analysis of an exposure is defined by a model profile and output profile. The output profile specifies analysis settings including the analysis type, engine, and the peril.

Different analysis types are available for different perils. The analysis type may be available for some regions and unavailable in others.

Loss Tables

A loss table is a table of output data (metrics and statistics) computed for loss-causing events.

Platform analysis generates loss tables for both deterministic and probable analysis models. Analysis data based on ALM and DLM models are stored in event loss tables (ELTs). Analysis data based on ALM and DLM models are stored in event loss tables (ELTs).

Metrics and statistics are based on output data.

Event loss tables

The event loss table (ELT) is an output table that loss-causing events in a DLM analysis, including the mean loss standard deviation (split into an independent and a correlated piece), exposure value, and event rate.

For each event, the table lists metrics, statistics, and metadata that characterize that event. This data is used to compute EP curves and statistics based on this output data. The ELT is the basis of losses for all financial perspectives at all exposure levels and is used in computing output statistics.

The Get ELT operation returns an array of objects that returns metrics, statistics, and metadata for each event.

[
  {
    "analysisId": 83343,
    "sourceId": 22257,
    "eventId": 276,
    "positionValue": 3473657.880534969,
    "perspectiveCode": "GU",
    "stdDevI": 1066771.2741421806,
    "stdDevC": 400576.7724183246,
    "expValue": 4343900.0,
    "rate": 1.2056769946866552e-6,
    "peril": "Windstorm",
    "region": "North America",
    "oepWUC": 1.205676267823641e-6,
    "exposureResourceId": 0,
    "exposureResourceType": "UNRECOGNIZED",
    "exposureResourceNumber": "string"
  }
]

Period loss tables

The period loss table (PLT) is an output table that simulates event losses over the course of a time period for a HD analysis. The PLT provides greater flexibility to evaluate loss metrics than the analytical calculations based on event loss tables (ELTs).

By simulating events through time, an HD model computes total loss as well as maximum event occurrence loss for each simulation period in the table, and generates loss statistics based on the distribution of losses across the large number of simulated periods. This methodology can calculate the impact of all contract terms, including terms with time-based features, such as contracts that are shorter (or longer) than a single year.

The Get PLT operation returns period loss table calculated using an HD model for the specified HD analysis result.

PLT data may be filtered by exposureResourceType. One of ACCOUNT, PORTFOLIO, LOCATION, POLICY, STEP_POLICY, TREATY, AGGPORTFOLIO

[
  {
    "periodId": 503,
    "weight": 2.0e-5,
    "eventId": 3508644,
    "eventDate": "2020-08-07T00:00:00.000Z",
    "lossDate": "2020-08-13T00:00:00.000Z",
    "positionValue": 111642.35349968076,
    "peril": "Earthquake",
    "region": "string",
    "exposureResourceNumber": "string"
  }
]

Non-EP Sampled Losses

The Get Non-EP Sampled Losses operation returns sampled non-EP losses from the PLT (period loss table) of the specified analysis result.

This operation takes four required parameters: analysisId, perspectiveCode, exposureResourceType, and events, a comma-separated list of events identified by event ID. The optional lossSampleLimit parameter...

An event is a representation of a peril with the potential to generate catastrophe losses. For a given peril, all potential events are synthesized into a stochastic event set, which defines the occurrence and magnitude of each event.

For each event, the response returns the eventId, sampleId, lossType, and loss, as well as the names of the cedant (cedantName) and line of business (lobName) associated with that loss.

[
  {
    "cedantName": "string",
    "lobName": "string",
    "lossType": "string",
    "sampleId": 0,
    "eventId": 0,
    "loss": 0
  }
]

EP Metrics

An EP analysis computes EP curves based on loss table data. An EP curve is a cumulative distributions showing the probability that losses will exceed a certain amount, from either single or multiple occurrences. Losses are expressed in the occurrence exceedance probability (OEP) and the aggregate exceedance probability (AEP) curves.

AEP and OEP curves are two different curves that have two distinct uses and offer different information. Both curves show the probability that losses will exceed a given threshold.

Metrics are quantitative measurements." "Metrics are the raw data you collect to measure aspects of the product, and analytics is the process of interpreting the data to gain insights and make data-driven decisions." An EP analysis returns an EP curve which consists of computed metrics.

EP Interpolation Metrics

The Get EP interpolation metrics operation returns EP metrics based on interpolated return period or critical probability values.

This operation accepts a new returnPeriod or criticalProbability value, which it inserts ("interpolates") into the PLT of the specified HD EP analysis. The Intelligent Risk Platform then computes new EP curves based on the interpolated value and returns updated EP metrics for the new return period. The request can also specify the perpectiveCode that defines the financial structure used to calculate modeled losses.

For example, the following request interpolates a new return period and specifies that metrics are calculated based on the GR (gross loss) financial perspective.

{
  "returnPeriod": 13,
  "criticalProbability": 0.075,
  "result": [
    {
      "perspectiveCode": "GR",
      "values": [
        {
          "metricName": "TCE-OEP",
          "metricValue": "68418.2476820577"
        }
      ]
    }
  ]
}

An exceedance probability (EP) curve indicates the probability that losses will exceed a given threshold within a year. This operation returns AEP curves and OEP curves.

This operation returns the following result properties:

EP metrics [EP Metrics (DLM Models)]

Returns exceedence probability (EP) metrics for the specified <glossary:ALM> or <glossary:DLM>> analysis result.

DLM and ALM EP analyses write modeled losses to an event loss table (ELT), compute EP metrics, and calculate summary statistics based on ELT data.

EP metrics define EP curves that represent the probability that losses will exceed a certain threshold. ALM and DLM analysis supports five types of EP curves: OEP (occurence EP), AEP (aggregate EP), CEP (stochastic conditional EP), TCE-AEP (tail conditional expectation AEP), and TCE-OEP (tail conditional expectation OEP) curves.

The Get EP Metrics request returns an array EP curves:

[
  {
    "jobId": 8,
    "epType": "AEP",
    "perspectiveCode": "GU",
    "exposureResourceId": 0,
    "exposureResourceType": "PORTFOLIO",
    "exposureResourceNumber": "8",
    "value": {
      "returnPeriods": [
                        1.0,
                        2.0,
                        3.0,
                        4.0,
                        5.0,
                        ...,
                        5000.0,
                       ],
      "positionValues": [
                         0,
                         0,
                         0,
                         1.4336826286215238,
                         2898128.185059362,
                         ...,
                         2923391.5767636155
                        ]
    }
  }
]

For each EP curve, the response shows the following:

Marginal EP Metrics

The Get Marginal EP Metrics operation returns projected differential losses expressed as marginal EP curves for the specified analysis result. This operation may be used to retrieve marginal EP metrics modeled using ALM, DLM, or HD models.

"Marginal impact analysis enables insurers to identify higher-risk policyholders who may require revised premiums or additional risk management measures."

An exceedance probability (EP) curve indicates the probability that losses will exceed a given threshold within a year. This operation returns four different types of EP curves: AEP, OEP, TCE-AEP, and TCE-OEP curves.

A marginal EP curve shows projected losses and differential losses (as raw numbers and percentage) between X and Y at each position in the curve. These numbers enable you to view the projected loss for X and Y at any given position, the difference between the value of X and Y at that position, and the percent difference between X and Y.

The request accepts three required parameters an analysisId, perspectiveCode exposureResourceType that specify the scope of the query.

[
  {
    "exposureResourceId": 0,
    "exposureResourceType": "UNRECOGNIZED",
    "exposureResourceNumber": "string",
    "perspectiveCode": "Empty",
    "epType": "UNRECOGNIZED",
    "value": {
      "returnPeriods": [0],
      "eps": [0],
      "positionValues": [0],
      "positionValueDiffs": [0],
      "positionValueDiffPercents": [0]
    }
  }
]

The number of marginal EP curves returned depends on engine to model the results.

Different EP curves may be returned depending on the model used in the analysis:

Statistics

A statistic (AKA loss statistic) is a calculation performed on output data, e.g. in an ELT or PLT. A standard deviation, mean loss, coefficient of variation are all statistics. Compare metrics.

Get Statistics

The Get Statistics operation returns a list of DLM-based metrics by analysis result.

Unlike other operations that retrieve metrics and statistics, this operation returns data from multiple analysis results.

Statistics include the average annual loss, standard deviation, and coefficient of variation.

[
  {
    "analysisId": 54,
    "exposureResourceId": 765,
    "exposureResourceType": "ACCOUNT",
    "perspectiveCode": "TY",
    "epType": "AEP",
    "purePremium": 0,
    "totalStdDev": 0,
    "cv": 2.808502733065068,
    "netPurePremium": 85213.63686810755,
    "activation": 0.19734192801321804,
    "exhaustion": 0.06465721482368603,
    "totalLossRatio": 0.17429420184027278,
    "limit": 900000,
    "premium": 25000,
    "netStdDev": 231466.464883724,
    "exhaustAllReinstatements": 0.0004301273657816296,
    "exposureResourceNumber": "Cat_EntirePort"
  }
]

For each analysis result, the response returns the following properties:

Marginal Statistics

The Get Marginal Statistics operation returns marginal statistics for the specified analysis result.

Treaty Losses: Risk Modeler makes losses viewable at the individual treaty level so that you can better assess capacity and coverage and make corresponding pricing decisions. You can view losses at the treaty level for the treaty types listed in Table 67. Add treaties pre- and post-analysis for DLM, ALM, and HD analyses. Risk Modeler does not include the ability to view individual facultative losses.

The loss dashboard displays the following: Return period losses, along with Aggregate Exceedance Probability curves (AEP) and Occurrence Exceedance Probability curves (OEP), Pure Premium (AAL), Standard Deviation, Coefficient of Variation (CV).

The request takes three required parameters: analysisId, perspectiveCode, and granularity.

Responses may be optionally filtered and sorted using query string parameters.

The response returns marginal statistics.

[
  {
    "exposureResourceId": 26113,
    "exposureResourceType": "TREATY",
    "exposureResourceNumber": "Cat_EntirePort_04",
    "perspectiveCode": "TY",
    "epType": "AEP",
    "limit": 900000,
    "exhaustion": 0.06465721482368603,
    "activation": 0.19734192801321804,
    "cv": 2.808502733065068,
    "cvDiff": 2.7163077811358347,
    "cvDiffPercent": 0,
    "totalStdDev": 3676637.4187586145,
    "totalStdDevDiff": 0,
    "totalStdDevDiffPercent": 0,
    "totalLossRatio": 0.17429420184027278,
    "netStdDev": 231466.464883724,
    "premium": 0,
    "purePremium": 493148.5493424345,
    "purePremiumDiff": 0,
    "purePremiumDiffPercent": 2.7777777777777777,
    "netPurePremium": 85213.63686810755,
    "exhaustAllReinstatements": 0.0004301273657816296
  }
]

Depending on the model, returns treaty-level losses for the following treaty types:

This operation does not return individual facultative losses.

Get Non-EP Statistics

The Get Non-EP Statistics operation returns key losses by event for the specified analysis result.

A non-EP analysis is a deterministic analysis based on a user-specified set of events. The Platform API supports several types of deterministic analysis, including footprint analysis, historical analysis, and scenario analysis.

The response returns an array of key loss metrics for each event modeled:

[
  {
    "eventId": 2864907,
    "stdDev": 1663.1549792686967,
    "meanLoss": 0,
    "cv": 6.62779067641994
  }
]

For each event, the response returns cv, meanLoss, and stdDev metrics:

Location-Level Statistics

The Get Location-Level Statistics operation returns average annual loss (AAL), coefficient of variation (CV), and standard deviation statistics for modeled location exposures. Using these statistics, underwriters can identify the location exposures in their portfolios that are at the greatest risk.

To help inform pricing and underwriting decisions, generate the following location-level results for detailed loss model (DLM) and high-definition (HD) results. Location-level losses are not available for ALM:

Location-level statistics are available for analysis results based on both DLM and HD models. These statistics are not available for analysis using ALM.

Location-level ELT and EP curves can be generated using DLM models. , you can also generate EP and Loss Table output at the location level.

The request must specify an analysis ID that was computed using an output profile.

To generate these location-level losses, create an output profile that uses Granularity=Risk for EP and Loss Table output (DLM only). For Statistics output, risk-level granularity is already selected by default (available for both HD and DLM).

For each location, the response returns the locationId, locationName, locationNumber, and AAL statistics.

[
  {
    "locationId": 58,
    "locationName": "Location_Name",
    "locationNumber": "Location_Num",
    "aal": 294.25022798552993,
    "cv": 5.652179067641994,
    "stdDev": 1663.1549792686967
  },
  {
    "locationId": 60,
    "locationName": "Location_Name",
    "locationNumber": "Location_Num",
    "aal": 274.25022798662993,
    "cv": 6.62779067641994,
    "stdDev": 1234.1549792686967
  }
]

Analysis Metadata

Analysis metadata is data about any analysis that provides information about the exposure modeled or analysis configurations defined in the model profile e.g. the region, cedant, or treaty applied to the analyzed exposure.

This data is helpful for understanding the significance of the computed losses, metrics, and statistics in an analysis result.

The Risk Data API supports the operations that enable you to retrieve following analysis metadata.

List Financial Perspectives by Analysis

The List Financial Perspectives by Analysis operation returns financial perspective data about the specified analysis.

A financial perspective (also called a position) is a financial structure that determines how loss statistics are calculated.

For example, the ground up loss (GU) financial perspective represents total loss to the exposure and excludes any insurance or reinsurance terms in the loss calculations. The gross loss (GR) financial perspective represents the loss to the insurer, accounting for the application of all insurance terms but without consideration for any reinsurance recoveries.

This operation returns an array of the financial perspectives used to calculate losses in an analysis. For each financial analysis, returns the code and name:

[
  {
    "perspectiveCode": "GR",
    "perspectiveName": "Gross Loss"
  },
  {
    "perspectiveCode": "GU",
    "perspectiveName": "Gross Up Loss"
  }
]

Multiple positions can be output for the same analysis, and the relevance of each position varies between users and use cases. Some financial perspectives affect estimates of property (P) loss or worker's compensation (WC) loss. To learn more, see Financial Perspectives

List Region Details by Analysis

The List Region Details by Analysis operation returns information about an analysis including details about exposures modelled and the model used in the analysis.

This operation returns an array of the analysis details by region. For each region, this operation returns information about the exposure modeled and model profile details.

[
  {
    "region": "string",
    "subRegion": "string",
    "peril": "Unrecognized",
    "eventRateSchemeId": 0,
    "framework": "ELT",
    "analysisId": 0,
    "modelProfileId": 0,
    "petId": 0,
    "numSamples": 0,
    "periods": 0,
    "applyContractFlag": true,
    "engineVersion": "HDv1.0"
  }
]

List Treaties by Analysis

The List Treaties by Analysis operation returns treaty data about the specified analysis.

A treaty is an agreement between a primary insurer and a reinsurer in which the primary insurer cedes a portion of risk to the reinsurer.
The terms of the treaty

List Treaty Details by Analysis

The Get Treaty Details by Analysis operation returns detailed information about a treaty applied to a specific analysis.

A treaty is an agreement between a primary insurer and a reinsurer in which the primary insurer cedes a portion of risk to the reinsurer.
The terms of the treaty

This operation returns the following detailed infomation about the specified treaty:

{
  "treatyId": 0,
  "treaty": "string",
  "treatyName": "string",
  "cedant": {
    "cedantId": 22,
    "cedantName": "CSW"
  },
  "producer": {
    "producerId": 3,
    "producerName": "rena"
  },
  "treatyType": "CATA",
  "currency": {
    "id": 0,
    "code": "string",
    "name": "string"
  },
  "attachmentBasis": "L",
  "attachmentLevel": "PORT",
  "premium": 0,
  "occurrenceLimit": 0,
  "attachmentPoint": 0,
  "riskLimit": 0,
  "retentionAmount": 0,
  "percentagePlaced": 0,
  "effectiveDate": "2020-01-01T00:00:00.000Z",
  "expirationDate": "2020-01-01T00:00:00.000Z",
  "percentageRetention": 0,
  "percentageRiShare": 0,
  "percentageCovered": 0,
  "priority": 0,
  "numberOfReinstatements": 0,
  "reinstatementCharge": 0,
  "maolAmount": 0,
  "isValid": true,
  "userId1": "string",
  "userId2": "string",
  "aggregateDeductible": 0,
  "aggregateLimit": 0,
  "uri": "string",
  "lobs": [
    {
      "lobId": 9,
      "lobName": "FACTORY",
      "uri": "/riskdata/v1/exposures/5/lobs/9"
    }
  ],
  "lossOccurrences": [
    {
      "id": 0,
      "treatyId": 0,
      "uri": "string",
      "regionPeril": {
        "id": 0,
        "code": "string",
        "name": "string"
      },
      "lossOccurrenceTime": 0,
      "lossOccurrenceRadius": 0,
      "radiusUnit": {
        "id": 0,
        "code": "string",
        "name": "string"
      },
      "multiLossOccurrence": {
        "id": 0,
        "code": "string",
        "name": "string"
      }
    }
  ],
  "analysisId": 0,
  "tagIds": [0]
}

This operation returns the following detailed infomation about the specified treaty: