Financial Data API — Documentation

Financial Data API dates the macro world. The economic calendar gives you scheduled and released macro events with the values consumers expect on a calendar (actual, forecast, consensus, previous, and revised). The unified events feed merges that calendar with every other official event Financial Data API tracks (central-bank actions and issuer filings) into one normalized shape with a single schema.

Economic calendar

GET /economic-calendar is the scheduled macro-release calendar: CPI prints, payrolls, central-bank meetings, each with actual, forecast, consensus, previous, and revised values.

Unified official events

GET /events is one stream across macro releases, central-bank actions, and issuer filings, with a single normalized event shape.

Use the calendar when you want classic macro-release rows with surprise inputs and release-time semantics. Use the unified events feed when you want a single stream across event classes (macro releases plus central-bank actions and issuer filings) under one schema.

What data is available

The calendar covers the same canonical macro indicators Financial Data API normalizes (CPI, core CPI, PCE, PPI, unemployment, nonfarm payrolls, jobless claims, real GDP growth, policy rates, money-market and government-bond yields, housing starts, building permits, trade balance, exports, imports, personal income, retail sales) across the covered countries, sourced from the institutions of record (FRED, BLS, ECB, OECD, BIS, Eurostat, Bank of England, Bank of Japan, and more). Read the live indicator list from GET /canonical-indicators and the country and category breadth from GET /coverage. The unified events feed spans three event families:

Macro releases

Scheduled and released macro prints, the same rows the economic calendar carries, surfaced as macro_release events.

Central-bank actions

Policy decisions and meetings from the central banks Financial Data API tracks, surfaced as central_bank events.

Issuer filings

SEC EDGAR filings from the company universe, surfaced as issuer_filing events. The structured statements behind them live in the financial statements endpoint.

Coverage grows over time. Read live breadth from GET /coverage and the live indicator slugs from GET /canonical-indicators rather than hard-coding which events exist.

Both feeds are rights-aware. Every event carries an exposure class, and only redistribution-safe events appear where the public surface applies. Licensed vendor data never appears on the public surface.

Authentication

Send your key as x-api-key (or Authorization: Bearer). Both endpoints require the data:read scope. See Authentication.

The economic calendar

GET /economic-calendar returns scheduled and released macro events. Each row carries the release time, the period it covers, and the value series: actual, forecast, consensus, previous, and (where applicable) revised.

Filters

The calendar accepts the standard list filters plus the observation filters relevant to events. Unknown query parameters are rejected with bad_request.

Example: high-importance US releases

curl "https://api.financialdatapi.com/economic-calendar?country=USA&importance=high&limit=5&order=desc" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY! });

const { data } = await client.economicCalendar({
  country: "USA",
  importance: "high",
  limit: 5,
  order: "desc",
});

for (const event of data) {
  console.log(event.releaseTime, event.eventName, event.actualValue, event.forecastValue);
}

Response

{
  "data": [
    {
      "id": "ecal_us_cpi_2026_05",
      "providerEventId": "...",
      "sourceId": "bls",
      "providerId": "bls",
      "entityId": "country_usa",
      "countryIso3": "USA",
      "indicatorId": "cpi_inflation_yoy",
      "eventName": "CPI (YoY)",
      "eventType": "economic_release",
      "importance": "high",
      "status": "released",
      "releaseTime": "2026-06-11T12:30:00Z",
      "releaseTimeZone": "America/New_York",
      "period": "2026-05",
      "periodStart": "2026-05-01",
      "periodEnd": "2026-05-31",
      "actualValue": 3.1,
      "forecastValue": 3.2,
      "consensusValue": 3.2,
      "previousValue": 3.3,
      "revisedValue": null,
      "unit": "percent",
      "currency": null,
      "sourceUrl": "https://www.bls.gov/...",
      "attribution": "U.S. Bureau of Labor Statistics",
      "observationId": "obs_...",
      "exposure": "public"
    }
  ],
  "meta": {
    "api_version": "v1",
    "pagination": { "limit": 5, "cursor": null, "next_cursor": null, "has_more": false }
  },
  "requestId": "..."
}

Example figures above are illustrative. Pull live values from the endpoint.

Calendar event fields

Get a single calendar event

GET /economic-calendar/{id} returns one calendar event by its id.

curl "https://api.financialdatapi.com/economic-calendar/ecal_us_cpi_2026_05" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

const { data: event } = await client.request(
  "/economic-calendar/ecal_us_cpi_2026_05"
);
console.log(event.eventName, event.actualValue);

First-release vs revised

Macro series are revised after their first print. Financial Data API keeps both, and the calendar exposes the distinction so you can model surprises honestly.

previousValue is first-release basis

previousValue carries the prior period value as it was known at this release, not the latest revised figure. That is what a forecast was measured against at the time, so it is the correct base for surprise and momentum calculations.

revisedValue and status: revised

When an event reports a revision, revisedValue is populated and status is revised. The original actualValue is preserved. Revisions are retained, never overwritten in place.

Reconstructing what was known at a point in time

To see the value set as known on a given date, use the knowledge-time filters (start_date and end_date) and as_of on the observations API. Honest caveat: as_of currently approximates the ingestion timestamp, not full provider-vintage reconstruction. Full vintage reconstruction is future work.

Unified official events

GET /events merges the economic calendar with every other official event into one normalized response shape. It covers macro releases, central-bank actions, and issuer filings (for example SEC filings) under one schema. Use it when you want a single stream and one set of fields across event classes.

Filters

Example: released US macro events

curl "https://api.financialdatapi.com/events?event_class=macro_release&country=USA&status=released&limit=5" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY! });

const { data } = await client.officialEvents({
  event_class: "macro_release",
  country: "USA",
  status: "released",
  limit: 5,
});

for (const event of data) {
  console.log(event.eventClass, event.eventType, event.title, event.observedAt);
}

Response

{
  "data": [
    {
      "id": "obs_or_ecal_id",
      "canonicalEventId": "...",
      "eventClass": "macro_release",
      "eventType": "economic_release",
      "eventLabel": "CPI (YoY)",
      "eventStatus": "released",
      "entityId": "country_usa",
      "countryIso3": "USA",
      "indicatorId": "cpi_inflation_yoy",
      "observedAt": "2026-06-11T12:30:00Z",
      "releasedAt": "2026-06-11T12:30:00Z",
      "effectiveAt": null,
      "periodStart": "2026-05-01",
      "periodEnd": "2026-05-31",
      "title": "CPI (YoY)",
      "summary": null,
      "tags": ["economic_release", "USA", "cpi_inflation_yoy"],
      "sourceId": "bls",
      "providerId": "bls",
      "sourceUrl": "https://www.bls.gov/...",
      "attribution": "U.S. Bureau of Labor Statistics",
      "exposure": "public",
      "linkedObservationId": "obs_...",
      "metadata": {
        "importance": "high",
        "actualValue": 3.1,
        "forecastValue": 3.2,
        "consensusValue": 3.2,
        "previousValue": 3.3,
        "revisedValue": null,
        "unit": "percent",
        "currency": null
      }
    }
  ],
  "meta": {
    "api_version": "v1",
    "pagination": { "limit": 5, "cursor": null, "next_cursor": null, "has_more": false }
  },
  "requestId": "..."
}

Unified event fields

Get a single event

GET /events/{id} returns one unified event by its id.

curl "https://api.financialdatapi.com/events/obs_or_ecal_id" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

const { data: event } = await client.request("/events/obs_or_ecal_id");
console.log(event.title, event.eventStatus);

Calendar vs unified events: which to use

Use the economic calendar

You want macro-release rows with surprise inputs (actual, forecast, consensus, previous, revised) and release-time semantics. Filter by country, indicator, importance, status, event_type, and period.

Use unified events

You want one stream across event classes (macro releases plus central-bank actions and issuer filings) under a single schema. Filter by event_class, event_type, status, exposure, and time.

Macro observations

Follow observationId (or linkedObservationId) to the point-in-time value the event released, with full filters and provenance.

Financial statements

Issuer filings surface as issuer_filing events here; the structured statements behind them live in the financials endpoint.

Derived analytics

Surprise indices and other analytics are computed from calendar inputs and stored as derived observations.

Get started

Data products

Data infrastructure

Agent access

Resources

Legal

Economic calendar & official events

Economic calendar

Unified official events

What data is available

Macro releases

Central-bank actions

Issuer filings

Authentication

The economic calendar

Filters

Example: high-importance US releases

Calendar event fields

Get a single calendar event

First-release vs revised

Unified official events

Filters

Example: released US macro events

Unified event fields

Get a single event

Calendar vs unified events: which to use

Use the economic calendar

Use unified events

Macro observations

Financial statements

Derived analytics

Economic calendar

Unified official events

​What data is available

Macro releases

Central-bank actions

Issuer filings

​Authentication

​The economic calendar

​Filters

​Example: high-importance US releases

​Calendar event fields

​Get a single calendar event

​First-release vs revised

​Unified official events

​Filters

​Example: released US macro events

​Unified event fields

​Get a single event

​Calendar vs unified events: which to use

Use the economic calendar

Use unified events

​Related

Macro observations

Financial statements

Derived analytics

What data is available

Authentication

The economic calendar

Filters

Example: high-importance US releases

Calendar event fields

Get a single calendar event

First-release vs revised

Unified official events

Filters

Example: released US macro events

Unified event fields

Get a single event

Calendar vs unified events: which to use

Related