经济日历数据获取器

概述

从 Financial Modeling Prep (FMP) 经济日历 API 检索即将发生的经济事件和数据发布。此技能获取预定的经济指标，包括中央银行货币政策决定、就业报告、通胀数据（CPI/PPI）、GDP 发布、零售销售、制造业数据以及其他影响金融市场的市场动向事件。

该技能使用 Python 脚本查询 FMP API，并按时间顺序生成包含每个预定事件影响评估的 Markdown 报告。

核心功能：

• 获取指定日期范围（最长 90 天）内的经济事件
• 支持灵活的 API 密钥提供方式（环境变量或用户输入）
• 按影响级别、国家或事件类型进行筛选
• 生成包含影响分析的结构化 Markdown 报告
• 默认为未来 7 天，便于快速了解市场前景

数据来源：

• FMP 经济日历 API：https://financialmodelingprep.com/api/v3/economic_calendar
• 覆盖主要经济体：美国、欧盟、英国、日本、中国、加拿大、澳大利亚
• 事件类型：央行决议、就业数据、通胀数据、GDP数据、贸易数据、房地产数据、调查数据

何时使用此功能

当用户请求以下内容时使用此功能：

1. 经济日历查询：

   • "本周有哪些即将到来的经济事件？"
   • "显示未来两周的经济日历"
   • "下一次联邦公开市场委员会会议是什么时候？"
   • "下个月将发布哪些主要经济数据？"

2. 市场事件规划：

   • "本周我应该关注市场的哪些方面？"
   • "是否有任何高影响力的经济数据即将发布？"
   • "下一次就业报告/消费者价格指数发布/国内生产总值报告是什么时候？"

3. 特定日期范围请求：

   • "获取1月1日至1月31日的经济事件"
   • "2025年第一季度的经济日历上有什么？"

4. 国家特定查询：

   • "显示下周美国经济数据发布情况"
   • "有哪些欧洲央行事件已安排？"
   • "日本何时发布其通胀数据？"

请勿将此技能用于：

• 过往经济事件（使用市场新闻分析师进行历史分析）
• 公司财报日历（此技能不包含财报）
• 实时市场数据或实时报价
• 技术分析或图表解读

工作流程

按照以下步骤获取并分析经济日历：

步骤1：获取FMP API密钥

检查API密钥的可用性：

1. 首先检查是否设置了FMP_API_KEY环境变量
2. 如果不可用，请通过聊天请求用户提供API密钥
3. 如果用户没有API密钥，请提供以下说明：
   • 访问https://financialmodelingprep.com
   • 注册免费账户（每日250次请求限制）
   • 导航至API仪表板以获取密钥

用户交互示例：

User: "Show me economic events for next week"
Assistant: "I'll fetch the economic calendar. Do you have an FMP API key? I can use the FMP_API_KEY environment variable, or you can provide your API key now."

步骤2：确定日期范围

根据用户请求设置合适的日期范围：

默认情况（未指定具体日期）：今天至7天后用户指定时间段：使用确切日期（验证格式：YYYY-MM-DD）最大范围：90天（FMP API限制）

示例：

• "下周" → 今天至7天后
• "未来两周" → 今天至14天后
• "2025年1月" → 2025-01-01 至 2025-01-31
• "2025年第一季度" → 2025-01-01 至 2025-03-31

验证日期范围：

• 确保开始日期 ≤ 结束日期
• 确保范围 ≤ 90天
• 查询过去日期时发出警告

步骤三：执行API获取脚本

使用适当参数运行 get_economic_calendar.py 脚本：

基本用法（默认7天）：

python3 /path/to/economic-calendar-fetcher/scripts/get_economic_calendar.py --api-key YOUR_KEY

指定日期范围：

python3 /path/to/economic-calendar-fetcher/scripts/get_economic_calendar.py \
  --from 2025-01-01 \
  --to 2025-01-31 \
  --api-key YOUR_KEY \
  --format json

使用环境变量（无需 --api-key 参数）：

export FMP_API_KEY=your_key_here
python3 /path/to/economic-calendar-fetcher/scripts/get_economic_calendar.py \
  --from 2025-01-01 \
  --to 2025-01-07

脚本参数：

• --from：开始日期（YYYY-MM-DD）- 默认值：今天
• --to：结束日期（YYYY-MM-DD）- 默认值：今天 + 7天
• --api-key：FMP API密钥（若已设置FMP_API_KEY环境变量则为可选）
• --format：输出格式（json或text）- 默认值：json
• --output：输出文件路径（可选，默认输出至stdout）

错误处理：

• 无效API密钥 → 提示用户验证密钥
• 超出速率限制（429） → 建议等待或升级FMP服务套餐
• 网络错误 → 采用指数退避策略重试
• 无效日期格式 → 提供正确格式示例

步骤4：解析与筛选事件

处理脚本返回的JSON响应：

1. 解析事件数据：从API响应中提取所有事件
2. 若指定筛选条件则应用用户筛选器
   • 影响级别："高"、"中"、"低"
   • 国家/地区："美国"、"欧盟"、"日本"、"中国"等
   • 事件类型：美联储利率决议、消费者价格指数、就业数据、国内生产总值等
   • 货币：美元、欧元、日元等

筛选示例：

• "仅显示高影响事件" → 筛选条件：影响级别 == "高"
• "仅限美国事件" → 筛选条件：国家/地区 == "美国"
• "央行决策" → 在事件名称中搜索："利率"、"政策"、"美联储"、"欧洲央行"、"日本央行"

事件数据结构：

{
  "date": "2025-01-15 14:30:00",
  "country": "US",
  "event": "Consumer Price Index (CPI) YoY",
  "currency": "USD",
  "previous": 2.6,
  "estimate": 2.7,
  "actual": null,
  "change": null,
  "impact": "High",
  "changePercentage": null
}

步骤5：评估市场影响

评估每个事件的市场重要性：

影响级别分类（来自FMP）：

• 高影响：主要市场驱动事件

  • 美联储利率决议、欧洲央行/日本央行政策会议
  • 非农就业数据、消费者价格指数、国内生产总值
  • 市场通常表现出0.5-2%以上的日内波动

• 中影响：重要但波动性较小

  • 零售销售、工业生产
  • 采购经理人指数调查，消费者信心指数
  • 住房数据，耐用品订单

• 低影响度：次要指标

  • 每周初请失业金人数（除非数据极端）
  • 地区制造业调查
  • 次要拍卖结果

额外情境因素：

1. 当前市场敏感度：

   • 高通胀环境 → 消费者物价指数/生产者物价指数重要性提升
   • 衰退担忧 → 就业数据更为关键
   • 降息预期 → 央行会议至关重要

2. 意外可能性：

   • 对比预期值与前期读数
   • 预期变动幅度大 = 关注度更高
   • 共识不确定性高 = 潜在影响更大

3. 事件集群效应：

   • 同日多项相关事件 = 影响叠加放大
   • 示例：消费者物价指数 + 零售销售数据 + 美联储讲话 = 极高影响日

4. 前瞻性意义：

   • 这一事件会影响即将到来的央行决策吗？
   • 这是初值还是终值？
   • 这些数据后续会修订吗？

步骤六：生成输出报告

创建结构化的Markdown报告，包含以下部分：

报告标题：

# Economic Calendar
**Period:** [Start Date] to [End Date]
**Report Generated:** [Timestamp]
**Total Events:** [Count]
**High Impact Events:** [Count]

事件列表（按时间顺序）：

对于每个事件，提供：

## [Date] - [Day of Week]

### [Event Name] ([Impact Level])
- **Country:** [Country Code] ([Currency])
- **Time:** [HH:MM UTC]
- **Previous:** [Value]
- **Estimate:** [Consensus Forecast]
- **Impact Assessment:** [Your analysis]

**Market Implications:**
[2-3 sentences on why this matters, what markets watch for, typical reaction patterns]

---

示例事件条目：

## 2025-01-15 - Wednesday

### Consumer Price Index (CPI) YoY (High Impact)
- **Country:** US (USD)
- **Time:** 14:30 UTC (8:30 AM ET)
- **Previous:** 2.6%
- **Estimate:** 2.7%
- **Impact Assessment:** Very High - Core inflation metric for Fed policy decisions

**Market Implications:**
CPI reading above estimate (>2.7%) likely strengthens hawkish Fed expectations, potentially pressuring equities and supporting USD. Reading at or below 2.7% could reinforce disinflation narrative and support risk assets. Options market pricing 1.2% S&P 500 move on release day.

---

总结部分：

在报告末尾添加分析性总结：

## Key Takeaways

**Highest Impact Days:**
- [Date]: [Events] - [Combined impact rationale]
- [Date]: [Events] - [Combined impact rationale]

**Central Bank Activity:**
- [Summary of any scheduled Fed/ECB/BOJ meetings or speeches]

**Major Data Releases:**
- Employment: [NFP, Unemployment Rate dates]
- Inflation: [CPI, PPI dates]
- Growth: [GDP, Retail Sales dates]

**Market Positioning Considerations:**
[2-3 bullets on how traders might position around these events]

**Risk Events:**
[Highlight any particularly high-uncertainty or surprise-potential events]

筛选说明：

如果用户要求了特定筛选条件，请在顶部注明：

**Filters Applied:**
- Impact Level: High only
- Country: US
- Events shown: [X] of [Y] total events in date range

输出格式：

• 主要输出：保存至磁盘的Markdown文件
• 文件命名格式：economic_calendar_[起始日期]_至_[结束日期].md
• 同时在聊天界面向用户显示总结

输出格式规范

文件命名约定：

economic_calendar_2025-01-01_to_2025-01-31.md
economic_calendar_2025-01-15_to_2025-01-21.md  (weekly)
economic_calendar_high_impact_2025-01.md  (with filters)

Markdown结构要求：

1. 时间顺序排列：事件按日期和时间排序（最早优先）
2. 影响级别指标：使用（高影响）、（中影响）、（低影响）标签
3. 时区清晰度：始终指定UTC时间，并为美国事件提供ET/PT时区转换
4. 数据完整性：包含所有可用字段（如果事件已发生，则包含先前值、预测值和实际值）
5. 空值处理：对空值显示"N/A"或"无预测"
6. 影响评估：每个高/中影响事件必须包含市场影响分析

表格格式选项（适用于密集列表）：

| Date/Time (UTC) | Event | Country | Impact | Previous | Estimate | Assessment |
|-----------------|-------|---------|--------|----------|----------|------------|
| 01-15 14:30 | CPI YoY | US | High | 2.6% | 2.7% | Core inflation metric |

语言：所有报告均使用英语

资源

Python脚本：

• scripts/get_economic_calendar.py：主API抓取脚本，带CLI接口

参考文档：

• references/fmp_api_documentation.md完整的FMP经济日历API参考文档
  • 认证与API密钥管理
  • 请求参数与日期格式
  • 响应字段定义
  • 速率限制与错误处理
  • 缓存与效率的最佳实践

API详情：

• 端点：https://financialmodelingprep.com/api/v3/economic_calendar
• 认证：需要API密钥（免费层级：250次请求/天）
• 最大日期范围：每次请求90天
• 响应格式：事件对象的JSON数组
• 速率限制：5次请求/秒（免费层级）

事件覆盖范围：

• 主要经济体：美国、欧盟、英国、日本、中国、加拿大、澳大利亚、瑞士
• 事件类别：货币政策、就业、通胀、GDP、贸易、房地产、调查
• 更新频率：实时（事件按计划添加/更新）
• 历史数据：可获取过往事件的实际值

使用提示：

1. 缓存结果以减少API调用次数（活动一旦排期就很少更改）
2. 查询7-30天范围以获得最佳请求效率
3. 不要查询超过6个月后的日期（数据稀疏，多为推测性日期）
4. 每日刷新接下来一周的缓存以捕捉时间变更
5. 实时活动监控使用较短范围（1-7天）

错误处理：

• API密钥错误：提供清晰的免费密钥获取指引
• 频率限制：采用指数退避重试机制
• 网络故障：优雅降级处理（优先使用可用缓存数据）
• 无效日期：进行验证并返回有帮助的错误信息