Economic Calendar Fetcher

When to Use This Skill

Use this skill when the user requests:

1. Economic Calendar Queries:

   • "What economic events are coming up this week?"
   • "Show me the economic calendar for the next two weeks"
   • "When is the next FOMC meeting?"
   • "What major economic data is being released next month?"

2. Market Event Planning:

   • "What should I watch for in the markets this week?"
   • "Are there any high-impact economic releases coming?"
   • "When is the next jobs report / CPI release / GDP report?"

3. Specific Date Range Requests:

   • "Get economic events from January 1 to January 31"
   • "What's on the economic calendar for Q1 2025?"

4. Country-Specific Queries:

   • "Show me US economic data releases next week"
   • "What ECB events are scheduled?"
   • "When is Japan releasing their inflation data?"

DO NOT use this skill for:

• Past economic events (use market-news-analyst for historical analysis)
• Corporate earnings calendars (this skill excludes earnings)
• Real-time market data or live quotes
• Technical analysis or chart interpretation

Workflow

Follow these steps to fetch and analyze the economic calendar:

Step 1: Obtain FMP API Key

Check for API key availability:

1. First check if FMP_API_KEY environment variable is set
2. If not available, ask user to provide API key via chat
3. If user doesn't have API key, provide instructions:
   • Visit https://financialmodelingprep.com
   • Sign up for free account (250 requests/day limit)
   • Navigate to API dashboard to obtain key

Example user interaction:

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

Step 2: Determine Date Range

Set appropriate date range based on user request:

Default (no specific dates): Today + 7 days User specifies period: Use exact dates (validate format: YYYY-MM-DD) Maximum range: 90 days (FMP API limitation)

Examples:

• "Next week" → Today to +7 days
• "Next two weeks" → Today to +14 days
• "January 2025" → 2025-01-01 to 2025-01-31
• "Q1 2025" → 2025-01-01 to 2025-03-31

Validate date range:

• Ensure start date ≤ end date
• Ensure range ≤ 90 days
• Warn if querying past dates

Step 3: Execute API Fetch Script

Run the get_economic_calendar.py script with appropriate parameters:

Basic usage (default 7 days):

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

With specific date range:

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

Using environment variable (no --api-key needed):

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

Script parameters:

• --from: Start date (YYYY-MM-DD) - default: today
• --to: End date (YYYY-MM-DD) - default: today + 7 days
• --api-key: FMP API key (optional if FMP_API_KEY env var set)
• --format: Output format (json or text) - default: json
• --output: Output file path (optional, default: stdout)

Handle errors:

• Invalid API key → Ask user to verify key
• Rate limit exceeded (429) → Suggest waiting or upgrading FMP tier
• Network errors → Retry with exponential backoff
• Invalid date format → Provide correct format example

Step 4: Parse and Filter Events

Process the JSON response from the script:

1. Parse event data: Extract all events from API response
2. Apply user filters if specified:
   • Impact level: "High", "Medium", "Low"
   • Country: "US", "EU", "JP", "CN", etc.
   • Event type: FOMC, CPI, Employment, GDP, etc.
   • Currency: USD, EUR, JPY, etc.

Filter examples:

• "Show only high-impact events" → Filter impact == "High"
• "US events only" → Filter country == "US"
• "Central bank decisions" → Search event name for "Rate", "Policy", "FOMC", "ECB", "BOJ"

Event data structure:

{
  "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
}

Step 5: Assess Market Impact

Evaluate the market significance of each event:

Impact Level Classification (from FMP):

• High Impact: Major market-moving events

  • FOMC rate decisions, ECB/BOJ policy meetings
  • Non-Farm Payrolls (NFP), CPI, GDP
  • Market typically shows 0.5-2%+ intraday volatility

• Medium Impact: Significant but less volatile

  • Retail Sales, Industrial Production
  • PMI surveys, Consumer Confidence
  • Housing data, Durable Goods Orders

• Low Impact: Minor indicators

  • Weekly jobless claims (unless extreme)
  • Regional manufacturing surveys
  • Minor auction results

Additional Context Factors:

1. Current Market Sensitivity:

   • High inflation environment → CPI/PPI elevated importance
   • Recession fears → Employment data more critical
   • Rate cut speculation → Central bank meetings crucial

2. Surprise Potential:

   • Compare estimate vs. previous reading
   • Large expected changes = higher attention
   • Consensus uncertainty = higher impact potential

3. Event Clustering:

   • Multiple related events same day = amplified impact
   • Example: CPI + Retail Sales + Fed speech = Very High impact day

4. Forward Significance:

   • Does this event influence upcoming central bank decisions?
   • Is this a preliminary or final reading?
   • Will this data be revised?

Step 6: Generate Output Report

Create structured markdown report with the following sections:

Report Header:

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

Event Listing (Chronological):

For each event, provide:

## [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]

---

Example Event Entry:

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

---

Summary Section:

Add analytical summary at the end:

## 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]

Filtering Notes:

If user requested specific filters, note at top:

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

Output Format:

• Primary: Markdown file saved to disk
• Filename format: economic_calendar_[START]_to_[END].md
• Also display summary to user in chat

Output Format Specifications

File naming convention:

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 structure requirements:

1. Chronological ordering: Events sorted by date and time (earliest first)
2. Impact level indicators: Use (High Impact), (Medium Impact), (Low Impact) labels
3. Time zone clarity: Always specify UTC and provide ET/PT conversions for US events
4. Data completeness: Include all available fields (previous, estimate, actual if past)
5. Null handling: Display "N/A" or "No estimate" for null values
6. Impact assessment: Every high/medium impact event must have market implications analysis

Table format option (for dense listings):

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

Language: All reports in English

Resources

Python Script:

• scripts/get_economic_calendar.py: Main API fetch script with CLI interface

Reference Documentation:

• references/fmp_api_documentation.md: Complete FMP Economic Calendar API reference
  • Authentication and API key management
  • Request parameters and date formats
  • Response field definitions
  • Rate limits and error handling
  • Best practices for caching and efficiency

API Details:

• Endpoint: https://financialmodelingprep.com/api/v3/economic_calendar
• Authentication: API key required (free tier: 250 requests/day)
• Max date range: 90 days per request
• Response format: JSON array of event objects
• Rate limits: 5 requests/second (free tier)

Event Coverage:

• Major economies: US, EU, UK, Japan, China, Canada, Australia, Switzerland
• Event categories: Monetary policy, Employment, Inflation, GDP, Trade, Housing, Surveys
• Update frequency: Real-time (events added/updated as scheduled)
• Historical data: Available for past events with actual values

Usage Tips:

1. Cache results to minimize API calls (events rarely change once scheduled)
2. Query 7-30 day ranges for optimal request efficiency
3. Don't query >6 months in future (sparse data, speculative dates)
4. Refresh cache daily for upcoming week to catch time changes
5. Use smaller ranges (1-7 days) for real-time event monitoring

Error Handling:

• API key errors: Clear user guidance for obtaining free key
• Rate limits: Exponential backoff retry logic
• Network failures: Graceful degradation with cached data if available
• Invalid dates: Validation with helpful error messages