Fxmacrodata

FXMacroData: Macro and FX Data

Overview

FXMacroData is a REST API for macroeconomic data taken from official publishers (statistics offices, central banks, the CFTC). It covers 22 currencies: AUD, BRL, CAD, CHF, CNH, CNY, DKK, EUR, GBP, HUF, ILS, JPY, KRW, MYR, NGN, NOK, NZD, PEN, SEK, THB, TWD and USD. Each series carries its publisher, source URL and the time the number was released, so answers can cite where a figure came from and when it became public.

This skill covers discovering indicator slugs, pulling release history, reading the release calendar, comparing policy rates between two currencies, and the access limits that apply without an API key.

When to Use

• Use when the user asks for an official macro figure for a country or currency: CPI, core inflation, GDP, unemployment, payrolls, retail sales, business and consumer confidence, trade balance, bond yields.
• Use when the user asks when the next CPI, payrolls, GDP or central-bank decision is due, or wants the release calendar for a week.
• Use when comparing central-bank policy rates or yield differentials between two currencies (for example USD vs JPY carry).
• Use when the user wants daily FX reference rates or CFTC Commitments of Traders positioning for a currency future.
• Do not use for intraday tick data, equities, crypto, or order execution. This is read-only reference data.

Access and Authentication

• Base URL: https://api.fxmacrodata.com/v1
• Authentication is optional. If the user has a key, read it from the FXMACRODATA_API_KEY environment variable and send it in the X-API-Key header. Never put the key in the URL or print it in output.
• Without a key:
  • USD indicators, the USD release calendar, the USD data catalogue and USD COT data work.
  • USD announcement data is delayed by 15 minutes. Each response includes a freemium_delay object with the cutoff time and withheld_count, the number of releases newer than the cutoff.
  • History is limited to the most recent 90 days. The freemium_window object shows the applied cutoff date, and requested_start_date in the response shows the start date actually used.
• Every other currency, /forex, /rate_differentials and /commodities need a key. Without one they return HTTP 401 with "code": "api_key_required". That means the data exists but needs a subscription; do not report it as missing.

# Keyless (USD only)
curl -s "https://api.fxmacrodata.com/v1/announcements/usd/policy_rate?limit=3"

# With a key, from the environment
curl -s -H "X-API-Key: $FXMACRODATA_API_KEY" \
  "https://api.fxmacrodata.com/v1/announcements/eur/policy_rate?limit=3"

Endpoints

Currency codes and indicator slugs are lowercase in paths (usd, policy_rate).

Common query parameters

Response shape

Announcement responses carry metadata (source, source_url, source_series_name, seasonal_adjustment, pagination) and a data array. Each row has:

• date: the reference period the value belongs to.
• val: the value, plus previous_value and change_from_previous when the prior observation is in range.
• announcement_datetime: Unix seconds (UTC) when the figure was published; announcement_datetime_local gives the publisher's local time.
• revisions: earlier vintages of the same observation, where available.

How It Works

Step 1: Find the indicator slug

Slugs differ from common names. US CPI is inflation, not cpi, and payrolls is non_farm_payrolls. Check the catalogue before the first query for a currency:

curl -s "https://api.fxmacrodata.com/v1/data_catalogue/usd" | jq 'keys'
curl -s "https://api.fxmacrodata.com/v1/data_catalogue/usd" | jq '.inflation | {name, unit, frequency, source}'

An unknown slug returns HTTP 404 with a suggestion, for example Did you mean: ppi?.

Step 2: Pull the history

curl -s "https://api.fxmacrodata.com/v1/announcements/usd/unemployment?limit=6" \
  | jq '.data[] | {date, val, announcement_datetime}'

Report the reference period (date) and the publication time (announcement_datetime) separately. A March figure is usually released in April.

Step 3: Check freshness before calling a value "latest"

curl -s "https://api.fxmacrodata.com/v1/announcements/usd/non_farm_payrolls?limit=1" \
  | jq '{latest: .data[0].date, val: .data[0].val, delay: .freemium_delay}'

If freemium_delay.withheld_count is greater than 0, a newer release has been published but is not yet visible to keyless requests. Say so, and do not present the older value as current.

Step 4: Check the next release

curl -s "https://api.fxmacrodata.com/v1/calendar/usd?indicator=non_farm_payrolls&timezone=UTC" \
  | jq '.data[0] | {name, reference_period, announcement_datetime_utc, release_date_confirmed}'

Use announcement_datetime_utc and convert to the user's timezone only when presenting the answer.