Skip to main content

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.

Python function: getEconomicReleases()
SpecificationValue
Delivery Frequencycontinuous
Data Frequencyevent-driven
Reporting LagEvent discovery every ~6 hours; actual values captured at release time
CoverageGlobal economic events (US, EU, UK, China, Japan, and more)
AvailabilityFree

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

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

​
Parameters

ParameterTypeRequiredDescription
series_idstr or NoneNoEvent attribute ID. Ask in chat to look up the ID for a specific event. None returns all events in the date range.
startstrYesStart date (YYYY-MM-DD). Filters on scheduled_time (New York date).
endstrYesEnd date (YYYY-MM-DD). Filters on scheduled_time (New York date).
Date filtering applies to scheduled_time only. All snapshots for matching events are returned regardless of their ts_recv timestamps.

​
Return Schema

ColumnTypeDescription
attr_idintEvent attribute identifier
titlestringEvent name (e.g. “Nonfarm Payrolls”, “CPI m/m”)
scheduled_timedatetime64[ns]Scheduled release time (New York time, tz-naive)
snapshotsdictRevision history keyed by ts_recv string. Each value: {"actual": float or None, "forecast": float or None, "unit": str}
countrystringCountry name (e.g. “United States”, “United Kingdom”)
currencystringISO 4217 currency code (e.g. “USD”, “EUR”)