How to Use FXMacroData Endpoints and Authentication

By the end of this guide you will be able to authenticate correctly, choose the right endpoint family for each task, and make production-ready requests across the FXMacroData API without guessing route structure or indicator coverage.

Prerequisites

• A FXMacroData account and API key for non-USD requests
• A terminal with curl or a runtime like Python/Node.js
• Basic familiarity with JSON responses and URL query parameters
• Access to the live docs at /documentation/

Step 1 - Start with the production base URL

All public examples should start from the production API base:

https://fxmacrodata.com/api/v1

The endpoint families you will use most are:

/announcements/{currency}/{indicator} for historical released values with precise announcement_datetime
/calendar/{currency} for upcoming release timestamps
/catalogue/{currency} for discoverability of supported indicators
/cot/{currency} for commitment-of-traders positioning
/commodities/{indicator} for commodity and energy series
/forex/{pair} and /market-sessions for market context

Step 2 - Authenticate correctly with query parameters

FXMacroData uses query-parameter authentication in public usage examples:

?api_key=YOUR_API_KEY

USD endpoint access is available without a key, while non-USD routes require a valid key.

# USD endpoint (no key required)
curl "https://fxmacrodata.com/api/v1/announcements/usd/inflation"

# Non-USD endpoint (key required)
curl "https://fxmacrodata.com/api/v1/announcements/aud/policy_rate?api_key=YOUR_API_KEY"

Step 3 - Discover what is available before coding

Call the catalogue route first when you are unsure which indicators exist for a currency. This avoids hard-coding assumptions.

curl "https://fxmacrodata.com/api/v1/catalogue/eur?api_key=YOUR_API_KEY"

Then use the indicator page index in the documentation indicator index to confirm route paths and expected fields.

Step 4 - Pull released data from announcements endpoints

Announcement endpoints return a top-level object plus a data array of historical releases. Each row includes a period-end date, a val, and an announcement_datetime timestamp.

curl "https://fxmacrodata.com/api/v1/announcements/gbp/unemployment?api_key=YOUR_API_KEY"

{
  "currency": "GBP",
  "indicator": "unemployment",
  "has_official_forecast": false,
  "start_date": "2025-01-31",
  "end_date": "2026-03-31",
  "data": [
    {
      "date": "2026-01-31",
      "val": 4.39,
      "announcement_datetime": 1770521400
    }
  ]
}

For exact indicator semantics and units, check the endpoint pages such as USD policy rate and EUR inflation.

Step 5 - Use the release calendar for event-driven workflows

The release calendar helps you schedule fetches around publication time instead of polling continuously.

curl "https://fxmacrodata.com/api/v1/calendar/usd?indicator=non_farm_payrolls"

A robust pattern is: query calendar -> read next announcement_datetime -> fetch the matching announcements route at release time.

Step 6 - Add supplementary endpoint families

Once your core announcements flow is stable, extend coverage with domain-specific routes:

COT: /api/v1/cot/{currency} for futures positioning context
Commodities: /api/v1/commodities/{indicator} for oil, gas, gold, and related risk inputs
Forex: /api/v1/forex/{pair} for spot alignment with macro releases
Market sessions: /api/v1/market-sessions for session-state-aware automation

curl "https://fxmacrodata.com/api/v1/cot/usd"
curl "https://fxmacrodata.com/api/v1/commodities/oil_brent"
curl "https://fxmacrodata.com/api/v1/forex/eurusd"
curl "https://fxmacrodata.com/api/v1/market-sessions"

Step 7 - End-to-end Python example

The snippet below checks availability, fetches one indicator series, and returns the latest print.

import requests

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


def fetch_latest(currency: str, indicator: str, api_key: str | None = None) -> dict | None:
    params = {}
    if api_key:
        params["api_key"] = api_key

    catalogue = requests.get(f"{BASE}/catalogue/{currency}", params=params, timeout=10)
    catalogue.raise_for_status()

    endpoint = requests.get(
        f"{BASE}/announcements/{currency}/{indicator}",
        params=params,
        timeout=10,
    )
    endpoint.raise_for_status()

    rows = endpoint.json().get("data", [])
    return rows[-1] if rows else None


latest = fetch_latest("aud", "policy_rate", API_KEY)
print(latest)

What you can build next

You now have the full path to authenticate, discover coverage, request historical release series, and expand into calendar-driven automation. A natural next step is pairing this workflow with the release scheduler in How to Use the Release Calendar API so your system reacts exactly when new macro data is published.

Securely Redirecting...