FactSet Open Risk API
Through this API one can get a comprehensive access to factor-based linear risk analytics engine, offering flexible and powerful risk analyses with full capability.
OpenAPI Specification
openapi: 3.0.3
info:
title: Factset Open Risk API
description: >-
Service to calculate parametric linear risk statistics and generate risk
model asset identifier mappings.
version: 1.24.0
contact:
name: FactSet Research Systems
email: [email protected]
url: https://developer.factset.com/contact
license:
name: Apache License, Version 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
tags:
- name: Linear
servers:
- url: https://api.factset.com/analytics/openrisk
paths:
/linear/{version}/riskmodels:
get:
summary: Factset Get available risk models
description: >-
Get the list of available risk models, including their respective model
codes required for use with other routes.
operationId: listRiskModels
tags:
- Linear
parameters:
- $ref: '#/components/parameters/VersionPath'
responses:
'200':
$ref: '#/components/responses/ListRiskModelsSuccess'
'401':
$ref: '#/components/responses/MissingOrInvalidAuthentication'
'404':
$ref: '#/components/responses/EndpointNotFound'
'429':
$ref: '#/components/responses/RateLimitReached'
'500':
$ref: '#/components/responses/InternalServerErrorJsonOnly'
/linear/{version}/riskmodels/{modelCode}:
get:
summary: Factset Get risk model details
description: >-
Get the meta data of the risk model for the corresponding modelCode.
modelCode can be obtained via '/linear/{version}/riskmodels/' route.
operationId: riskModelMetadata
tags:
- Linear
parameters:
- $ref: '#/components/parameters/VersionPath'
- $ref: '#/components/parameters/RiskModelCodePath'
responses:
'200':
$ref: '#/components/responses/RiskModelDetailsSuccess'
'401':
$ref: '#/components/responses/MissingOrInvalidAuthentication'
'404':
$ref: '#/components/responses/EndpointNotFound'
'429':
$ref: '#/components/responses/RateLimitReached'
'500':
$ref: '#/components/responses/InternalServerErrorJsonOnly'
/linear/{version}/stats:
get:
summary: Factset Get available risk statistics details
description: >-
All base risk statistic names and their respective support and/or
requirement for certain name-settings statistics options (such as:
correlated specific risk, covariance isolation method, etc.), available
levels, and security group calculation methodology. When
'securityGroupMethod' is 'statSpecific', please refer to statistics
documentation service for more information.
operationId: stats
tags:
- Linear
parameters:
- $ref: '#/components/parameters/VersionPath'
responses:
'200':
$ref: '#/components/responses/ListRiskStatisticsDetails'
'401':
$ref: '#/components/responses/MissingOrInvalidAuthentication'
'404':
$ref: '#/components/responses/EndpointNotFound'
'429':
$ref: '#/components/responses/RateLimitReached'
/linear/{version}/stats-names-only:
get:
summary: Factset Get available risk statistics names
description: >-
All available risk statistic names including statistics names containing
risk statistics options such as CSR (correlated specific risk)
operationId: statsNamesOnly
tags:
- Linear
parameters:
- $ref: '#/components/parameters/VersionPath'
responses:
'200':
$ref: '#/components/responses/ListRiskStatisticsNames'
'401':
$ref: '#/components/responses/MissingOrInvalidAuthentication'
'404':
$ref: '#/components/responses/EndpointNotFound'
'429':
$ref: '#/components/responses/RateLimitReached'
/linear/{version}/health:
get:
summary: Factset Get health of service
description: Health status of the service
operationId: healthStatus
tags:
- Linear
parameters:
- $ref: '#/components/parameters/VersionPath'
responses:
'200':
$ref: '#/components/responses/HealthPass'
'401':
$ref: '#/components/responses/MissingOrInvalidAuthentication'
'403':
$ref: '#/components/responses/HealthFailAuthorization'
'404':
$ref: '#/components/responses/HealthFailVersionNotFound'
'429':
$ref: '#/components/responses/RateLimitReached'
/linear/{version}/calculate/from-holdings:
post:
summary: Factset Calculate risk statistics
description: >-
Calculate predicted risk statistics for provided holdings using risk
model data. Asset symbols and market values/weights are required.
operationId: calculateFromHoldings
tags:
- Linear
parameters:
- $ref: '#/components/parameters/VersionPath'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CalculateFromHoldingsRequestBody'
example:
data:
stats:
- name: ActiveVarianceToRisk
level: Portfolio
- name: ActiveVarianceToRisk
level: SecurityGroup
- name: PortfolioWeights
level: Security
- name: BenchmarkWeights
level: Security
- name: ActiveWeights
level: Security
- name: ActiveFactorVarianceToRisk
level: Security
settings:
correlatedSpecificRisk: true
- name: ActiveFactorVarianceToRiskCSR
level: Security
- name: ActiveFactorRisk
level: FactorGroup
settings:
covarianceTimesTwo: true
- name: PortfolioReturnAtRiskPercentWithContribution
level: Portfolio
settings:
confidenceLevel: 0.95
daysPerYear: 250
horizon: 1
- name: RawResidualRisk
level: Security
- name: RawSecurityFactorRisk
level: Security
- name: RawFactorExposure
level: FactorSecurity
- name: RawFactorExposure
level: FactorSecurity
settings:
sparse: true
- name: PortfolioExposure
level: Factor
settings:
sparse: true
holdings:
portfolio:
ids:
- IBM
- FDS
- CA_ETF
- CASH_GBP_CFD
- CFD_B10RZP
marketValues:
- 60
- 30
- 30
- -30
- 30
grouping:
groups:
- name: USD
groups:
- name: Direct Assets
indices:
- 0
- 1
- name: Composite Assets
indices:
- 2
- name: GBP
indices:
- 4
- name: Offset Cash
indices:
- 3
benchmark:
ids:
- B10RZP
- IBM
- MSFT
marketValues:
- 30
- 40
- 30
grouping:
groups:
- name: GBP
indices:
- 0
- name: USD
groups:
- name: Direct Assets
indices:
- 1
- 2
underlyingIds:
CFD_B10RZP: B10RZP
compositeAssets:
CA_ETF:
ids:
- FDS
- IBM
marketValues:
- 10
- 90
assetTypes:
CFD_B10RZP: OTH_CFD
factorGrouping:
name: >-
This factor grouping is incomplete; it omits factors for the
sake of brevity and is not recomended for actual use.
nodes:
- name: Market
nodes:
- id: GLOBAL_MARKET
- name: Style
nodes:
- name: Market Factors
nodes:
- id: BETA
- id: LIQUIDITY
- id: MOMENTUM
- id: SIZE
- id: VOLATILITY
- name: Fundamental Factors
nodes:
- id: BOOK_TO_PRICE
- id: DIVIDEND_YIELD
- id: EARNINGS_YIELD
- id: GROWTH
- id: LEVERAGE
factorsVisible:
list:
- FX_GBP
- FX_USD
type: Whitelist
allowForcedRisklessAssets: true
currency: USD
riskModel: FDS:GLOBAL_EQUITY_M_V1
date: '2021-05-31'
calendar: FIVEDAY
responses:
'200':
$ref: '#/components/responses/CalculateFromHoldingsSuccess'
'400':
$ref: '#/components/responses/BadRequestOrDataUnavailable'
'401':
$ref: '#/components/responses/MissingOrInvalidAuthentication'
'403':
$ref: '#/components/responses/AccessForbidden'
'404':
$ref: '#/components/responses/EndpointNotFound'
'429':
$ref: '#/components/responses/RateLimitReached'
'500':
$ref: '#/components/responses/InternalServerErrorJsonOnly'
/linear/{version}/generate/id-mapping:
post:
summary: Factset Generate risk model ID mapping
description: >-
Resolve all input holdings IDs against a risk model for coverage and
provide a mapping to security indices in the model or the reason for
exclusion
operationId: generateIdMapping
tags:
- Linear
parameters:
- $ref: '#/components/parameters/VersionPath'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateIDMappingRequestBody'
example:
data:
holdings:
portfolio:
grouping:
groups:
- name: USD
groups:
- name: Direct Assets
indices:
- 0
- 1
- name: Composite Assets
indices:
- 2
- name: GBP
indices:
- 4
- name: Offset Cash
indices:
- 3
ids:
- IBM
- FDS
- CA_ETF
- CASH_GBP_CFD
- CFD_B10RZP
marketValues:
- 60
- 30
- 30
- -30
- 30
benchmark:
grouping:
groups:
- name: GBP
indices:
- 0
- name: USD
groups:
- name: Direct Assets
indices:
- 1
- 2
- name: Other - Uncovered Assets
indices:
- 3
ids:
- B10RZP
- IBM
- MSFT
- FAKE_UNCOVERED_ASSET
marketValues:
- 30
- 30
- 30
- 10
allowForcedRisklessAssets: true
assetTypes:
CFD_B10RZP: OTH_CFD
calendar: FIVEDAY
compositeAssets:
CA_ETF:
ids:
- FDS
- IBM
marketValues:
- 10
- 90
currency: USD
date: '2021-05-31'
riskModel: FDS:GLOBAL_EQUITY_M_V1
underlyingIds:
CFD_B10RZP: B10RZP
responses:
'200':
$ref: '#/components/responses/GenerateIDMappingSuccess'
'400':
$ref: '#/components/responses/BadRequestOrDataUnavailable'
'403':
$ref: '#/components/responses/AccessForbidden'
'404':
$ref: '#/components/responses/EndpointNotFound'
'429':
$ref: '#/components/responses/RateLimitReached'
'500':
$ref: '#/components/responses/InternalServerErrorJsonOnly'
components:
schemas:
StatCalculationLevel:
description: Stat levels available for calculation
type: string
minLength: 1
enum:
- Portfolio
- Security
- SecurityGroup
- SecuritySecurity
- Factor
- FactorGroup
- FactorFactor
- FactorSecurity
- FactorGroupSecurity
- FactorSecurityGroup
- FactorGroupSecurityGroup
StatCalculationSettings:
description: >-
Settings to modify an individual statistic's calculation. See also
[OA:17698](https://my.apps.factset.com/oa/pages/17698#risk) and
[OA:16097](https://my.apps.factset.com/oa/pages/16097#cov2) for cov*2.
type: object
properties:
useAbsoluteWeightsForLotExpansion:
type: boolean
default: true
covarianceTimesTwo:
type: boolean
default: false
covarianceTimesTwoTerm:
type: boolean
default: false
correlatedSpecificRisk:
description: >-
When this is set to true, specific risk correlation adjustment will
be applied to security level as well as portfolio level. An example
case where stock specific correlation is supplied by risk models is
the case between parent equity and ADR.
type: boolean
default: false
sparse:
description: >-
When this is set to true, the matrix and vector output is in
compressed sparse row matrix format. Vector is considered as a
matrix with one row for compressed sparse row matrix output. This
only applies for matrix and vector output, not for single data
points e.g. stats at Portfolio level.
type: boolean
default: false
horizon:
type: number
daysPerYear:
type: number
confidenceLevel:
type: number
lamda:
type: number
specificToFactorRatio:
type: number
rapSys:
type: number
rapUnsys:
type: number
Stat:
description: Risk statistic name and calculation level plus optional stat settings
type: object
required:
- name
- level
properties:
name:
type: string
minLength: 1
level:
$ref: '#/components/schemas/StatCalculationLevel'
settings:
$ref: '#/components/schemas/StatCalculationSettings'
Stats:
description: List of risk stats and settings to calculate
type: array
minItems: 1
maxItems: 1000
items:
$ref: '#/components/schemas/Stat'
IDsAndMarketValues:
description: >-
Security IDs and market values; the arrays must have the same number of
items. Public security IDs such as SEDOL, CUSIP, ISIN, and Ticker are
supported. If proprietary IDs are provided, they need to be mapped via
composite assets. Market values are used to calculate weights and do not
have to be normalized, but need to be denominated in the single same
currency ISO.
type: object
required:
- ids
- marketValues
properties:
ids:
type: array
minItems: 0
items:
type: string
minLength: 1
marketValues:
type: array
minItems: 0
items:
type: number
format: double
SecurityGroup:
description: >-
Security grouping definition to use in calculation and results.
Multi-layer security groupings are also suppoted.
type: object
properties:
name:
type: string
minLength: 1
indices:
description: >-
List of 0-based indices into the containing holding's security IDs
array
type: array
minItems: 1
items:
type: integer
groups:
description: >-
Recursively defined elements; base case array (i.e., lowest security
group) contains objects with 'indices' only and not 'groups'
type: array
minItems: 1
items:
$ref: '#/components/schemas/SecurityGroup'
Holding:
description: >-
Security IDs and market values plus optional security grouping; the
arrays must have the same number of items. Public security IDs such as
SEDOL, CUSIP, ISIN, and Ticker are supported. If proprietary IDs are
provided, they need to be mapped via composite assets. Market values are
used to calculate weights and do not have to be normalized, but need to
be denominated in the single same currency ISO.
type: object
allOf:
- $ref: '#/components/schemas/IDsAndMarketValues'
- properties:
grouping:
$ref: '#/components/schemas/SecurityGroup'
uncoveredAssets:
description: >-
Uncovered asset weight handling. Default values: 'portfolio' ->
ExcludeToGlobalCash, 'benchmark' -> Normalize, 'market' ->
Normalize. See also
[OA:21737](https://my.apps.factset.com/oa/pages/21737#group_normal_mix)
type: string
minLength: 1
enum:
- Normalize
- ExcludeToGlobalCash
- NormalizeWithGroupCash
- ExcludeToCashWithinGroup
- NormalizeWithinGroup
Holdings:
type: object
required:
- portfolio
properties:
portfolio:
$ref: '#/components/schemas/Holding'
benchmark:
$ref: '#/components/schemas/Holding'
market:
$ref: '#/components/schemas/Holding'
RiskModelFactor:
description: Individual factor from the risk model
type: object
required:
- id
properties:
id:
description: Factor ID from the risk model
type: string
minLength: 1
FactorGroupNodes:
oneOf:
- $ref: '#/components/schemas/FactorGroup'
- $ref: '#/components/schemas/RiskModelFactor'
FactorGroup:
description: >-
Factor grouping definition to use for calculations and results. This
field impacts the calculation only when any 'FactorGroup' level
statistics are requested, e.g. 'FactorGroup', 'FactorGroupSecurity'.
type: object
required:
- nodes
properties:
name:
description: Name of this factor group
type: string
minLength: 1
nodes:
description: >-
Recursively defined elements; base case array (i.e., lowest factor
group) contains 'RiskModelFactor' objects only and no 'FactorGroup'
objects
type: array
minItems: 1
items:
$ref: '#/components/schemas/FactorGroupNodes'
RiskModelCode:
description: Model code
type: string
minLength: 1
example: FDS:GLOBAL_EQUITY_M_V1
StringDate:
description: >-
**(since 1.1.0)** Any FactSet-accepted string date format, except that
"NOW" is not supported by risk analysis. For more, refer to
[OA:1964](https://my.apps.factset.com/oa/pages/1964#rel).
type: string
minLength: 1
example: '-3M'
StandardDate:
description: '**(since 1.12.0)** Date format YYYY-MM-DD.'
type: string
format: date
example: '2019-01-26'
Date:
description: >-
Date of risk model and holdings data to fetch and use. For the use of
Relative Date argument, refer to
[OA:1964](https://my.apps.factset.com/oa/pages/1964#rel). Ignored only
for composite asset definitions provided as inputs via 'compositeAssets'
field.
oneOf:
- $ref: '#/components/schemas/StringDate'
- $ref: '#/components/schemas/StandardDate'
AssetTypes:
description: >-
**(since 1.4.0)** A mapping of security ID to its asset type as the
standard asset type keys. When this input is in a request, it is used to
(1) identify assets that use Underlying IDs from 'underlyingIds' input,
and (2) identify asset types compatible with automatic removal of their
contribution of currency to risk unless any form of the
'removeCurrencyRisk' input is also provided. When this input is used in
the request, underlying IDs (provided via 'underlyingIds' input) are
only respected for the following standard asset type keys (all other
underlying IDs will be discarded): refer to
[OA:22019](https://my.apps.factset.com/oa/pages/22019) for compatible
asset type keys and more details.
type: object
example:
FDS: EQ_EQ_COMMON
CFDTOIBM: OTH_CFD
additionalProperties:
type: string
minLength: 1
CurrencyISOCode:
description: >-
ISO-4217 currency code for risk model and holdings data to fetch and
use. Ignored only for composite asset definitions provided as inputs via
'compositeAssets' field.
type: string
minLength: 1
example: EUR
CalendarCode:
description: >-
Calendar code for risk model and holdings data to fetch and use. Ignored
only for composite asset definitions provided as inputs via
'compositeAssets' field. See also
[OA:2012](https://my.apps.factset.com/oa/pages/2012#calendar) for global
codes, "FIVEDAY" or "SEVENDAY" calendars and see
[OA:16610](https://my.apps.factset.com/oa/pages/16610#country) for
country codes (cf. 'Calendar Code' column).
type: string
minLength: 1
example: FJH
ExposureDateFormatConvention:
description: Factor exposure matrix date.
oneOf:
- $ref: '#/components/schemas/StringDate'
- $ref: '#/components/schemas/StandardDate'
CovarianceDateFormatConvention:
description: Factor covariance matrix date.
oneOf:
- $ref: '#/components/schemas/StringDate'
- $ref: '#/components/schemas/StandardDate'
LaggingDates:
description: >-
Risk model lagging dates for data items to fetch and use. This field can
be utilized to isolate each data item's impact on risk calculation. A
typical use case is to analyze the risk change from one day to the other
by fixing the risk model data date to one date while moving the
portfolio holdings data.
type: object
properties:
exposureDate:
$ref: '#/components/schemas/ExposureDateFormatConvention'
covarianceDate:
$ref: '#/components/schemas/CovarianceDateFormatConvention'
ssrDateIs:
description: >-
Stock specific risk (SSR) date can take one of the other lagging
dates
type: string
minLength: 1
enum:
- ExposureDate
- CovarianceDate
RequiresFactorReturns:
description: >-
Indicates factor returns are required and which frequency from the risk
model to fetch and use. The requested factor return frequency must be
one that is available from the selected risk model itself. The
orientation of factor return is forward-looking. For example, if daily
factor return is called, and 'date' is set as '2021-06-30', factor
return date range used for calculation is 2021-06-30 to 2021-07-01,
assuming no holidays in these two dates.
type: string
minLength: 1
enum:
- Daily
- Monthly
CompositeAssetDefinitions:
description: >-
IDs to be defined as composite assets with their constituents' IDs and
market values. The typical use case is for risk look-through of ETF or
Funds' constituents. When defining composite assets and creating
portfolios which hold them, the IDs provided must be an exact match.
type: object
additionalProperties:
$ref: '#/components/schemas/IDsAndMarketValues'
example:
CA1_to_IBM_and_CA2:
ids:
- IBM
- CA2
marketValues:
- 0.45
- 0.55
CA2:
ids:
- VZ
- cfd_FDS
marketValues:
- 0.6
- 0.4
FactorsVisible:
description: >-
Hide risk model factors in the response results; does not affect
calculated data values
type: object
required:
- list
- type
properties:
list:
description: List of risk model factor IDs
type: array
minItems: 1
items:
type: string
minLength: 1
type:
type: string
minLength: 1
enum:
- Whitelist
- Blacklist
UnderlyingIDs:
description: >-
A map of security IDs to their underlying IDs. When 'assetTypes' input
is in a request, underlying IDs provided via this input are only
respected for the following standard asset type keys (all other
underlying IDs will be discarded): refer to
[OA:22019](https://my.apps.factset.com/oa/pages/22019) for compatible
asset type keys and more details.
type: object
additionalProperties:
type: string
minLength: 1
example:
CFD_IBM: IBM
cfd_FDS: FDS
RemoveCurrencyRiskBoolean:
description: >-
**(since 1.11.0)** Enables or disables the removal of the contribution
of currency to risk based upon asset type (Contract for Difference
(CFD), equity futures, and index futures). This single-boolean schema
field will have no effect without valid 'assetTypes' input in the
request also.
type: boolean
default: true
RemoveCurrencyRiskIDs:
description: >-
Security IDs from which the contribution of currency to risk should be
removed or not. Typical use includes asset types such as Contract for
Difference (CFD), equity futures, and index futures. This will override
the automatic currency removal based on assetTypes when provided. If
this input type is provided, all assets that do not have explicit
specification will have currency risk, because the default value is
false.
type: object
additionalProperties:
type: boolean
example:
CFD_IBM: true
cfd_FDS: false
RemoveCurrencyRisk:
description: >-
Controls removal (or not) of the contribution of currency to risk.
**Note:** If this input is not provided in the request, then currency
risk will be removed automatically based upon asset type when valid
'assetTypes' are specified in the request.
oneOf:
- $ref: '#/components/schemas/RemoveCurrencyRiskBoolean'
- $ref: '#/components/schemas/RemoveCurrencyRiskIDs'
RiskModelAppendDataValue:
description: Value for field at respective integer key index
oneOf:
- type: string
minLength: 1
- type: number
RiskModelAppendData:
description: >-
**(since 1.17.0)** Inline append data. This field can be used mainly for
two purpose: 1) to supplement the risk model coverage when assets are
not natively covered by a model, and 2) to intentionally override asset
exposures and/or specific risk whenever there is misaligned view of an
asset's risk profile between a model and a user.
type: object
required:
- data
- fields
properties:
data:
description: List of all rows of the append data.
type: array
minItems: 1
items:
description: >-
Contains field, value pairs. The field must be the integer index
position of the field in 'fields', but must be as a string. The
value will be the data for that field. Values for a single field
must have the same data type.
type: object
additionalProperties:
$ref: '#/components/schemas/RiskModelAppendDataValue'
example:
'1': SYMBOL_2
'2': 7.2
example:
- '0': 2.5
'1': SYMBOL_1
'2': 23.1
- '1': SYMBOL_2
'2': 7.2
fields:
description: >-
List of fields in append data. Must contain 'SYMBOL'. Index location
will be used in 'data' elements as keys. The entire set of factor
IDs and specific risk are not required. If any inputs of exposures
or specific risk are missing, 0 will be inserted for those field.
type: array
minItems: 1
uniqueItems: true
items:
type: string
minLength: 1
example:
- FACTOR_1
- SYMBOL
- STDERR
AllowForcedRisklessAssets:
description: >-
Allow certain assets to be entirely riskless; certain models always
override this to be true. Examples of asset types to which this applies
includes offset cash.
type: boolean
default: false
AdditionalCalculationInputs:
description: >-
Additional user-defined calculation input values. For example, some may
be required for some Risk-Based Performance Attribution (RBPA) stats,
such as 'ResidualFactorReturnsCSR' and 'DeannualizedActiveFactorRisk'.
type: object
properties:
marketExcess:
description: >-
User-defined values (all required) to compute the desired arbitrary
'excess return' of the market portfolio (which is usually intended
to be defined as a broad market index).
type: object
required:
- return
- riskFreeRate
- riskPremium
- riskPrem
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/factset/refs/heads/main/openapi/open-risk-openapi-original.yml