Economic Calendar API

← All financial data endpoints

Why Use FinanceFlowAPI’s Economic Calendar API?

Tracking market-moving macroeconomic releases usually means watching a different national statistics agency or central bank calendar for every country you cover, each with its own format and update schedule. The Economic Calendar API normalizes scheduled and released events for 83 countries into one schema and one authentication method, so you can add a new country to your product without a new integration.

• One JSON schema for every country and event type, so there is no per-source parsing to write.
• 83 countries verified live against production, from the U.S. and the Euro Area to emerging markets.
• A dedicated catalog endpoint to discover exactly which countries are covered, instead of guessing.
• Same account, API key and billing as the rest of FinanceFlowAPI: Bonds, Commodities, Currency and Economic Indicators data.

Key Capabilities

• Actual, previous & consensus per event: see the reported value against the prior reading and market expectations in one call, without a second lookup.
• Query by country, with an optional date range: omit the dates for the default upcoming window, or set date_from/date_to together to look forward or back up to 60 days.
• Impact classification: every event ships with an economicImpact level (Major, Moderate or Standard) so you can filter noise from market-moving releases.
• Built-in discovery: calendar-catalog lists every country available in the calendar.

Data Coverage & Trust

Data Methodology

Economic Calendar API data is aggregated from public economic data sources and normalized into one consistent schema (report_name, actual, previous, consensus, unit, economicImpact) for every supported country, so your integration doesn’t need a different parser per source. Release timing is set by each country’s statistics agency or central bank, not by FinanceFlowAPI. Information not provided: exact upstream data vendor and full per-country methodology.

Live API Playground Coming Soon

An interactive API Playground for this endpoint is planned. Until it ships, use the request and response examples below, or your own HTTP client, to try the API live with your key.

Request Example

GET https://financeflowapi.com/api/v1/financial-calendar?api_key=YOUR_API_KEY&country=United%20States&date_from=2026-08-20&date_to=2026-08-23

Response Example

{
  "success": true,
  "code": 200,
  "message": "OK",
  "meta": {
    "timestamp": 1787479239,
    "request_id": "6a8ac4c7d9f90"
  },
  "data": [
    {
      "country": "United States",
      "report_name": "Weekly Jobless Claims",
      "actual": "206000",
      "previous": "212000",
      "consensus": "210000",
      "unit": "",
      "economicImpact": "Moderate",
      "report_date": "08-15",
      "datetime": "2026-08-20 12:30:00"
    }
  ]
}

API Parameters

The financial-calendar endpoint returns economic events for a country:

The calendar-catalog endpoint discovers available countries:

Response Schema

Each item in data for financial-calendar:

Each item in data for calendar-catalog:

HTTP Status & Errors

Code Examples

curl "https://financeflowapi.com/api/v1/financial-calendar?api_key=YOUR_API_KEY&country=United%20States&date_from=2026-08-20&date_to=2026-08-23"

import requests
from datetime import datetime, timedelta

url = "https://financeflowapi.com/api/v1/financial-calendar"
today = datetime.now().strftime("%Y-%m-%d")
week_ahead = (datetime.now() + timedelta(days=7)).strftime("%Y-%m-%d")

params = {
    "api_key": "YOUR_API_KEY",
    "country": "United States",
    "date_from": today,
    "date_to": week_ahead
}

response = requests.get(url, params=params)
data = response.json()

high_impact = [e for e in data["data"] if e["economicImpact"] == "Major"]
print(f"{len(high_impact)} high-impact events this week")

const params = new URLSearchParams({
  api_key: "YOUR_API_KEY",
  country: "United States",
  date_from: "2026-08-20",
  date_to: "2026-08-23"
});

fetch(`https://financeflowapi.com/api/v1/financial-calendar?${params}`)
  .then(res => res.json())
  .then(data => console.log(data));

<?php
$params = http_build_query([
    'api_key'   => 'YOUR_API_KEY',
    'country'   => 'United States',
    'date_from' => '2026-08-20',
    'date_to'   => '2026-08-23',
]);

$response = file_get_contents("https://financeflowapi.com/api/v1/financial-calendar?{$params}");
$data = json_decode($response, true);

print_r($data);

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
)

func main() {
    params := url.Values{}
    params.Add("api_key", "YOUR_API_KEY")
    params.Add("country", "United States")
    params.Add("date_from", "2026-08-20")
    params.Add("date_to", "2026-08-23")

    resp, err := http.Get("https://financeflowapi.com/api/v1/financial-calendar?" + params.Encode())
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    var data map[string]interface{}
    json.Unmarshal(body, &data)

    fmt.Println(data)
}

Use Cases

• Trading bots. Avoid high-volatility windows or place event-driven orders around Major-impact releases.
• Investor dashboards. Show upcoming economic events with impact badges and consensus-vs-actual comparisons.
• Research & analytics. Compare actual vs. consensus across countries to study surprise patterns.
• Correlate events with markets. Combine calendar data with Bonds API and Economic Indicators API data to study how yields and indicator levels react around scheduled releases.

How FinanceFlowAPI Compares

Based on a live review of each provider’s public page (2026-08-23). Not every provider publishes every figure. Gaps are marked Not published rather than guessed.

Who Is This API For?

• Algorithmic and discretionary traders who need to know what’s scheduled before it moves the market
• Fintech apps and dashboards that need country-level event context alongside market data
• Publishers and content platforms that need sourced economic event data
• Researchers studying how actual releases compare to consensus expectations

Limitations

• Per-request date range is capped at 60 days between date_from and date_to.
• date_from and date_to must be provided together. Passing only one returns a 400 error; it does not fall back to a default range.
• Event importance is a 3-level classification (Major/Moderate/Standard), not a numeric volatility or deviation score.
• Endpoint access and your per-minute rate limit depend on your subscription plan; some plans further restrict how far back you can query historical events.

Related APIs

• Government Bonds API: see how bond yields react around scheduled economic events.
• Economic Indicators API: the underlying indicator values behind these calendar releases.

Full API documentation →