Introducing the FXMacroData GraphQL API

The FXMacroData GraphQL API is now live. Alongside the existing REST endpoints, every core data surface — indicator time series, data catalogue queries, and release calendar lookups — is now available through a single, typed GraphQL schema. Fetch exactly the fields you need in one round-trip, compose multi-currency queries in a single request body, and explore the full schema interactively through the built-in GraphiQL IDE.

What's New

The GraphQL endpoint is mounted at POST /api/v1/graphql and exposes three root query fields that mirror the production REST surface:

announcements

Fetch historical macroeconomic indicator data for any supported currency and indicator slug. Returns the same date, val, and announcement_datetime fields as the REST endpoint, plus optional pct_change and pct_change_12m fields.

dataCatalogue

List all available indicators for a currency, including the indicator slug, human-readable name, unit, update frequency, and whether an official central-bank forecast is available.

calendar

Query upcoming economic release timestamps for any supported currency, with an optional indicator filter. Returns Unix epoch timestamps so you can schedule follow-up data fetches precisely.

Authentication uses the same API key as the REST surface — pass it as the api_key query parameter on the request URL. The schema is strongly typed: every field, argument, and return object is documented directly in the schema, so introspection and IDE autocompletion work out of the box.

Why It Matters for Traders and Developers

REST endpoints are efficient for single-indicator lookups. GraphQL becomes valuable the moment your workflow spans multiple currencies, multiple indicators, or multiple data surfaces in a single analytical cycle.

Consider a cross-currency spread model that needs inflation and policy rate history for six G10 currencies simultaneously. With REST you issue twelve sequential HTTP requests. With GraphQL you send one request body containing six announcements field aliases and receive the combined response in a single round-trip — cutting latency, reducing connection overhead, and keeping client code linear.

Precise field selection

Ask only for the fields your model uses. If you need date and val but not the percentage-change enrichments, leave them out. The server skips computing anything not in your selection set.

Single-endpoint integration

One base URL, one auth mechanism, one response envelope. Tooling that already speaks GraphQL — Apollo Client, graphql-request, Python's gql, R's ghql — integrates without any custom REST adapter layer.

Schema-first exploration

Fire an introspection query to enumerate every available currency, indicator, and field type programmatically — no separate documentation scraping required.

Central-bank target context

The announcements query returns an optional cbTarget object alongside the data series — giving you the current central-bank target range, effective date, and source in the same response.

Practical Example: Multi-Currency Inflation Query

Suppose you are building a G3 inflation dashboard and need the last twelve months of CPI data for the USD, EUR, and GBP in one shot. Rather than three sequential REST calls, you alias the announcements field three times within a single GraphQL document:

curl -X POST "https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ usd: announcements(currency: \"USD\", indicator: \"inflation\", startDate: \"2025-04-01\") { currency indicator data { date val announcementDatetime } } eur: announcements(currency: \"EUR\", indicator: \"inflation\", startDate: \"2025-04-01\") { currency indicator data { date val announcementDatetime } } gbp: announcements(currency: \"GBP\", indicator: \"inflation\", startDate: \"2025-04-01\") { currency indicator data { date val announcementDatetime } } }"
  }'

Representative response:

{
  "data": {
    "usd": {
      "currency": "USD",
      "indicator": "inflation",
      "data": [
        { "date": "2026-03-01", "val": 2.8, "announcementDatetime": 1743253200 },
        { "date": "2026-02-01", "val": 3.0, "announcementDatetime": 1740747600 }
      ]
    },
    "eur": {
      "currency": "EUR",
      "indicator": "inflation",
      "data": [
        { "date": "2026-03-01", "val": 2.3, "announcementDatetime": 1743340800 },
        { "date": "2026-02-01", "val": 2.4, "announcementDatetime": 1740834000 }
      ]
    },
    "gbp": {
      "currency": "GBP",
      "indicator": "inflation",
      "data": [
        { "date": "2026-03-01", "val": 2.6, "announcementDatetime": 1743253200 },
        { "date": "2026-02-01", "val": 2.8, "announcementDatetime": 1740747600 }
      ]
    }
  }
}

Three currencies, one HTTP round-trip. The announcementDatetime epoch on each data point gives you the exact second the print was released, so you can align the series on event time rather than calendar month when modelling market reactions. Pair this with the USD policy rate endpoint and its EUR and GBP equivalents to add the rate-differential layer.

Practical Example: Discover Available Indicators

Before building a new model, you can query the data catalogue via GraphQL to enumerate every indicator available for a currency, including its update frequency and whether an official central-bank forecast accompanies the release:

curl -X POST "https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ dataCatalogue(currency: \"AUD\") { currency indicators { slug name unit frequency hasOfficialForecast } } }"
  }'

Representative response (truncated):

{
  "data": {
    "dataCatalogue": {
      "currency": "AUD",
      "indicators": [
        {
          "slug": "policy_rate",
          "name": "Cash Rate Target",
          "unit": "%",
          "frequency": "irregular",
          "hasOfficialForecast": false
        },
        {
          "slug": "inflation",
          "name": "CPI Inflation",
          "unit": "%",
          "frequency": "quarterly",
          "hasOfficialForecast": false
        },
        {
          "slug": "unemployment",
          "name": "Unemployment Rate",
          "unit": "%",
          "frequency": "monthly",
          "hasOfficialForecast": false
        }
      ]
    }
  }
}

The returned slugs map directly to the indicator argument of the announcements query — no separate documentation pass is needed. You can script the discovery step and automatically build a request batch for whichever indicators your model requires. Browse the full AUD indicator set in the AUD API documentation.

Practical Example: Release Calendar Lookup

Knowing when the next high-impact print is due is critical for position sizing around event risk. The calendar query exposes upcoming release timestamps for any supported currency, with an optional indicator filter to narrow the results:

curl -X POST "https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ calendar(currency: \"CAD\", indicator: \"policy_rate\") { currency indicator data { release announcementDatetime } } }"
  }'

Representative response:

{
  "data": {
    "calendar": {
      "currency": "CAD",
      "indicator": "policy_rate",
      "data": [
        {
          "release": "policy_rate",
          "announcementDatetime": 1747400400
        },
        {
          "release": "policy_rate",
          "announcementDatetime": 1752580800
        }
      ]
    }
  }
}

The announcementDatetime values are Unix epoch integers — drop them directly into a scheduler or alert system without any date-parsing step. To scan multiple currencies at once, alias the calendar field just as you would alias announcements: compose one query covering CAD, AUD, and NZD policy rate dates and receive a single consolidated calendar response. See the full CAD policy rate reference for the REST equivalent.

GraphQL vs REST: When to Use Each

Both interfaces draw from the same Firestore-backed data store and carry identical announcement_datetime precision. The choice is a workflow decision:

Scenario	Recommended interface
Single indicator, single currency	REST — simple URL, curl-friendly
Multiple currencies or indicators in one request	GraphQL — field aliasing eliminates multiple round-trips
Strongly typed client (TypeScript, Kotlin, Swift)	GraphQL — generate types from introspection automatically
Notebook or scripting environment	REST or GraphQL — both are single `curl` or `requests.get()` calls
Schema exploration / catalogue discovery	GraphQL — introspection returns the full schema without docs scraping
Existing REST-based pipeline	REST — no migration needed; both surfaces are maintained in parallel

Get Started

The GraphQL endpoint is available to all subscribers on the same API key used for the REST surface. No additional configuration is required.

First steps

Run your first query: curl -X POST "https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY" -H "Content-Type: application/json" -d '{"query":"{ dataCatalogue(currency: \"USD\") { indicators { slug name } } }"}'
Explore the live schema using the API documentation hub
Browse all supported indicators per currency at the API docs
No API key yet? Subscribe to get started — a free tier is available.

Securely Redirecting...