Economic Calendar API

Quick Start: Pull Your First Economic Events

Three steps from zero to a live economic news feed: get a key, open one link, read the JSON. A browser is enough to try it, and the same link works from a terminal, a Python script or an MT5 robot.

{
  "status": true,
  "response": [
    {
      "title": "Core PCE Price Index MoM",
      "country": "US",
      "importance": "2",
      "date": "2026-10-29 12:30:00",
      "actual": "0.3",
      "forecast": "0.3",
      "previous": "0.3"
    }
  ]
}

Economic Calendar API Parameters

Eight fields shape a request. Put them in the query string of a GET call, or send them as form data or a JSON body with POST. Only access_key is mandatory, and a field that takes several values expects commas between them.

Economic Calendar API Endpoint and JSON Response

Call forex/economy_cal with GET or POST. The answer is an economic calendar in JSON: response holds one object per event, ordered from the earliest release to the latest, and info echoes the effective time window and the credits charged. The request fields are described in the parameter table.

Response Format

{
    "id": "399075",
    "event": "ECONOMICS:USIRYY",
    "title": "Inflation Rate YoY",
    "indicator": "Inflation Rate",
    "comment": "In the United States, unadjusted Consumer Price Index for All Urban Consumers is based on the prices of a market basket of ...",
    "country": "US",
    "currency": "USD",
    "importance": "2",
    "period": "Sep",
    "actual": "3.7",
    "forecast": "3.6",
    "previous": "3.4",
    "source": "Bureau of Labour Statistics",
    "scale": "",
    "unit": "%",
    "date": "2026-10-14 12:30:00",
    "category": "prce",
    "reference_date": "2026-09-30",
    "source_url": "http://www.bls.gov/"
}

Upcoming and Historical Economic Events by Date

The fields from and to set the time window, and every value you send is read as UTC. Leave both out and you get the current UTC day, 00:00:00 to 23:59:00, while a date-only to reaches 23:59:59. A window that lies ahead lists scheduled releases whose actual is still empty; a window in the past reads the archive described under coverage.

Date and Time Formats

Sending only to keeps the default start, so a to one week ahead lists everything from the beginning of today until then. Text that is not a date is refused with code 112, quoted under errors and fixes.

Converting to Local Time

The API never changes the zone, so convert in your own code. A date that ends in 00:00:00 is an all-day item and should stay a plain date. In JavaScript add a Z before parsing, otherwise the browser reads the text as local time:

const when = new Date(e.date.replace(" ", "T") + "Z");

In Python attach UTC first, then convert to the zone you need:

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

utc = datetime.strptime(e["date"], "%Y-%m-%d %H:%M:%S").replace(tzinfo=timezone.utc)
print(utc.astimezone(ZoneInfo("Asia/Riyadh")))

Forex News by Currency, Pair or Country

symbol follows currencies and country follows economies. Used as a forex news API inside a trading tool, symbol takes the chart name as it is: a six-letter pair is cut into its two currencies, and news for either side comes back.

How symbol Values Are Read

Currency or Country?

The difference matters for the euro. symbol=EUR collects every euro-area release, from the EU aggregate to Germany, France, Italy, Spain and the other members, whereas country=DE returns German releases only. If a request contains both fields, country is applied and symbol is ignored.

High-Impact News and Importance Levels

Every event carries a grade for its usual market effect: 0 low, 1 medium, 2 high. Send one grade or a comma list such as importance=1,2. Values outside 0 to 2 are dropped, and when nothing valid is left the call returns all grades. In a URL write the list with commas; a bracketed list such as [1,2] is not understood and also returns all grades.

Share of Each Grade

The shares come from the eight-week sample measured for the coverage tables.

Grades Are Set per Country

Identical titles can carry different grades. Inflation Rate YoY is a 2 for the United States and the United Kingdom, yet a 0 for many small economies, so filter on importance instead of matching titles.

Event Codes for NFP, CPI and Rate Decisions

An event code identifies one indicator of one economy, for example ECONOMICS:USNFP for US payrolls. The table lists high-impact codes we have checked for eight major economies, written without the ECONOMICS: prefix. Codes for anything else can be copied from the event field of any calendar row.

Verified High-Impact Codes

One Code, a Family of Events

Rate-decision codes also gather the events around a meeting. ECONOMICS:USINTR brings the Fed Interest Rate Decision together with the Fed press conference, FOMC minutes, FOMC economic projections and speeches by Fed officials. ECONOMICS:GBINTR adds MPC votes, MPC minutes and BoE speeches to the BoE decision, ECONOMICS:EUINTR adds the ECB press conference and Lagarde speeches, and ECONOMICS:AUINTR includes the RBA meeting minutes. When only the decision matters, keep the rows whose title ends in "Interest Rate Decision". Adding importance=2 shrinks the family too: for USINTR over 13 months it cuts about 400 rows (9 credits) to 38 (1 credit), namely the nine decisions with their press conferences and minutes, the projections and a few chair speeches. USNFP also holds the annual payroll revision, so keep the rows titled "Non Farm Payrolls" for the monthly prints.

Historical Economic Calendar Data for One Event

With event in the request, the endpoint returns the release history of the listed codes instead of a daily schedule. symbol and country are ignored in this mode, and the default window changes: without dates it runs from the first day of the month six months back to the last day of the current month, which often includes the next scheduled release.

Writing Codes in a Request

• Prefix optional.event=USNFP and event=ECONOMICS:USNFP return the same series: older rows were stored with the short code, and the API looks for both forms.
• Not case-sensitive.usnfp works too, and spaces next to the commas of a list are ignored.
• Numeric codes. Holidays and some speeches have no official code, so their event value is a number; send that number like any other code.
• Long ranges. Add from and to to reach further back; a longer window returns more rows and costs more, as the credit table shows.

Category, Reference Date and Source URL of Each Event

Every event ends with three descriptive fields after date: category, reference_date and source_url. They are part of every reply and need no request field. The 16 values before them keep their names, order and meaning. A value that is not known comes back as an empty string. The three fields are defined in the field reference.

Category Codes and Their Share

Percentages refer to the same eight weeks of data as the importance shares. For the ECB decision in the right panel, the three values are:

"category": "mny",
"reference_date": "2026-09-10",
"source_url": "https://www.ecb.europa.eu"

Countries Covered and Calendar Data Volume

The calendar spans about 150 countries and roughly 120 currencies, and its archive starts in 2018. New figures are picked up every 5 minutes, so an actual value normally appears within about 5 minutes of publication. The numbers below were measured over eight weeks, 1 September to 26 October 2026, and show how much data a request can return.

Typical Data Volume

Speeches, public holidays, minutes and press conferences never receive an actual value. Auction rows do: their result is published in actual like any other figure.

Busiest Country Calendars

Gulf Calendars

The six Gulf economies SA, AE, KW, QA, BH and OM have thin calendars: together they listed 24 events in the five weeks from 29 October 2026, and 23 of them were grade 0. A call with importance=2 for them therefore returns code 112, so request them with country=SA,AE,KW,QA,BH,OM and no importance filter. Text is English only, every time is UTC (Riyadh is UTC+3 all year), and the API has no language or time zone field: names such as lang or timezone are ignored without an error.

Event count and market weight are different things: China published fewer events than Sweden in this period, yet the second-highest number of high-impact releases.

MT4 / MT5 News Filter for Expert Advisors

The MQL5 code below stops an Expert Advisor from opening trades while high-impact news for its chart pair is near. A timer asks the economic calendar API every 5 minutes for grade-2 events between 15 minutes ago and 30 minutes ahead; while any are found, OnTick skips the entry logic. It is useful when the rules of an account, for example a prop-firm challenge, forbid trading around news.

input string InpApiKey     = "API_KEY";   // your own Corporate+ key; the demo key allows 10 calls an hour
input string InpCurrencies = "";        // e.g. "USD" for GOLD, US30 or BTCUSD; empty = first 6 letters of the chart symbol
input int    InpMinsBefore = 30;   // pause this many minutes before high-impact news
input int    InpMinsAfter  = 15;   // and this many minutes after it (45 or more around FOMC, ECB and BoE decisions)

bool newsBlock = false;

// true when a high-impact event for this chart's pair is inside the window
bool HighImpactNewsNow()
{
   long   now  = (long)TimeGMT();
   string pair = (InpCurrencies != "") ? InpCurrencies : StringSubstr(_Symbol, 0, 6);   // "EURUSD.m" -> "EURUSD"
   string url  = "https://api-v4.fcsapi.com/forex/economy_cal?symbol=" + pair
               + "&importance=2"
               + "&from=" + IntegerToString(now - InpMinsAfter * 60)
               + "&to="   + IntegerToString(now + InpMinsBefore * 60)
               + "&access_key=" + InpApiKey;

   char   data[], result[];
   string resHeaders;
   int code = WebRequest("GET", url, "", 5000, data, result, resHeaders);
   if(code == -1)
   {
      // URL not allowed in the terminal, no internet or a timeout: stay safe and block
      Print("WebRequest error ", GetLastError(), " - allow https://api-v4.fcsapi.com/ under Tools > Options > Expert Advisors");
      return true;
   }
   string body = CharArrayToString(result, 0, WHOLE_ARRAY, CP_UTF8);
   // HTTP 200 + status true = at least one event (the demo key's reply is pretty-printed, so both spellings are checked)
   if(code == 200 && (StringFind(body, "\"status\":true") >= 0 || StringFind(body, "\"status\": true") >= 0))
      return true;
   // no event in the window = code 112 (0 credits)
   if(StringFind(body, "\"code\":112") >= 0)
      return false;
   // any other reply (bad key, plan, credits) is logged and blocks new entries to stay safe
   Print("News API error: ", body);
   return true;
}

int OnInit()
{
   EventSetTimer(300);                  // data refreshes every 5 minutes
   newsBlock = HighImpactNewsNow();
   return(INIT_SUCCEEDED);
}

void OnTimer()                  { newsBlock = HighImpactNewsNow(); }
void OnDeinit(const int reason) { EventKillTimer(); }

void OnTick()
{
   if(newsBlock) return;                // no new entries around high-impact news
   // ... your entry logic ...
}

Economic Calendar API Examples in Python, JavaScript and PHP

Each snippet requests the high-impact EURUSD news of the current day and prints the UTC time, currency, title, actual and forecast of every row. Run them on a server or from a script where the key stays hidden; a key placed in browser JavaScript or an app bundle can be read by anyone.

import requests

params = {
    "symbol": "EURUSD",
    "importance": "2",
    "access_key": "API_KEY",
}
data = requests.get("https://api-v4.fcsapi.com/forex/economy_cal",
                    params=params, timeout=10).json()

if data["status"]:
    for e in data["response"]:
        print(e["date"], "UTC", e["currency"], e["title"],
              "actual:", e["actual"] or "-", "forecast:", e["forecast"] or "-")
else:
    print(data["msg"])

// Node.js 18+ (built-in fetch) or any server-side JS, so the key stays private
const url = "https://api-v4.fcsapi.com/forex/economy_cal"
  + "?symbol=EURUSD&importance=2&access_key=API_KEY";

fetch(url)
  .then(res => res.json())
  .then(data => {
    if (!data.status) return console.log(data.msg);
    for (const e of data.response) {
      console.log(`${e.date} UTC  ${e.currency}  ${e.title}  actual: ${e.actual || "-"}  forecast: ${e.forecast || "-"}`);
    }
  });

<?php
$query = http_build_query([
    "symbol"     => "EURUSD",
    "importance" => 2,
    "access_key" => "API_KEY",
]);

$ch = curl_init("https://api-v4.fcsapi.com/forex/economy_cal?" . $query);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($data["status"])) {
    foreach ($data["response"] as $e) {
        echo $e["date"] . " UTC  " . $e["currency"] . "  " . $e["title"] . PHP_EOL;
    }
} else {
    echo $data["msg"] ?? "Request failed";
}

curl "https://api-v4.fcsapi.com/forex/economy_cal?symbol=EURUSD&importance=2&access_key=API_KEY"

Projects Built on an Economic Events API

Most projects reuse one of a handful of request patterns. Find yours in the table.

Economic Calendar API Pricing and Credits

Calendar access starts with the Corporate plan and is included in every higher plan; keys on smaller plans receive code 105. The charge for a call depends only on the number of events it returns and is reported in info.credit_count. A call that fails or finds nothing is free.

Credits by Reply Size

There is no row limit and no paging: one call returns every matching event, and no limit, offset or page field exists.

What Real Requests Cost

Calendar Request Errors and Fixes

A failed call answers with "status": false, a numeric code and a msg. Check status before reading response. Only code 112 sets HTTP status 400; every other error arrives as HTTP 200 with status false, so branch on the body and not on the HTTP status. A 112 message that starts with "No data" means nothing matched, which also happens when from is later than to or the country is unknown; one that starts with "Invalid" points at a field you must rewrite. Messages are quoted as the API sends them; for 211 and 213 only the opening words are shown.

Economic Calendar API FAQ

What is an economic calendar API?

A web service that delivers the dates, times and results of scheduled economic releases as structured data. Software reads it directly instead of scraping a calendar web page.

Is there a free economic calendar API?

You can try this one at no cost with the demo key API_KEY, which gives a small trimmed sample and allows 10 calls an hour from one IP. Complete data needs the Corporate plan or a higher plan.

How often is the economic calendar updated?

Every 5 minutes. A freshly published figure is usually visible in the actual field about 5 minutes after its release time.

Which time zone does the economic calendar API use?

UTC, both for the times in each reply and for the from and to values you send. Conversion to local time is left to your application.

How far back does the historical economic calendar data go?

The stored history begins in 2018. Request any period since then by setting from and to.

Can I use the economic calendar API in MT4 or MT5?

Yes. An Expert Advisor can call it through WebRequest(), and passing the chart pair as symbol returns the news for both of its currencies.

Which economic events move the forex market the most?

Central bank rate decisions, CPI inflation, Non Farm Payrolls, unemployment and GDP releases of the major economies usually cause the largest moves. The API marks them with importance 2.

Can I get the economic calendar as CSV?

Not directly, because the endpoint answers in JSON, JSONP, serialized PHP, array or object form. Writing the JSON rows to a CSV file takes only a few lines in most languages.

How many credits does an economic calendar request cost?

One credit covers up to 50 returned events, so 51 to 100 events cost two, and failed or empty calls cost nothing. A whole week of high-impact news fits into a single credit.

Does the API include forecasts for upcoming events?

Yes, where a forecast exists it is present before the release, next to the previous reading. The actual field stays empty until the figure is out.

Does the economic calendar API support other languages or time zones?

No. Text is English only and every time is UTC. Names such as lang or timezone are ignored without an error, so convert the times in your own code; the Date Range section shows how for Python and JavaScript.

Can I show the economic calendar on my own website?

Fetch it on your server with your key, cache the reply for the refresh cycle and serve the cached copy to your visitors. A call from browser JavaScript works because the API accepts any origin, but it shows your key to everyone. How the data may be displayed is set by the terms of service.

Economic Calendar Data Disclaimer

Release times are set by the publishing institutions and can change, sometimes at short notice, and published figures are often revised later. Treat the calendar as information rather than trading advice: FCS API accepts no liability for losses from decisions based on it, and use of the data is governed by our terms of service.