# 公募基金组合风险分析
> 来源页面: https://www.gugudata.com/api/details/fundportfolioriskanalysis
## 概览
- API 标识: `fundportfolioriskanalysis`
- 分类: 商业/分析
- 描述: 基金组合历史风险与分散分析
- 标签: 基金组合 / 风险分析 / 分散度
- 短标签: 基金组合 / 风险分析 / 分散度
- 详情页: https://www.gugudata.com/api/details/fundportfolioriskanalysis
- LLM Markdown: https://www.gugudata.com/api/details/fundportfolioriskanalysis/llm.md
- 数据预览: https://www.gugudata.com/preview/fundportfolioriskanalysis
- 购买开通: https://www.gugudata.com/order/fundportfolioriskanalysis
- APP KEY 管理: https://www.gugudata.com/portal/
- 订单与续费: https://www.gugudata.com/portal/orders
## 给大模型的接入指令
如果你正在帮助用户接入这个 API，请优先使用本文档中的接口地址、请求方式、请求参数、返回参数、状态码、cURL 示例和预览数据生成代码或排查问题。
- 接入目标: 调用 `公募基金组合风险分析`，不要臆造未在文档中出现的参数或返回字段。
- AppKey 获取: 用户登录咕咕数据开发者中心后，在 `APP KEY 管理` 页面复制对应产品的 AppKey。
- AppKey 替换: 示例中的 `YOUR_APPKEY`、`APPKEY`、`{{YOUR_APPKEY}}`、`{{appkey}}`、`{{appKey}}` 都应替换为用户自己的 AppKey。
- AppKey 传递: 推荐使用 `X-GUGUDATA-APPKEY` 或 `X-API-Key` 请求头；OpenAI 兼容客户端可使用 `Authorization: Bearer <AppKey>`；历史 query 参数 `appkey` 继续有效。
- 开通与续费: 未开通时引导用户访问购买开通页；已开通或需要续费时，引导用户进入开发者中心或订单与续费页。
- 错误处理: HTTP 状态码代表传输层结果，响应体内的业务状态码代表接口业务结果，代码中应分别处理。
- 生产建议: AppKey 应保存在服务端环境变量或密钥配置中，由服务端统一发起请求，不要写入网页、App 客户端或公开仓库。
关键链接:
- 接口详情页: https://www.gugudata.com/api/details/fundportfolioriskanalysis
- LLM Markdown: https://www.gugudata.com/api/details/fundportfolioriskanalysis/llm.md
- 数据预览: https://www.gugudata.com/preview/fundportfolioriskanalysis
- 购买开通页: https://www.gugudata.com/order/fundportfolioriskanalysis
- 开发者中心 APP KEY 管理: https://www.gugudata.com/portal/
- 订单与续费: https://www.gugudata.com/portal/orders
## API 功能
- 按基金代码和持仓权重分析组合风险；
- 支持 6 个月或 1 年分析周期；
- 支持 95% 或 99% 置信水平；
- 提供组合年化收益与年化波动率；
- 提供最大回撤及对应日期区间；
- 提供 VaR 与 CVaR 风险指标；
- 展示单只基金的收益、波动与风险贡献；
- 展示基金相关性与下行相关性；
- 展示组合分散效果与数据完整性；
- 结果基于历史数据，不构成投资建议；
- 默认最大 QPS:5，可在开发者中心自助升级，月付年付订单接口调用次数不限。
- [接口调用状态与状态监控](https://www.gugudata.com/status)
## 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`
- 接口测试: https://api.gugudata.com/ai/fund/portfolio-risk-analyses/demo
- Apifox: https://doc.gugudata.com/
- Postman: https://www.postman.com/gugudata/gugudata-official/collection/1163860-22cb92f5-771a-48fd-89c0-f20a0790a8ce/?action=share&creator=1163860&active-environment=1163860-a95b31ef-324f-43db-b2fc-faa41f45bd35
- OpenAPI: https://www.gugudata.com/openapi/gugudata.openapi.3.1.json
## 鉴权方式
接口支持以下 AppKey 传递方式，任选一种即可；已有请求示例、Postman 集合和历史代码仍可继续使用原来的 `appkey` 参数方式。
| 传输载体 | 参数 | 示例 | 说明 |
| --- | --- | --- | --- |
| HTTP Header | `X-GUGUDATA-APPKEY` | `X-GUGUDATA-APPKEY: YOUR_APPKEY` | 推荐方式，适合服务端接入和统一封装。 |
| HTTP Header | `X-API-Key` | `X-API-Key: YOUR_APPKEY` | 通用 API Key Header，便于和常见 API 客户端集成。 |
| HTTP Header | `Authorization` | `Authorization: Bearer YOUR_APPKEY` | 适合 OpenAI 兼容接口或 Bearer Token 风格客户端。 |
| Query 参数 | `appkey` | `?appkey=YOUR_APPKEY` | 兼容现有示例、Postman 集合、浏览器调试和历史代码。 |
> 部分历史 POST 接口仍兼容表单或 JSON body 中的 `appkey`；新接入建议优先使用 Header 或 Query 参数。
## 请求参数
| 参数名 | 参数类型 | 是否必须 | 默认值 | 备注 |
| --- | --- | --- | --- | --- |
| appkey | string | 是 | YOUR_APPKEY | 付费后获取的 APPKEY。推荐使用 Authorization: Bearer YOUR_APPKEY；也支持 AppKey、X-GUGUDATA-APPKEY、X-API-Key 请求头和 appkey 查询参数。APPKEY 不属于 JSON 请求体 |
| Positions | array | 是 | [{"FundCode":"012729","Weight":0.3},{"FundCode":"290008","Weight":0.25},{"FundCode":"000001","Weight":0.25},{"FundCode":"110022","Weight":0.2}] | JSON 持仓数组，必须包含 2 至 10 个对象；FundCode 不得重复，返回结果保持提交的基金与权重 |
| Positions[].FundCode | string | 是 | 012729 | 六位数字组成的公募基金代码，必须以 JSON 字符串传递以保留前导零，例如 012729 |
| Positions[].Weight | number | 是 | 0.3 | 当前组合权重，使用有限且大于 0 的小数；全部 Weight 之和与 1 的误差不得超过 0.000001，服务端不会自动归一化 |
| Period | string | 否 | 1Y | 历史分析窗口，可选 6M 或 1Y，默认 1Y。6M 至少需要 100 个有效观察，1Y 至少需要 200 个有效观察 |
| ConfidenceLevel | number | 否 | 0.95 | 单日历史模拟 VaR 和 CVaR 的置信水平，仅支持 0.95 或 0.99，默认 0.95 |
## 返回参数
| 参数名 | 参数类型 | 备注 |
| --- | --- | --- |
| DataStatus.RequestParameter | string | 服务端生成的脱敏请求摘要，仅包含基金数量、分析周期和置信水平，不包含基金代码、权重或 APPKEY |
| DataStatus.StatusCode | integer | 业务状态码。100 表示请求正常完成；501 参数错误；502 请求频率受限；503 账号过期；504 APPKEY 错误；505 调用额度不足；900 服务内部错误；901 服务暂不可用 |
| DataStatus.Status | string | 机器可读的错误状态；成功响应通常不返回。参数错误为 invalid_argument，服务不可用为 service_unavailable |
| DataStatus.StatusDescription | string | 本次请求的中文状态说明；程序判断应优先使用 StatusCode 和 AnalysisStatus |
| DataStatus.ResponseDateTime | string | 服务端响应时间，格式为 YYYY-MM-DD HH:mm:ss.SSS |
| DataStatus.DataTotalCount | integer | 当前响应中的分析结果数量；成功分析通常为 1，错误响应为 0 |
| 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 | 全部请求基金严格共有的有效交易日期数量；该值不足周期门槛时 PortfolioMetrics 为 null |
| Data.CoverageRatio | number | 全部基金严格公共日期数除以有效日期并集数量，范围为 0 至 1，越接近 1 表示日期对齐越完整 |
| Data.RequestedFundCount | integer | 请求中提交的基金数量 |
| Data.AnalyzedFundCount | integer | 满足周期数据要求并完成个体指标计算的基金数量 |
| Data.PortfolioMetrics | object | 组合层历史风险指标。仅当全部基金和严格公共样本均满足周期要求时返回对象，否则为 null |
| Data.PortfolioMetrics.AnnualizedReturn | number | 基于组合日收益几何复利并按 252 个交易日年化；可为负数，小数表示，例如 0.08 表示 8% |
| Data.PortfolioMetrics.AnnualizedVolatility | number | 组合年化波动率，按小数表示，例如 0.12 表示 12% |
| Data.PortfolioMetrics.MaximumDrawdown | number | 分析期内组合累计收益从历史峰值到后续谷值的最大跌幅，按正数小数表示 |
| Data.PortfolioMetrics.MaximumDrawdownStartDate | string | 最大回撤起始日期，格式为 YYYYMMDD；无回撤时为 null |
| Data.PortfolioMetrics.MaximumDrawdownEndDate | string | 最大回撤结束日期，格式为 YYYYMMDD；无回撤时为 null |
| Data.PortfolioMetrics.ValueAtRisk | number | 按 ConfidenceLevel 计算的单日历史模拟风险价值，采用正损失口径；例如 0.02 表示阈值损失为 2% |
| Data.PortfolioMetrics.ConditionalValueAtRisk | number | 超过 VaR 阈值后的单日平均尾部损失，采用正损失口径，并保证 CVaR 大于等于 VaR |
| Data.PortfolioMetrics.DiversificationRatio | number | 加权个体年化波动率之和除以组合年化波动率；通常大于 1 表示存在分散化效果，零方差时为 null |
| Data.FundMetrics | array | 按请求顺序返回每只基金的个体历史风险指标、覆盖率和组合风险贡献 |
| Data.FundMetrics[].FundCode | string | 六位基金代码 |
| Data.FundMetrics[].FundName | string | 基金名称；历史序列未提供名称时为 null |
| Data.FundMetrics[].Weight | number | 请求中该基金的组合权重 |
| Data.FundMetrics[].AnalysisStatus | string | 该基金的个体指标状态，取值为 AVAILABLE 或 UNAVAILABLE；组合整体状态另见 Data.AnalysisStatus |
| Data.FundMetrics[].ObservationCount | integer | 该基金在分析周期内的有效观察数 |
| Data.FundMetrics[].CoverageRatio | number | 该基金有效日期数占全部基金有效日期并集的比例 |
| Data.FundMetrics[].AnnualizedReturn | number | 该基金日收益按几何复利和 252 个交易日年化；数据不足时为 null |
| Data.FundMetrics[].AnnualizedVolatility | number | 该基金日收益样本标准差按 252 个交易日年化；数据不足时为 null |
| Data.FundMetrics[].MaximumDrawdown | number | 该基金在分析期内从峰值到谷值的最大跌幅，按正数小数表示；数据不足时为 null |
| Data.FundMetrics[].RiskContribution | number | 该基金对组合风险的贡献占比；单只基金允许为负，组合可计算时各项之和约等于 1 |
| Data.PairwiseDependencies | array | 满足周期样本门槛的基金两两依赖关系；每个无序基金对返回一条记录 |
| Data.PairwiseDependencies[].FundCodeA | string | 相关性基金代码 A |
| Data.PairwiseDependencies[].FundCodeB | string | 相关性基金代码 B |
| Data.PairwiseDependencies[].Correlation | number | 两只基金在严格公共日期上的 Pearson 相关系数，范围为 -1 至 1；零方差等不可计算情况为 null |
| Data.PairwiseDependencies[].DownsideCorrelation | number | 全部基金组合收益小于 0 的严格公共交易日期上计算；所有基金对使用同一组下行日期。少于 30 个下行样本或零方差时为 null |
| Data.DataQuality | object | 当前周期的数据门槛、最旧最新记录的数据年龄和标准化警告码 |
| Data.DataQuality.MinimumObservationCount | integer | 当前周期要求的最低有效观察数 |
| Data.DataQuality.LatestDataAgeDays | integer | 最旧一只基金的最新记录距分析日期的天数 |
| Data.DataQuality.Warnings | array | 数据质量提示码数组，例如 INSUFFICIENT_DOWNSIDE_OBSERVATIONS 或 ZERO_PORTFOLIO_VARIANCE |
| Data.DataQuality.Warnings[] | string | 单条警告码；部分警告会附带相关基金代码，便于程序定位但不影响其他可计算指标 |
| Data.NoDataReasons | array | 基金级或组合级不可计算原因数组；合法基金但数据不足仍返回 HTTP 200 和业务码 100 |
| Data.NoDataReasons[].FundCode | string | 原因对应的基金代码；组合级原因时为 null |
| Data.NoDataReasons[].Reason | string | 稳定原因码，包括 FUND_NOT_FOUND、EMPTY_HISTORY、INSUFFICIENT_OBSERVATIONS、INSUFFICIENT_COMMON_OBSERVATIONS、STALE_HISTORY、CONFLICTING_DUPLICATE_DATE、INVALID_RETURN、INSUFFICIENT_DOWNSIDE_OBSERVATIONS 或 ZERO_PORTFOLIO_VARIANCE |
| Data.ComplianceNotice | string | 历史风险分析免责声明；结果仅供信息参考，不构成投资建议 |
| Data.IsDemo | boolean | 是否为免鉴权演示结果。正式 POST 请求为 false，Demo 返回 true |
## 响应示例（真实数据节选）
```json
{
"DataStatus": {
"RequestParameter": "fundCount=4&Period=1Y&ConfidenceLevel=0.95",
"StatusCode": 100,
"StatusDescription": "分析成功",
"ResponseDateTime": "2026-08-31 03:38:54.257",
"DataTotalCount": 1,
"RequestId": "efed3113-98ad-4a58-ad58-d4fab4b44adf"
},
"Data": {
"AnalysisStatus": "AVAILABLE",
"ModelVersion": "gprm-1.1.0",
"Period": "1Y",
"ConfidenceLevel": 0.95,
"WeightingMethod": "CONSTANT_WEIGHT",
"DataStartDate": "20250901",
"DataEndDate": "20260828",
"SnapshotTime": "2026-08-31T11:38:54+08:00",
"ObservationCount": 241,
"CoverageRatio": 1.0,
"RequestedFundCount": 4,
"AnalyzedFundCount": 4,
"PortfolioMetrics": {
"AnnualizedReturn": 0.060532,
"AnnualizedVolatility": 0.221846,
"MaximumDrawdown": 0.1719,
"MaximumDrawdownStartDate": "20260506",
"MaximumDrawdownEndDate": "20260724",
"ValueAtRisk": 0.02324,
"ConditionalValueAtRisk": 0.029015,
"DiversificationRatio": 1.493706
},
"FundMetrics": [
{
"FundCode": "012729",
"FundName": "国泰中证动漫游戏ETF联接C",
"Weight": 0.3,
"AnalysisStatus": "AVAILABLE",
"ObservationCount": 241,
"CoverageRatio": 1.0,
"AnnualizedReturn": -0.2624,
"AnnualizedVolatility": 0.312991,
"MaximumDrawdown": 0.392717,
"RiskContribution": 0.30582
},
{
"FundCode": "290008",
"FundName": "泰信发展主题混合",
"Weight": 0.25,
"AnalysisStatus": "AVAILABLE",
"ObservationCount": 241,
"CoverageRatio": 1.0,
"AnnualizedReturn": 0.51947,
"AnnualizedVolatility": 0.463274,
"MaximumDrawdown": 0.455578,
"RiskContribution": 0.375555
},
{
"FundCode": "000001",
"FundName": "华夏成长混合",
"Weight": 0.25,
"AnalysisStatus": "AVAILABLE",
"ObservationCount": 241,
"CoverageRatio": 1.0,
"AnnualizedReturn": 0.267234,
"AnnualizedVolatility": 0.362689,
"MaximumDrawdown": 0.270036,
"RiskContribution": 0.274353
}
],
"PairwiseDependencies": [
{
"FundCodeA": "012729",
"FundCodeB": "290008",
"Correlation": 0.224457,
"DownsideCorrelation": -0.133313
},
{
"FundCodeA": "012729",
"FundCodeB": "000001",
"Correlation": 0.360282,
"DownsideCorrelation": 0.162133
},
{
"FundCodeA": "012729",
"FundCodeB": "110022",
"Correlation": 0.352017,
"DownsideCorrelation": 0.182233
}
],
"DataQuality": {
"MinimumObservationCount": 200,
"LatestDataAgeDays": 3,
"Warnings": [
]
},
"NoDataReasons": [
],
"ComplianceNotice": "本 Demo 使用固定基金组合展示历史风险指标；结果仅供信息参考，不构成投资建议。",
"IsDemo": true
}
}
```
## 接口常见 HTTP 响应状态码
> 以下为接口调用中常见的 HTTP 传输层状态码，不等同于响应体内的业务状态码；完整状态码注册表以 IANA HTTP Status Code Registry 为准。
| 状态码 | 状态码解释 | 备注 |
| --- | --- | --- |
| 200 | 请求成功 | HTTP 请求已成功处理；业务状态请结合响应体中的自定义业务码判断。 |
| 201 | 资源已创建 | 创建类接口请求成功，并已生成对应资源。 |
| 202 | 请求已接受 | 请求已被接受处理，结果可能异步完成。 |
| 204 | 无响应内容 | 请求成功但响应体为空，适用于无需返回数据的操作。 |
| 400 | 请求参数错误 | 请求参数缺失、格式错误或参数组合不合法。 |
| 401 | 认证失败 | 缺少、无效或未通过认证的访问凭证（如 AppKey）。 |
| 403 | 无权限访问 | 订单到期、权限不足或接口额度不可用。 |
| 404 | 资源不存在 | 请求路径不存在。 |
| 405 | 请求方法不允许 | 当前路径不支持该 HTTP 方法。 |
| 408 | 请求超时 | 客户端请求在服务端等待时间内未完成，可稍后重试。 |
| 409 | 请求冲突 | 请求与当前资源状态冲突，调整参数或业务状态后重试。 |
| 413 | 请求内容过大 | 上传文件或请求体超过接口限制。 |
| 414 | 请求地址过长 | 请求 URL 超过服务端可处理长度，建议减少查询参数或改用 POST。 |
| 415 | 请求内容类型不支持 | 上传或请求体的内容类型不符合接口要求。 |
| 422 | 请求语义错误 | 请求格式正确，但参数取值、语义或业务约束无法处理。 |
| 429 | 请求频率受限 | 默认按来源 IP 限速，单 IP 最多 5 QPS，可满足常规业务调用。超出限制时接口会返回 429 请求频率受限；已购买接口订单可加购 10 QPS 扩展。 |
| 431 | 请求头过大 | 请求头字段过大或过多，建议精简 Header 后重试。 |
| 500 | 服务器内部错误 | 服务端处理异常，请稍后重试。 |
| 502 | 服务暂时不可用 | 请稍后重试。 |
| 503 | 服务暂时不可用 | 请稍后重试。 |
| 504 | 请求超时 | 请稍后重试。 |
## 接口自定义业务状态码
| 业务状态码 | 业务状态码解释 | 备注 |
| --- | --- | --- |
| 100 | 正常返回 | 结合 AnalysisStatus 判断分析数据完整性 |
| 501 | 参数错误 | 请检查基金代码、持仓数量、权重、周期和置信水平 |
| 502 | 请求频率受限 | 请降低请求频率后重试 |
| 503 | 账号已过期 | 请确认订单有效期 |
| 504 | APPKEY 错误 | 请检查 APPKEY 及接口权限 |
| 505 | 调用额度不足 | 请确认接口调用额度 |
| 900 | 服务内部错误 | 请稍后重试；持续失败时可提供 RequestId 联系支持 |
| 901 | 服务暂不可用 | 历史数据服务暂不可用，请稍后重试 |
## cURL 请求示例
```bash
curl --location --request POST 'https://api.gugudata.com/ai/fund/portfolio-risk-analyses' \
--header 'Authorization: Bearer YOUR_APPKEY' \
--header 'Content-Type: application/json' \
--data '{
"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
}'
```
## 常见问题 Q&A
### Q: 如何完成第一次 API 调用？
A: 先确认当前接口的请求方法、必填参数和成功状态，再使用对应产品的 AppKey 发起请求；以实际响应中的业务状态判断结果。 [查看接入指南](https://www.gugudata.com/developers/getting-started)
### Q: 如何保证请求时 AppKey 的安全性？
A: 在开发者中心的 APP KEY 管理页面复制对应产品的 AppKey，并保存在服务端环境变量或密钥管理服务中。不要写入网页、App 客户端、公开仓库或日志。
### Q: 接口可以用于哪些开发语言？
A: Java、Python、Node.js、PHP、Go、C#、Swift、Kotlin 等支持 HTTP 请求的语言均可接入；也可以通过 OpenAPI、Postman 或 Apifox 查看和调试接口。
### Q: 请求失败或超时后可以重试吗？
A: 先区分 HTTP 状态与业务错误。参数、鉴权和权限错误应修正后再请求；超时并不表示服务端未执行，重试前需确认接口是否会重复计费或产生副作用。 [查看接入指南](https://www.gugudata.com/developers/errors-and-retries)
### Q: 接口的性能可以保证吗？
A: 实际响应时间受接口类型、参数和网络环境影响。请按当前套餐的 QPS 控制并发，生产接入前完成联调与容量评估。
## 服务协议以及服务免责声明
- [服务协议](https://www.gugudata.com/license)
- [服务免责声明](https://www.gugudata.com/disclaimer)
## 技术支持
- 技术支持邮箱: support@gugudata.com
- 微信客服: https://work.weixin.qq.com/kfid/kfcf9a60a6afe3337b7