> ## Documentation Index
> Fetch the complete documentation index at: https://scalarfield.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Economic Event Releases

> Global economic event calendar with full revision history. Tracks scheduled release times, forecast consensus, and actual values with point-in-time snapshots showing how data evolves across scrapes.

<Info>**Python function:** `getEconomicReleases()`</Info>

| Specification      | Value                                                                   |
| ------------------ | ----------------------------------------------------------------------- |
| Delivery Frequency | continuous                                                              |
| Data Frequency     | event-driven                                                            |
| Reporting Lag      | Event discovery every \~6 hours; actual values captured at release time |
| Coverage           | Global economic events (US, EU, UK, China, Japan, and more)             |
| Availability       | Free                                                                    |

# Product Overview

## Overview

Economic Event Releases provides structured data on scheduled macroeconomic events — GDP prints, employment reports, CPI releases, central bank decisions, and more. Each row represents a single event occurrence at a specific scheduled time.

The key differentiator of this dataset is the **snapshot revision history**. Rather than a single actual/forecast pair, each event carries a `snapshots` dictionary that records how the actual and forecast values evolved over time — from initial forecast publication through post-release revisions. This makes the dataset suitable for point-in-time backtesting where you need to know what was known when.

## Data Pipeline

A continuous service tracks economic event schedules from direct website sources. New events are discovered every \~6 hours. At release time, actual and forecast values are captured and stored as timestamped snapshots. Subsequent revisions to the same event (e.g. revised GDP figures) are captured as additional snapshots, preserving the full revision history.

## Snapshot Model

The `snapshots` column is a dictionary keyed by `ts_recv` (New York time string), where each entry contains:

* `actual` — the released value (None before release)
* `forecast` — the consensus forecast at that point in time
* `unit` — the unit of measurement (e.g. `"%"`, `"K"`)

**Pre-release snapshots** (ts\_recv before scheduled\_time): `actual` is typically null; `forecast` may revise across snapshots as consensus changes.

**Post-release snapshots** (ts\_recv at or after scheduled\_time): `actual` appears after the first release and may revise in subsequent snapshots; `forecast` usually stays fixed.

```python theme={null}
# Example snapshots dict for a single event:
{
    "2026-02-27 15:01:00": {"actual": 0.3, "forecast": 0.2, "unit": "%"},
    "2026-03-28 04:53:13": {"actual": 0.8, "forecast": None, "unit": "%"}
}
```

# Querying the Data

## Basic Usage

```python theme={null}
from scalarlib import getEconomicReleases

# All economic events in a date range
df = getEconomicReleases(None, '2025-01-01', '2026-03-28')

# Specific event by series ID (e.g. '45' for US Construction Spending)
df = getEconomicReleases('45', '2025-01-01', '2026-03-28')

# Extract the latest actual value from snapshots
df['latest_actual'] = df['snapshots'].apply(
    lambda s: list(s.values())[-1]['actual'] if s else None
)
```

<Info>To find the `series_id` for an event, ask Scalar Field in chat — for example, "What is the series ID for US Construction Spending?" The platform will look it up for you.</Info>

## Parameters

| Parameter   | Type        | Required | Description                                                                                                          |
| ----------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `series_id` | str or None | No       | Event attribute ID. Ask in chat to look up the ID for a specific event. `None` returns all events in the date range. |
| `start`     | str         | Yes      | Start date (`YYYY-MM-DD`). Filters on `scheduled_time` (New York date).                                              |
| `end`       | str         | Yes      | End date (`YYYY-MM-DD`). Filters on `scheduled_time` (New York date).                                                |

<Info>Date filtering applies to `scheduled_time` only. All snapshots for matching events are returned regardless of their `ts_recv` timestamps.</Info>

## Return Schema

| Column           | Type            | Description                                                                                                                 |
| ---------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `attr_id`        | int             | Event attribute identifier                                                                                                  |
| `title`          | string          | Event name (e.g. "Nonfarm Payrolls", "CPI m/m")                                                                             |
| `scheduled_time` | datetime64\[ns] | Scheduled release time (New York time, tz-naive)                                                                            |
| `snapshots`      | dict            | Revision history keyed by `ts_recv` string. Each value: `{"actual": float or None, "forecast": float or None, "unit": str}` |
| `country`        | string          | Country name (e.g. "United States", "United Kingdom")                                                                       |
| `currency`       | string          | ISO 4217 currency code (e.g. "USD", "EUR")                                                                                  |