Introducing the Currency Latest Endpoint

Scanning the macro state of a currency used to mean firing a separate API call for each indicator — one for inflation, one for unemployment, one for the policy rate, and so on. Starting today, you can retrieve the latest value, the preceding print, and the period-over-period percent change for every indicator in a single authenticated request. The same one-call pattern is now available for COT positioning and commodity prices.

What's New

Three new /latest aggregate endpoints are live in the FXMacroData API:

Every response includes a top-level as_of date derived from the most recent indicator in the dataset, so you always know the data currency without parsing individual rows. Each indicator entry follows a consistent shape:

• indicator — canonical slug matching the announcements endpoint
• unit and frequency — from the data catalogue, so you can format values correctly without a second lookup
• latest — date, val, and announcement_datetime of the most recent print
• previous — the preceding observation in the same fields
• pct_diff_prev — pre-computed percent change from previous to latest, rounded to two decimal places

For COT data, pct_diff_prev is a map rather than a scalar — one percentage change per numeric positioning field (open interest, non-commercial long and short, net positions, and so on) — because the full COT snapshot is multi-dimensional.

Why It Matters for Traders

If your system monitors seven currencies — something like USD, EUR, GBP, AUD, JPY, CAD, and CHF — with ten to fifteen indicators each, a naive polling loop can require over a hundred individual API calls to update a dashboard or feed a model. Beyond network overhead, that approach also means processing partial state: your USD inflation value might be two seconds older than your USD unemployment value, depending on when each request completed.

The /latest endpoints read from the Firestore announcement store — the same data that backs the full historical series — so there is no separate cache or lag introduced by the aggregate call. The data you get back is identical to querying each indicator individually.

Practical Example: USD Macro Snapshot

You are monitoring the US macro picture before the New York open. One call to the USD announcements /latest endpoint returns the current state of every tracked indicator, each with its previous print and the change between them:

curl "https://fxmacrodata.com/api/v1/announcements/usd/latest?api_key=YOUR_API_KEY"

Representative response (truncated to three indicators):

{
  "currency": "USD",
  "source": "store",
  "as_of": "2026-03-31",
  "count": 14,
  "data": [
    {
      "indicator": "inflation",
      "unit": "%",
      "frequency": "Monthly",
      "has_official_forecast": false,
      "latest": {
        "date": "2026-02-28",
        "val": 2.8,
        "announcement_datetime": 1772433000
      },
      "previous": {
        "date": "2026-01-31",
        "val": 2.9,
        "announcement_datetime": 1769754600
      },
      "pct_diff_prev": -3.45
    },
    {
      "indicator": "non_farm_payrolls",
      "unit": "Persons",
      "frequency": "Monthly",
      "has_official_forecast": false,
      "latest": {
        "date": "2026-03-31",
        "val": 228000,
        "announcement_datetime": 1774857000
      },
      "previous": {
        "date": "2026-02-28",
        "val": 151000,
        "announcement_datetime": 1772256600
      },
      "pct_diff_prev": 50.99
    },
    {
      "indicator": "unemployment",
      "unit": "%",
      "frequency": "Monthly",
      "has_official_forecast": false,
      "latest": {
        "date": "2026-03-31",
        "val": 4.1,
        "announcement_datetime": 1774857000
      },
      "previous": {
        "date": "2026-02-28",
        "val": 4.1,
        "announcement_datetime": 1772256600
      },
      "pct_diff_prev": 0.0
    }
  ]
}

From this single response a trader or model can immediately read that headline USD inflation eased slightly month-on-month while non-farm payrolls printed significantly stronger than the prior month. The unemployment rate held flat. That combination — stronger employment against softer inflation — is enough to shape a view on the near-term Fed path without opening a second request.

Practical Example: EUR/USD COT Scan

CFTC Commitment of Traders reports are published weekly. The COT /latest endpoint returns the most recent full snapshot alongside the prior week's snapshot, with percentage changes per field. For EUR, the call also includes the conventional fx_overlay pair for chart overlays:

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

Representative response:

{
  "currency": "EUR",
  "instrument": "EURO FX - CHICAGO MERCANTILE EXCHANGE",
  "fx_overlay": { "pair": "EUR/USD" },
  "source": "store",
  "latest": {
    "date": "2026-03-25",
    "announcement_datetime": 1774478400,
    "open_interest": 612380,
    "noncommercial_long": 198450,
    "noncommercial_short": 108900,
    "noncommercial_net": 89550
  },
  "previous": {
    "date": "2026-03-18",
    "announcement_datetime": 1773873600,
    "open_interest": 598200,
    "noncommercial_long": 184200,
    "noncommercial_short": 112100,
    "noncommercial_net": 72100
  },
  "pct_diff_prev": {
    "open_interest": 2.37,
    "noncommercial_long": 7.74,
    "noncommercial_short": -2.86,
    "noncommercial_net": 24.2
  }
}

In one response, a positioning system can see that EUR speculative longs increased 7.74% week-over-week while shorts contracted 2.86%, widening the net long position by over 24%. That shift in non-commercial net positioning is immediately actionable without any client-side arithmetic.

Practical Example: Commodities State in Python

Rather than polling each commodity independently on a schedule, the commodities /latest endpoint returns all supported commodity indicators in a single call. Here is a minimal Python example that fetches the full snapshot and flags any commodity that has moved more than 2% since its prior print:

import requests

FXMD_API_KEY = "YOUR_API_KEY"
BASE_URL = "https://fxmacrodata.com/api/v1"

def commodities_movers(threshold_pct: float = 2.0):
    resp = requests.get(
        f"{BASE_URL}/commodities/latest",
        params={"api_key": FXMD_API_KEY},
        timeout=10,
    )
    resp.raise_for_status()
    payload = resp.json()

    movers = [
        entry for entry in payload["data"]
        if entry.get("pct_diff_prev") is not None
        and abs(entry["pct_diff_prev"]) >= threshold_pct
    ]

    print(f"Commodities snapshot as of {payload['as_of']}")
    for m in movers:
        direction = "▲" if m["pct_diff_prev"] > 0 else "▼"
        print(
            f"  {m['indicator']:20s}"
            f"  latest={m['latest']['val']} {m['unit']}"
            f"  {direction} {abs(m['pct_diff_prev']):.2f}% vs prior"
        )

commodities_movers(threshold_pct=2.0)

The script makes a single API call regardless of how many commodity indicators are tracked. Swap the threshold or extend the filter conditions to build a commodity alert rule suited to your strategy.

How It Fits with the Full Announcements Endpoint

The /latest endpoints are designed for state-awareness, not history. When you need a time series — backtesting, building rolling averages, computing YoY comparisons, or drawing a chart — use the full announcements endpoint with a date range. When you need to know the current macro state of a currency right now, use /latest.

The two complement each other cleanly in event-driven workflows. Listen to the FXMacroData SSE stream for release events; when an event fires for a currency, call that currency's /latest endpoint once to refresh your current-state snapshot. If you need deeper context for the printed indicator — trend, seasonal comparison, revision history — follow up with a targeted full-series call to that specific indicator.

This keeps the total request volume proportional to how many currencies actually publish data in a given session — not to the size of your indicator inventory.

Get Started

USD announcements are public. All other currency announcements, COT data, and commodity prices require an authenticated API key supplied via the ?api_key= query parameter.