How to Use All FXMacroData API Endpoints: A Complete Guide

By the end of this guide you will have working examples for every public endpoint in the FXMacroData API — from the announcement series and release calendar to COT positioning, precious metals prices, forex rates, real-time SSE streaming, and the GraphQL interface — so you can pick the right tool for any macro data workflow.

Step 1 — Announcements: historical indicator series

The announcements endpoint is the core of FXMacroData. It returns a normalized, timestamped time series for any supported macroeconomic indicator. Each row carries the observation date, the released value, and the exact Unix timestamp of the official publication — giving you second-level precision for event-driven research and backtesting.

USD requests work without an API key. For any other currency, append your key as a query parameter. Use start_date and end_date (YYYY-MM-DD) to narrow the window; the default is the last 365 days.

# USD inflation series — no key needed
curl "https://fxmacrodata.com/api/v1/announcements/usd/inflation"

# AUD policy rate — Pro key required
curl "https://fxmacrodata.com/api/v1/announcements/aud/policy_rate?api_key=YOUR_API_KEY"

# EUR GDP with a custom date range
curl "https://fxmacrodata.com/api/v1/announcements/eur/gdp?start_date=2024-01-01&end_date=2026-03-01&api_key=YOUR_API_KEY"

{
  "currency": "USD",
  "indicator": "inflation",
  "has_official_forecast": false,
  "start_date": "2025-03-01",
  "end_date": "2026-03-30",
  "data": [
    {
      "date": "2026-02-01",
      "val": 2.8,
      "announcement_datetime": 1741082400,
      "pct_change": -0.5,
      "pct_change_12m": -6.7
    }
  ]
}

The announcement_datetime field is a Unix timestamp (seconds, UTC) for the exact moment the data was officially published. Use it for event study alignment and to avoid look-ahead bias in backtests. Browse available indicator slugs for any currency with the data catalogue (Step 3) or at API data docs.

Step 2 — Release Calendar: upcoming announcement times

The calendar endpoint returns the scheduled UTC announcement timestamps for every upcoming macro release for a given currency. Use it to schedule a targeted fetch that fires when new data is published rather than polling continuously on a fixed interval.

No API key is required. Filter to a specific indicator with the optional indicator query parameter. The special currency code COMM returns the commodity release schedule.

# All upcoming releases for USD
curl "https://fxmacrodata.com/api/v1/calendar/usd"

# Filter to a single indicator
curl "https://fxmacrodata.com/api/v1/calendar/usd?indicator=non_farm_payrolls"

# Commodity release schedule
curl "https://fxmacrodata.com/api/v1/calendar/COMM"

{
  "currency": "USD",
  "indicator": "non_farm_payrolls",
  "data": [
    {
      "release": "non_farm_payrolls",
      "announcement_datetime": 1746540600,
      "requires_api_key": false
    }
  ]
}

Convert the timestamp to a human-readable UTC time with datetime.fromtimestamp(ts, tz=timezone.utc) in Python or new Date(ts * 1000).toISOString() in JavaScript. For a complete scheduling pattern, see How to Use the Release Calendar API to Schedule Indicator Fetches.

Step 3 — Data Catalogue: discover available indicators

Before writing code that targets a specific indicator, query the catalogue to confirm what is available for a currency. The response maps each indicator slug to its human-readable name, unit, release frequency, and whether the central bank publishes an official forecast for it.

# List all indicators for EUR — no key required
curl "https://fxmacrodata.com/api/v1/data_catalogue/eur"

# Include routing and auth discovery metadata per indicator
curl "https://fxmacrodata.com/api/v1/data_catalogue/usd?include_capabilities=true"

{
  "gdp": {
    "name": "GDP Growth",
    "unit": "%QoQ",
    "frequency": "Quarterly",
    "has_official_forecast": false
  },
  "inflation": {
    "name": "Inflation (CPI)",
    "unit": "%YoY",
    "frequency": "Monthly",
    "has_official_forecast": false
  },
  "policy_rate": {
    "name": "Policy Rate",
    "unit": "%",
    "frequency": "Meeting",
    "has_official_forecast": true
  }
}

The top-level keys in the response are the exact {indicator} slugs to use in announcements calls. Supported currencies include USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD, CNY, SGD, SEK, DKK, PLN, and BRL. Pass include_coverage=true to get a cross-currency availability grid in a single response.

Step 4 — COT Positioning: speculative futures data

The Commitment of Traders endpoint delivers weekly CFTC positioning data for FX futures contracts. It shows total open interest split between non-commercial (speculative), commercial (hedger), and non-reportable participants — a widely tracked leading indicator for currency trend reversals and crowded positioning.

Supported currencies: USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD. USD is free; all others require a Pro key.

# USD COT history — free
curl "https://fxmacrodata.com/api/v1/cot/usd"

# EUR COT with a custom date range
curl "https://fxmacrodata.com/api/v1/cot/eur?start_date=2025-01-01&api_key=YOUR_API_KEY"

{
  "currency": "EUR",
  "instrument": "EURO FX - CHICAGO MERCANTILE EXCHANGE",
  "fx_overlay": { "pair": "EUR/USD" },
  "start_date": "2025-01-07",
  "end_date": "2026-03-25",
  "data": [
    {
      "date": "2026-03-18",
      "announcement_datetime": 1742493000,
      "open_interest": 812345,
      "noncommercial_long": 185000,
      "noncommercial_short": 92000,
      "noncommercial_net": 93000,
      "commercial_long": 203000,
      "commercial_short": 310000,
      "commercial_net": -107000,
      "nonreportable_long": 21000,
      "nonreportable_short": 9000
    }
  ]
}

The noncommercial_net field (speculative long minus short) is the most frequently cited positioning gauge for FX traders. Each row also carries an announcement_datetime for the Friday 3:30 PM ET CFTC publication. For EUR pair context see the EUR policy rate docs.

Step 5 — Metals: gold, silver, and platinum prices

The metals endpoint returns daily price series for precious metals sourced from The Royal Mint (LBMA fixes). These series are useful as cross-asset macro inputs, especially for tracking safe-haven flows and USD-linked dynamics.

A Professional API key is always required for this endpoint. Available indicator slugs: gold, silver, platinum.

# Gold LBMA PM Fix daily prices
curl "https://fxmacrodata.com/api/v1/commodities/gold?api_key=YOUR_API_KEY"

# Silver with a date range
curl "https://fxmacrodata.com/api/v1/commodities/silver?start_date=2025-01-01&api_key=YOUR_API_KEY"

# Platinum spot
curl "https://fxmacrodata.com/api/v1/commodities/platinum?api_key=YOUR_API_KEY"

{
  "currency": "COMM",
  "indicator": "gold",
  "has_official_forecast": false,
  "start_date": "2025-03-30",
  "end_date": "2026-03-30",
  "data": [
    {
      "date": "2026-03-28",
      "val": 2870.00,
      "pct_change": 1.2,
      "pct_change_12m": 30.1
    }
  ]
}

The response shape is identical to the announcements endpoint, so you can reuse the same parsing code. Note that announcement_datetime is null for daily price series and is only populated for official monthly publication events.

Step 6 — Forex Rates: daily spot price series

The forex endpoint returns daily OHLC spot rate data for any supported currency pair. No API key is required. Use it to align macro indicator releases with the contemporaneous exchange rate for backtesting or chart visualization workflows.

Pass base and quote as separate path segments (e.g. /forex/eur/usd for EUR/USD). Add technical indicator overlays with the indicators query parameter.

# EUR/USD daily rates — no key required
curl "https://fxmacrodata.com/api/v1/forex/eur/usd"

# AUD/JPY with a custom date range
curl "https://fxmacrodata.com/api/v1/forex/aud/jpy?start_date=2025-01-01"

# GBP/USD with technical indicators overlaid
curl "https://fxmacrodata.com/api/v1/forex/gbp/usd?indicators=sma_20,rsi_14"

{
  "base": "EUR",
  "quote": "USD",
  "start_date": "2025-03-30",
  "end_date": "2026-03-30",
  "data": [
    {
      "date": "2026-03-28",
      "close": 1.0832,
      "open": 1.0821,
      "high": 1.0867,
      "low": 1.0798
    }
  ]
}

Step 7 — Market Sessions: real-time session state

The market sessions endpoint returns the current open/close status for all four major FX sessions — Sydney, Tokyo, London, and New York — together with the active overlap windows. No API key is required. Use it to gate time-sensitive automation to peak-liquidity windows or to annotate charts with session boundaries.

# Real-time snapshot — no key required
curl "https://fxmacrodata.com/api/v1/market_sessions"

# Historical snapshot for scheduling or testing
curl "https://fxmacrodata.com/api/v1/market_sessions?at=2026-03-28T12:00:00Z"

{
  "now_utc": "2026-03-30T08:47:00Z",
  "now_unix": 1743324420,
  "is_market_day": true,
  "sessions": [
    {
      "name": "London",
      "is_open": true,
      "seconds_to_close": 25200,
      "currencies": ["EUR", "GBP", "CHF"],
      "open_utc": "2026-03-30T07:00:00Z",
      "close_utc": "2026-03-30T15:00:00Z"
    }
  ],
  "overlaps": [
    {
      "name": "London / New York",
      "is_active": false,
      "priority": "high",
      "start_utc": "2026-03-30T12:00:00Z",
      "end_utc": "2026-03-30T16:00:00Z",
      "notable_pairs": ["EUR/USD", "GBP/USD", "USD/CHF"],
      "duration_hours": 4
    }
  ]
}

The London/New York overlap is the highest-liquidity window of the trading day and is when macro releases most frequently cause the largest spot moves. Use is_market_day: false to skip automation on weekends and major market holidays.

Step 8 — Real-Time Stream: SSE event subscription

The SSE endpoint opens a persistent HTTP connection and pushes a lightweight notification every time FXMacroData ingests a fresh economic release. Rather than polling an announcement endpoint on a timer, your application subscribes once and only makes a REST call when the stream tells you new data has actually landed.

USD events work without a key. Add your API key for full cross-currency coverage. Filter the feed with currencies and indicators query parameters to reduce noise.

# Listen for all USD events — no key required
curl -N "https://fxmacrodata.com/api/v1/stream/events"

# Filter by currencies and indicators
curl -N "https://fxmacrodata.com/api/v1/stream/events?currencies=eur,gbp&indicators=inflation,policy_rate&api_key=YOUR_API_KEY"

A typical SSE frame pushed by the server looks like this:

id: usd_inflation_1772109000
event: announcement
data: {"event_id": "usd_inflation_1772109000", "currency": "usd", "indicator": "inflation", "records_written": 1, "timestamp": 1772109002}

After receiving an event, call the matching announcements endpoint (Step 1) to retrieve the full record. The stream is a trigger, not the full dataset — the canonical values always come from the REST endpoint.

For a complete browser EventSource example and a Python worker with explicit replay logic, see How to Stream Live Macro Data with FXMacroData SSE Events.

Step 9 — GraphQL: batch multiple queries in one request

FXMacroData exposes a GraphQL endpoint that mirrors the REST surface exactly — same authentication rules, same field names, same data — but lets you declare only the fields you need and combine multiple queries into a single HTTP round-trip. If you need EUR inflation and GBP policy rate and an AUD release calendar, that is one POST instead of three GETs.

Send a POST to https://fxmacrodata.com/api/v1/graphql with a JSON body containing a query key and your API key as a URL query parameter. The available root fields are announcements, dataCatalogue, and calendar.

# Single free USD query — no key required
curl -s -X POST "https://fxmacrodata.com/api/v1/graphql" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ announcements(currency: \"USD\", indicator: \"inflation\") { currency indicator data { date val pctChange } } }"
  }'

# Batched: EUR inflation + GBP policy rate in one request
curl -s -X POST "https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { eurCPI: announcements(currency: \"EUR\", indicator: \"inflation\") { data { date val } } gbpRate: announcements(currency: \"GBP\", indicator: \"policy_rate\") { data { date val } } }"
  }'

{
  "data": {
    "eurCPI":  { "data": [{ "date": "2026-02-28", "val": 2.3 }] },
    "gbpRate": { "data": [{ "date": "2026-03-20", "val": 4.5 }] }
  }
}

GraphQL returns HTTP 200 even when a query field fails — errors appear in a top-level errors array alongside any successful partial data. Always check for that array before processing the response. For a full Python and JavaScript implementation with error handling and batching patterns, see How to Query FXMacroData via GraphQL.

Step 10 — End-to-end Python workflow

The snippet below pulls together the most common patterns in sequence: discover available indicators, check the next scheduled release, fetch two indicator series in a single GraphQL request, and then conditionally check market session state before routing the output.

import requests
from datetime import datetime, timezone

BASE = "https://fxmacrodata.com/api/v1"
API_KEY = "YOUR_API_KEY"


def params(require_key: bool = True) -> dict:
    return {"api_key": API_KEY} if require_key else {}


# 1. Discover available indicators for AUD (free)
catalogue = requests.get(f"{BASE}/data_catalogue/aud", params=params(False), timeout=10)
catalogue.raise_for_status()
print("AUD indicators:", list(catalogue.json().keys())[:5])

# 2. Check the next USD non-farm payrolls release timestamp (free)
cal = requests.get(f"{BASE}/calendar/usd", params={"indicator": "non_farm_payrolls"}, timeout=10)
cal.raise_for_status()
events = cal.json().get("data", [])
if events:
    ts = events[0]["announcement_datetime"]
    dt = datetime.fromtimestamp(ts, tz=timezone.utc)
    print(f"Next NFP release: {dt.strftime('%Y-%m-%d %H:%M UTC')}")

# 3. Fetch EUR inflation + AUD policy rate in one GraphQL request (Pro key)
gql_query = """
query {
  eurCPI: announcements(currency: "EUR", indicator: "inflation") {
    data { date val pctChange }
  }
  audRate: announcements(currency: "AUD", indicator: "policy_rate") {
    data { date val }
  }
}
"""
resp = requests.post(
    f"{BASE}/graphql",
    params={"api_key": API_KEY},
    json={"query": gql_query},
    timeout=15,
)
resp.raise_for_status()
payload = resp.json()
if "errors" in payload:
    raise RuntimeError(payload["errors"])
data = payload["data"]

eur_latest = data["eurCPI"]["data"][-1]
aud_latest = data["audRate"]["data"][-1]
print(f"EUR CPI  {eur_latest['date']}: {eur_latest['val']}%")
print(f"AUD Rate {aud_latest['date']}: {aud_latest['val']}%")

# 4. Check market sessions before triggering a trade alert (free)
sessions_resp = requests.get(f"{BASE}/market_sessions", timeout=10)
sessions_resp.raise_for_status()
session_data = sessions_resp.json()

if session_data["is_market_day"]:
    for overlap in session_data.get("overlaps", []):
        if overlap["is_active"] and overlap["priority"] == "high":
            print(f"High-liquidity window active: {overlap['name']}")
else:
    print("Market closed — skipping alert")

What you can build next

You now have working examples for every public endpoint in the FXMacroData API. A few natural next steps:

• Combine SSE with calendar-based scheduling. Use the release calendar to know what is due, then keep the SSE stream open as a live confirmation layer — the scheduler wakes you up, the stream confirms the actual publish moment. Read How to Stream Live Macro Data with FXMacroData SSE Events.
• Replace sequential REST calls with GraphQL batching. Anywhere you make three or more independent GET requests, a single GraphQL POST can replace them. Start with How to Query FXMacroData via GraphQL.
• Layer COT positioning over rate differentials. Combine the speculative net from the COT endpoint with the policy rate series to build a composite macro signal across the G8 currency universe.
• Align metals prices with currency releases. Pair gold from the metals endpoint with the AUD or USD announcement series to track safe-haven and dollar correlations over time.

— The FXMacroData Team