# Introducing the FXMacroData GraphQL API

Canonical: https://fxmacrodata.com/articles/introducing-fxmacrodata-graphql-api
Author: Robert Tidball
Published: 2026-04-16T12:00:00Z

The FXMacroData GraphQL API is now live. Query indicator time series, data catalogues, and release calendars across multiple currencies in a single typed request — the same data, the same precision, one new endpoint.

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](/api-data-docs/usd/policy_rate) 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](/api-data-docs/aud/policy_rate) .

## 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](/api-data-docs/cad/policy_rate) 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](/documentation/)

- Browse all supported indicators per currency at[the API docs](/documentation/)

- No API key yet?[Subscribe to get started](/subscribe) — a free tier is available.

Source: FXMacroData