Overview

RMS APIs support query string parameters that provide you with better control over the data returned from a resource. Query string parameters are especially useful in top-level resources that return lists of exposure objects such as lists of accounts, profiles, or treaties.

A query string parameter is a type of REST API parameter that is appended to a resource endpoint. Where the endpoint defines the path to a resource, the query string parameter controls the scope or order of the data returned from that resource.

Use query string parameters to specify a data source to query; and to filter, sort, and paginate the data returned from that data source. The query string parameter is appended to the service endpoint using the ? character.

Synopsis

RMS 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 service. 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 services enable you to filter and identify relevant analysis results using the exposureId, jobId, jobUUID, perspective, and treatyId query strings.

Data source filters

The datasource query string parameter identifies a specific data source (EDM) to query.

GET /portfolios?datasource=api_edm_3

Many tenants manage their exposure data in multiple EDM data sources. Consequently, the datasource query string parameter is generally required when requesting data from a resource.

Query filters

The q query parameter keyword enables you to define a query string parameter that selects records using attribute value filters and comparison operators. Multiple expressions may be linked together using logical operators.

The q keyword supports four matching operations: comparison, logical, and list operations.

Comparison operators

The q keyword supports comparative queries that return records that match a specified attribute values. These queries support six operators.

The query consists of the q keyword, an attribute, a comparison operator, and a condition that specifies an attribute value. The query compares the value of the specified attribute in each record with the value of the specified condition and selects records that match. Attribute value strings are not case sensitive.

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

Risk Modeler supports the = != > < LIKE and NOT LIKEoperators.

• The = operator selects records with attribute values that exactly match a specified attribute value. The = comparison operator may be used to select records attribute values that match strings and numbers.
• The != operator selects records with attribute values that do not match the specified attribute value. The != comparison operator may be used to filter records based on string or number values.
• The > operator selects records with numerical attribute values that are greater than the specified attribute value.
• The < operator selects records with numerical attribute values that are less than than the specified attribute value.
• The LIKE operator selects records with attribute values that match the specified string pattern. The asterisk character (*) may be used as a wildcard character to represent zero or more characters. The LIKE operator may be used to compare strings and numbers.
• The NOT LIKE operator selects records with attribute values that do not match the specified string pattern. The asterisk character (*) may be used as a wildcard character to represent zero or more characters. The NOT LIKE operator may be used to compare strings and numbers.

List operators

The q keyword supports queries that return records that based on values that are or are not is a specified list of attribute values.

• The IN operator selects records with attribute values that match an attribute value specified in a list of attribute values. The IN operator may be used to compare strings and numbers.
• The NOT IN operator selects records with attribute values that do not match an attribute value specified in a list of attribute values. The IN operator may be used to compare strings and numbers.

Logical operators

Some Risk Modeler API services enable you to create complex queries by stringing together multiple attribute value filters using logical operators. The q keyword supports logical queries that return records based on complex queries that compare the value of expresssions.

A logical operator is a keyword that connects two or more expressions to create a compound expression.

GET /portfolios?datasource=ds1&limit=3&sort=number ASC&q=number LIKE "Portfolio_*" AND (description = 1) OR (ownerName ="roland_alphonso")

The Risk Modeler API enables you to create complex expressions using the AND and the OR logical operators:

• In an complex expression using the AND logical operator, both expressions must be true for the complex expression to be true.
• In an complex expression using the OR logical operator, either expression may be true for the complex expression to be true.

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 service.

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 pages 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 page 1:

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

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

Analysis result filters

Metrics API services enable you to filter analysis results based query string parameters that specify analysis result attributes values.

• The exposureId query string parameter filters result data by the ID number of a specific exposure.
• The jobId query string parameter filters result data by the ID number of an analysis job.
• The treatyId query string parameter filters data by the treaty ID number.
• The jobUUID query string parameter filters data by the job UUID.
• The userName query string parameter filters data by the name of a user who an analysis job.
• The runDate query string parameter filters data by the date that the analysis was run.
• The exposureType query string parameter filters data by exposure type.
• The perspective query string parameter filters data by financial perspective, i.e. the financial structures that were taken into consideration in the calculation of the loss statistics.
• The metricType query string parameter filters data by metric type.

For example, the Location AAL service enables you to filter analytics results by financial perspective.

curl --location --request GET 'https://{env_url}/riskmodeler/v1/analyses/100257/location-aal?perspective=GR' \

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.

Exposure type filters

The optional exposureType parameter enables the client to filter perspectives by exposure type. If unspecified, the service uses the default value of 0 and returns all exposure types. The exposureType query parameter may be defined by the following values:

• 0: Default. Returns persectives for all exposure types
• 7937: Treaty
• 7938: PortByCedant
• 7939: AccountCoverage
• 7940: EQLocationCvgDetail
• 7941: HULocationCvgDetail
• 7942: TOLocationCvgDetail
• 7943: PortByRegion
• 7950: PortByPostCode
• 7951: PortByPostCodeLOB
• 7952: PortByLocCode
• 7953: PortByLocCodeLOB
• 7954: PortByDistrict
• 7955: PortByDistrictLOB
• 7956: PortByCity
• 7957: PortByCityLOB
• 7958: PortByCounty
• 7959: PortByCountyLOB
• 7960: PortByCresta
• 7961: PortByCrestaLOB
• 7962: PortByState
• 7963: PortByStateLOB
• 7964: PortByLOB
• 7965: PortInjuryLevel
• 7966: AcctInjuryLevel
• 7967: PolicyInjuryLevel
• 7968: LocationInjuryLevel
• 7969: LocPeopleGroupInjuryLevel
• 7970: PolicySpecialConditions
• 7971: BuildingCoverage
• 7972: BuildingInjuryLevel
• 7975: PortByCountry
• 7976: PortByCountryByLOB
• 7977: PortByPostCodeByCedant
• 7981: PortByCountyByCedant
• 7982: PortByCrestaByCedant
• 7983: PortByStateByCedant
• 7984: PortByCountryByCedant
• 7986: PortByPostCodeByLOBByCedant
• 7990: PortByCountyLOBByCedant
• 7991: PortByCrestaLOBByCedant
• 7992: PortByStateLOBByCedant
• 7993: PortByCountryByLOBByCedant
• 8017: Portfolio
• 8019: Account
• 8020: Location
• 8021: Policy
• 8022: LocationCoverage
• 8023: PolicyCoverage
• 8024: ReinsuranceCession
• 8025: EQLocationDetail
• 8026: HULocationDetail
• 8027: TOLocationDetail
• 8028: FLLocationDetail
• 8029: AggPortfolio
• 8030: PortfolioCoverage
• 8031: LocationPeopleGroup
• 8035: Building
• 9000: Fac

Perspective filters

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

GU Ground Up Loss
GS Ground Up Specified Loss
G2 Ground Up Loss - Secondary Peril
G1 Ground Up Loss - Primary Peril
CL Client Loss
UC Underlying Coverage
OL Over Limit Loss
OI Other Insurer’s Loss
GR Gross Loss
FA Faculative Reinsurance Loss
SS Surplus Share Treaty Loss
QS Quota Share Treaty Loss
WX Working Excess Treaty Loss
RL New Loss Pre Cat
RP Net Loss Post Cat
RC Net Loss Post Corporate Cat
RG Reinsurance Gross Loss
RN Reinsurance New Loss

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.

Metric type filters

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

ELT event loss table
EP exceedence probability
STATS Statistics