公募基金组合风险分析 API 接口

公募基金组合风险分析 API 接口

接口详情官网地址: https://www.gugudata.com/api/details/fundportfolioriskanalysis

公募基金组合风险分析 API 根据 2 至 10 只公募基金及其组合权重，返回组合和单只基金的历史收益、波动率、最大回撤、VaR、CVaR、风险贡献、相关性及分散化指标。接口适合用于基金组合监控、投研看板、量化预检和智能投顾后台，帮助业务系统以结构化方式评估历史风险与组合分散效果。

1. 产品功能

• 支持一次提交 2 至 10 只公募基金，并按用户指定权重分析组合风险；
• 支持 6 个月和 1 年历史分析窗口，以及 95% 和 99% 两种置信水平；
• 返回组合年化收益、年化波动率、最大回撤、VaR、CVaR 和分散化比率；
• 返回每只基金的有效观察数、覆盖率、年化收益、年化波动率、最大回撤和风险贡献；
• 返回基金两两相关性和下行相关性，便于识别同涨同跌及下跌共振；
• 通过 AVAILABLE、PARTIAL 和 UNAVAILABLE 明确标识分析结果的可用程度；
• 提供数据质量警告和稳定原因码，便于业务系统自动降级、提示和审计；
• 不会静默移除数据不足的基金，也不会自动重新分配用户提交的组合权重；
• 仅返回历史风险分析指标，不提供涨跌预测、基金评分、买卖建议或调仓建议；

2. API 文档

接口地址: https://api.gugudata.com/ai/fund/portfolio-risk-analyses

返回格式: application/json; charset=utf-8

请求方式: POST

请求协议: HTTPS

请求示例: https://api.gugudata.com/ai/fund/portfolio-risk-analyses

请求头: Authorization: Bearer YOUR_APPKEY

请求体示例:

{
  "Positions": [
    {
      "FundCode": "012729",
      "Weight": 0.3
    },
    {
      "FundCode": "290008",
      "Weight": 0.25
    },
    {
      "FundCode": "000001",
      "Weight": 0.25
    },
    {
      "FundCode": "110022",
      "Weight": 0.2
    }
  ],
  "Period": "1Y",
  "ConfidenceLevel": 0.95
}

数据预览: https://www.gugudata.com/preview/fundportfolioriskanalysis

接口测试: https://api.gugudata.com/ai/fund/portfolio-risk-analyses/demo

3. 请求参数

参数名	参数类型	是否必须	默认值	备注
appkey	string	是	YOUR_APPKEY	开发者中心获取的 APPKEY。推荐通过 Authorization: Bearer YOUR_APPKEY 传递，也兼容 X-GUGUDATA-APPKEY、X-API-Key 请求头和 appkey 查询参数；不属于 JSON 请求体。
Positions	array	是	见请求体示例	基金持仓数组，必须包含 2 至 10 个对象；FundCode 不得重复。
Positions[].FundCode	string	是	012729	由 6 位数字组成的公募基金代码，必须以 JSON 字符串传递以保留前导零。
Positions[].Weight	number	是	0.3	当前组合权重，必须为大于 0 的有限小数；全部 Weight 之和与 1 的误差不得超过 0.000001。
Period	string	否	1Y	历史分析窗口，支持 6M 或 1Y；6M 至少需要 100 个有效观察，1Y 至少需要 200 个有效观察。
ConfidenceLevel	number	否	0.95	单日历史模拟 VaR 和 CVaR 的置信水平，仅支持 0.95 或 0.99。

4. 返回参数

参数名	参数类型	备注
DataStatus.RequestParameter	string	脱敏请求摘要，仅包含基金数量、分析周期和置信水平，不包含基金代码、权重或 APPKEY。
DataStatus.StatusCode	integer	业务状态码，100 表示请求正常完成。
DataStatus.Status	string	机器可读的错误状态，成功响应通常不返回。
DataStatus.StatusDescription	string	本次请求的业务状态说明。
DataStatus.ResponseDateTime	string	服务端响应时间，格式为 YYYY-MM-DD HH:mm:ss.SSS。
DataStatus.DataTotalCount	integer	当前响应中的分析结果数量，成功分析通常为 1。
DataStatus.RequestId	string	请求追踪标识，咨询技术支持时可提供该值，但不要提供 APPKEY。
DataStatus.NoDataReason	string	统一响应层的无数据原因码；详细原因以 Data.NoDataReasons 为准。
Data.AnalysisStatus	string	分析状态，支持 AVAILABLE、PARTIAL 或 UNAVAILABLE。
Data.ModelVersion	string	本次分析使用的模型版本。
Data.Period	string	实际采用的历史分析周期，取值为 6M 或 1Y。
Data.ConfidenceLevel	number	VaR 和 CVaR 计算采用的置信水平，取值为 0.95 或 0.99。
Data.WeightingMethod	string	组合收益的权重方法，当前为 CONSTANT_WEIGHT。
Data.DataStartDate	string	组合公共样本的起始交易日期，格式为 YYYYMMDD。
Data.DataEndDate	string	组合公共样本的结束交易日期，格式为 YYYYMMDD。
Data.SnapshotTime	string	本次风险分析的数据快照时间，采用包含时区偏移的 ISO 8601 格式。
Data.ObservationCount	integer	全部基金共有的有效交易日期数量。
Data.CoverageRatio	number	公共日期数占全部有效日期并集的比例，范围为 0~1。
Data.RequestedFundCount	integer	请求中提交的基金数量。
Data.AnalyzedFundCount	integer	满足数据要求并完成个体指标计算的基金数量。
Data.PortfolioMetrics	object	组合层历史风险指标；数据不足时为 null。
Data.PortfolioMetrics.AnnualizedReturn	number	组合年化收益率，以小数表示。
Data.PortfolioMetrics.AnnualizedVolatility	number	组合年化波动率，以小数表示。
Data.PortfolioMetrics.MaximumDrawdown	number	分析期内组合最大回撤，按正数小数表示。
Data.PortfolioMetrics.MaximumDrawdownStartDate	string	最大回撤起始日期，格式为 YYYYMMDD；无回撤时为 null。
Data.PortfolioMetrics.MaximumDrawdownEndDate	string	最大回撤结束日期，格式为 YYYYMMDD；无回撤时为 null。
Data.PortfolioMetrics.ValueAtRisk	number	按 ConfidenceLevel 计算的单日 VaR，采用正损失口径。
Data.PortfolioMetrics.ConditionalValueAtRisk	number	超过 VaR 阈值后的单日平均尾部损失，采用正损失口径。
Data.PortfolioMetrics.DiversificationRatio	number	组合分散化比率；不可计算时为 null。
Data.FundMetrics	array	按请求顺序返回每只基金的历史风险指标、覆盖率和组合风险贡献。
Data.FundMetrics[].FundCode	string	6 位基金代码。
Data.FundMetrics[].FundName	string	基金名称，无法取得时为 null。
Data.FundMetrics[].Weight	number	请求中该基金的组合权重。
Data.FundMetrics[].AnalysisStatus	string	单只基金的分析状态，取值为 AVAILABLE 或 UNAVAILABLE。
Data.FundMetrics[].ObservationCount	integer	该基金在分析周期内的有效观察数。
Data.FundMetrics[].CoverageRatio	number	该基金有效日期数占全部基金有效日期并集的比例。
Data.FundMetrics[].AnnualizedReturn	number	该基金年化收益率，数据不足时为 null。
Data.FundMetrics[].AnnualizedVolatility	number	该基金年化波动率，数据不足时为 null。
Data.FundMetrics[].MaximumDrawdown	number	该基金最大回撤，数据不足时为 null。
Data.FundMetrics[].RiskContribution	number	该基金对组合风险的贡献占比，组合不可计算时为 null。
Data.PairwiseDependencies	array	满足样本门槛的基金两两依赖关系。
Data.PairwiseDependencies[].FundCodeA	string	相关性基金代码 A。
Data.PairwiseDependencies[].FundCodeB	string	相关性基金代码 B。
Data.PairwiseDependencies[].Correlation	number	两只基金的相关系数，范围为 -1~1；不可计算时为 null。
Data.PairwiseDependencies[].DownsideCorrelation	number	下跌样本中的相关系数；样本不足或不可计算时为 null。
Data.DataQuality	object	当前周期的数据门槛、最新数据年龄和标准化警告信息。
Data.DataQuality.MinimumObservationCount	integer	当前周期要求的最低有效观察数。
Data.DataQuality.LatestDataAgeDays	integer	数据最新记录距分析日期的天数。
Data.DataQuality.Warnings	array	标准化数据质量警告码数组。
Data.NoDataReasons	array	基金级或组合级不可计算原因数组。
Data.NoDataReasons[].FundCode	string	原因对应的基金代码；组合级原因时为 null。
Data.NoDataReasons[].Reason	string	稳定原因码，例如 FUND_NOT_FOUND、INSUFFICIENT_OBSERVATIONS 或 STALE_HISTORY。
Data.ComplianceNotice	string	历史风险分析免责声明。
Data.IsDemo	boolean	是否为免鉴权演示结果，正式 POST 请求为 false。

5. 错误码说明

状态码	错误说明	备注
100	正常返回	需要结合 AnalysisStatus 判断分析数据完整性。
501	参数错误	请检查基金代码、持仓数量、权重、周期和置信水平。
502	请求频率受限	请按照当前套餐限制降低请求频率。
503	账号已过期	请确认接口订单有效期。
504	APPKEY 错误	请检查 APPKEY 及接口权限。
901	服务暂不可用	历史数据服务暂不可用，请稍后重试。

6. 适用场景

• 适合用于基金组合监控看板，持续观察组合收益、波动率、最大回撤和尾部风险变化。
• 适合用于投研和量化预检，在提交研究结论前检查组合相关性、下行相关性和风险贡献。
• 适合用于智能投顾后台和资产配置工具，为用户展示结构化历史风险与分散效果。
• 适合用于自动化风控流程，根据 AnalysisStatus、数据质量警告和原因码执行提示或降级处理。
• 接口结果基于历史数据，仅用于风险研究和信息参考，不构成投资建议或收益承诺。

7. 相关接口

• 前置接口：基金基本信息，用于获取和校验标准 6 位公募基金代码。
• 可搭配使用：公募基金历史数据，用于查询基金历史净值、收益和排名数据。
• 可搭配使用：公募基金实时净值，用于补充基金最新净值和申赎状态。