Overview

Metrics API operations support the filtering of analysis result data by means of query string parameters that specify analysis result attributes values.

The API reference documentation page list the query parameters that are supported by each operation. For example, the Get Metrics operation supports the metricType, position, granularity, epType, returnPeriod, filterCondition, sort, limit, and offset query parameters.

Using analysis results query parameters in tandem with the sort query parameter makes it easy for you to compare the metrics returned so that you may identify exposures at the greatest risk.

Synopsis

Moody's Risk Modeler supports five basic query string parameters: datasource, q, sort, limit, and offset.

Every query string parameter is defined by a parameter keyword, a query string, and a comparison operator (=) that connects the parameter keyword to the query string. You can use the & operator to append multiple query string parameters to the endpoint.

• A datasource query string parameter defines a filter that specifies the EDM to query.
• A q query string parameter defines an attribute value filter that selects the data returned from a resource. The q keyword supports four filtering operations: comparison operations, logical operations, list operations and matching operations.
• A sort query string parameter specifies an attribute on which to sort and the sort order (alphabetical or numerical) for the records returned from the resource. One of ASC for ascending or DESC for descending.
• A limit query string parameter specifies the number of records to display per page. By default, 100.
• An offset query string parameter specifies the number of pages that are offset before the initial page of records returned. By default, 0.

Some Metrics API resources enable you to filter and identify relevant analysis results using the exposureId, jobId, jobUUID, perspective, and treatyId query strings.

Filters

EP curve type filters

The epType query parameter enables you to filter metrics by EP curve types. Options include AEP, OEP, TCE_AEP, and TCE_OEP.

An EP curve is a cumulative distribution 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.

For example, the Get Metrics operation supports filtering by EP type:

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses/analysisID/metrics?granularity=POLICY& \
		 epType=AEP& \
		 epType=TCE_AEP& \
		 limit=100& \
		 offset=0' \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

Risk Modeler API supports the following EP curve type query parameters as filters:

Event ID filters

The eventIds query parameter enables you to filter result metrics by event IDs.

An event is a representation of a peril (e.g. earthquake, flood, hurricane) 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. Events within an event set are identified by a unique event ID.

The Get ELT and Get Sampled Losses operations supports filtering by Event IDs.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses/id/elt?perspective=RN& \
		 treatyId=56& \
		 eventIds=6789& \
		 eventIds=6790& \
		 eventIds=6791 \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

Exposure ID filters

The exposureId query parameter enables you to filter metrics by exposure ID.

An exposure is an entity that may produce a financial loss when impacted by an event. Exposures are identified by their exposure type and a unique ID number.

The exposure ID identifies the exposure (e.g. location, account, portfolio) analyzed.

The Get ELT, Get EP Metrics, Get EP Interpolation, Get Key Losses, Get PLT, Get Sampled Losses, and Get Statistics operations support filtering by exposure IDs.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses/id/elt?exposureId=45' \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

Exposure type filters

The exposureType query parameter enables the client to filter perspectives by exposure type. If unspecified, the resource uses the default value of 0 and returns all exposure types.

Each exposure type is identified by a four-digit numberic code, e.g. 8017 (Portfolio or Group), 8019 (Account), 8020 (Location).

The Get ELT, Get EP Metrics, Get EP Interpolation, Get Key Losses, Get Financial Perspectives, Get PLT, Get Sampled Losses, and Get Statistics operations support filtering by exposure IDs.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses/35/keylosses?exposureType=8020'

The exposureType query parameter may be defined by the following values:

Filter condition filters

The filterCondition query parameters enable you to filter metrics by job IDs.

The Get Metrics operation supports filtering by return periods and filter conditions.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses/analysisID/metrics?returnPeriod=33&filterCondition=condition&limit=100&offset=0' \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

Granulariy filters

The granularity query parameters enable you to filter metrics by output levels.

The Get Metrics operation supports filtering by the POLICY granularity.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses/analysisID/metrics?granularity=POLICY& \
		 epType=AEP& \
		 epType=TCE_AEP& \
		 limit=100& \
		 offset=0' \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

Job ID filters

The jobId query parameters enable you to filter metrics by job IDs.

The jobId parameter is supported by all Risk Modeler GET operations in the Metrics collection.

curl --request GET \
     --url 'https://{host}/riskmodeler/v1/analyses/analysisID/elt?perspective=GU& /
		 jobUUID=a433baa3-8e1e-47ff-8098-f8781d9b3c32& /
		 exposureId=8& /
		 exposureType=8017& /
		 jobId=134866' /
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

Job UUID filters

The jobuuid query parameters enable you to filter metrics by job UUIDs.

The jobUUID parameter is supported by all Risk Modeler GET operations in the Metrics collection.

curl --request GET \
     --url 'https://{host}/riskmodeler/v1/analyses/analysisID/elt?perspective=GU& /
		 jobUUID=a433baa3-8e1e-47ff-8098-f8781d9b3c32& /
		 exposureId=8& /
		 exposureType=8017& /
		 jobId=9064540' /
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

Key and value filters

The key and value query parameters enable you to filter metrics by key-value attributes.

The Get EP Interpolation operation supports filtering by keys and key values.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses/id/ep/interpolate?key=key& \
		 value=value' \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

Metric type filters

The metricType query parameter enables you to filter analysis result data based on the metrics.

The Get EP Metrics, Get EP Interpolation, and Get Metrics operation supports filtering by metric types. One of ELT, EP, or STATS.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses/45/ep?metricType=ELT'

Risk Modeler API supports the following metric type parameter values:

Perspective filters

The perspective query parameter identifies the financial perspective. Financial perspectives are identified by a two-character string.

The Get Cedants by Result, Get ELT, Get EP Interpolation, Get Key Losses, Get Location AAL Metrics, Get Metrics, Get PLT, Get Sampled Losses, and Get Statistics operations support filtering by financial perspective.

curl --request GET \
     --url 'https://{host}//riskmodeler/v2/analyses/34/location-aal?perspective=GR \
            &sort=AAL%20DESC \
            &limit=100 \
            &offset=0'

Risk Modeler supports the following perspective query parameters as filters:

Financial perspectives are understood to be upstream or downstream of one another. The position of one perspective relative to one another perspective is an important factor in financial perspective mapping. For more information, see Map perspective by analysis.

Return period filters

The returnPeriod query parameter enables you to filter by return period.

A return period is a point on an EP curve that describes the likelihood of exceeding a loss threshold from the single largest event (OEP) or the aggregation of one or more events (AEP). The return period is defined as the inverse of the annual exceedance probability. For example, a return period of 100 years corresponds to an annual exceedance probability of 1%. In the context of peril events, return period refers to the number of years between occurrences of an event of a given size in the region. Short and long return periods enable modelers to estimate risk at both short and long-range exceedance probabilities.

The Get Metrics operation supports filtering by return periods. Must be a value between 2 and 49999.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses/analysisID/metrics?returnPeriod=2500& \
		 limit=100& \
		 offset=0' \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

Run date filters

The runDate query parameter enables you to filter analysis results by the date the analysis was processed.

The Get Results operation supports filtering by run date.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/[email protected]& \
		 runDate=2022-12-23'

Treaty ID filters

The treatyId query parameter enables you to filter analysis results by treaty ID.

By viewing losses at the treaty-level, you can better assess capacity and coverage and make corresponding pricing decisions.

The Get EP Metrics, Get ELT, Get EP Interpolation, Get key Losses, Get PLT, Get Sampled Losses, and Get Statistics operations support treaty ID filtering.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses/id/elt?perspective=RN& \
		 treatyId=56& \
		 eventIds=6789& \
		 eventIds=6790& \
		 eventIds=6791 \
     --header 'Authorization: XXXXXXXXXX' \
     --header 'accept: application/json'

User name filters

The userName query parameter enables you to filter analysis results by the name of the principal that submitted that analysis job.

A principal is an entity that identifies an authorized end user or client application. Intelligent Risk Platform supports two principals: user accounts for end users of applications and API keys for client applications. Principals gain access rights and permissions to protected resources by being members of a group that has been granted those access rights and permissions.

For example, the Get Results operation supports user name filtering.

curl --request GET \
     --url 'https://{host}/riskmodeler/v2/analyses?userName=p_name& \
		 runDate=date-string'

Pagination

Sort data

The sort query string parameter enables you to specify the attribute on which returned records are sorted and the sort order (ascending or descending) for those records.

Use the = operator to specify the sort column. In the following example, the returned records are sorted in ascending order based on the attribute value in the number column.

GET /portfolios?datasource=ds1&limit=3&sort=number ASC&q=number LIKE "Portfolio_*"

By default, Risk Modeler API services returns data sorted by a predefined attribute. If no attribute is specified, the service sorts records in ascending order on the default column.

Records may be sorted in ascending (ASC) or descending (DESC) order.

Page data

The limit and offset query string parameters enable you to paginate data returned from a resource.

These two query string parameters are always used together. The size of a page will affect the size of the offset. Where the limit query string parameter specifies the number of records returned per page, the offset query string parameter specifies the number of records that are "off set" before records are returned.

The following request returns records from the ds1 data source, filtered for the year 2018, listed in ascending order, showing 25 records a page starting with record 11:

GET /portfolios?datasource=ds1&q=year=2018&sort=year=ASC&limit=25&offset=10

The default limit setting is 100 records per page. The default offset setting is 0 records.