Economic Calendar Fetcher

# FMP Economic Calendar API Documentation

## Overview

The Financial Modeling Prep (FMP) Economic Calendar API provides access to upcoming and historical economic data releases, central bank decisions, and other market-moving events. This API enables traders and investors to stay informed about scheduled economic events that may impact financial markets.

## API Endpoint

```
https://financialmodelingprep.com/api/v3/economic_calendar
```

## Authentication

API access requires a valid FMP API key, which must be included as a query parameter in all requests.

**Parameter:** `apikey`
**Format:** String
**Required:** Yes

### Obtaining an API Key

1. Visit https://financialmodelingprep.com
2. Sign up for an account (free and paid tiers available)
3. Navigate to the API dashboard to view your API key
4. Free tier allows limited requests per day (~250-300 requests)
5. Paid tiers offer higher rate limits and additional features

## Request Parameters

### Required Parameters

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `from` | date | Start date for calendar period | `2025-01-01` |
| `to` | date | End date for calendar period | `2025-01-31` |
| `apikey` | string | Your FMP API key | `YOUR_API_KEY` |

### Date Format

- **Format:** `YYYY-MM-DD` (ISO 8601 date format)
- **Example:** `2025-07-20`
- **Maximum Range:** 90 days between `from` and `to` dates
- **Timezone:** All dates are in UTC

### Date Range Limitations

- Minimum range: 1 day
- Maximum range: 90 days
- Past dates: API returns historical events with actual values
- Future dates: API returns scheduled events with estimates (actual values will be null)

## Response Format

The API returns a JSON array of economic event objects.

### Response Structure

```json
[
    {
        "date": "2024-03-01 03:35:00",
        "country": "JP",
        "event": "3-Month Bill Auction",
        "currency": "JPY",
        "previous": -0.112,
        "estimate": null,
        "actual": -0.096,
        "change": 0.016,
        "impact": "Low",
        "changePercentage": 14.286
    }
]
```

### Response Fields

| Field | Type | Description | Nullable |
|-------|------|-------------|----------|
| `date` | string | Event date and time in UTC (format: `YYYY-MM-DD HH:MM:SS`) | No |
| `country` | string | ISO 2-letter country code (e.g., `US`, `JP`, `GB`, `EU`) | No |
| `event` | string | Name/description of the economic event | No |
| `currency` | string | ISO 3-letter currency code (e.g., `USD`, `EUR`, `JPY`) | No |
| `previous` | number | Previous reading/value for this indicator | Yes |
| `estimate` | number | Market consensus estimate/forecast | Yes |
| `actual` | number | Actual released value (null for future events) | Yes |
| `change` | number | Absolute change from previous reading | Yes |
| `impact` | string | Market impact level: `"High"`, `"Medium"`, `"Low"` | No |
| `changePercentage` | number | Percentage change from previous reading | Yes |

### Field Details

**`date`:**
- Format: `YYYY-MM-DD HH:MM:SS` in UTC timezone
- Represents the scheduled release time for the economic data
- For future events, this is the expected release time
- Times may be adjusted if releases are delayed

**`country`:**
- ISO 3166-1 alpha-2 country codes
- Special codes:
  - `EU`: European Union (ECB-related events)
  - `G7`: G7 summit/collaborative events
  - International organizations may use special codes

**`event`:**
- Descriptive name of the economic indicator or event
- Examples:
  - `"Non-Farm Payrolls"`
  - `"Consumer Price Index (CPI)"`
  - `"Federal Funds Rate Decision"`
  - `"GDP Growth Rate QoQ"`
  - `"Unemployment Rate"`

**`currency`:**
- ISO 4217 currency codes
- Indicates which currency's economy the event affects
- May differ from country (e.g., EU events affect EUR across multiple countries)

**`previous`:**
- The last reported value for this indicator
- Used as baseline for comparing current release
- May be revised from originally repo