FXMacroData GraphQL API
Query macroeconomic indicator data, release calendars, and dataset catalogues through one flexible endpoint. Pull exactly the fields your application needs without carrying the full REST payload every time.
Endpoint
https://api.fxmacrodata.com/v1/graphql
Schema surface
3 query fields
REST parity
33 public routes also available
Why use GraphQL
One request, cleaner payloads
Use GraphQL when you want indicator series, release timing, and catalogue metadata from one entry point without stitching multiple endpoint responses together.
- Request only the fields each client needs.
- Batch multiple datasets into one POST.
- Reuse the same auth model as the public REST API.
Quick Start
curl -X POST https://api.fxmacrodata.com/v1/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "{ announcements(currency: \"USD\", indicator: \"inflation\") { currency data { date val } } }"
}'
For paid endpoints (non-USD announcements, non-USD COT, real-time releases, and USD history older than 90 days), send your key in the X-API-Key: YOUR_API_KEY header.
The calendar and data catalogue queries are open without a key.
Schema
The GraphQL schema exposes three query fields that mirror the core public REST endpoints. Each returns strongly-typed objects — request only the fields your application needs.
Query field
announcements
Fetch historical macroeconomic indicator data with announcement timestamps and percentage change enrichment. Mirrors /v1/announcements/{currency}/{indicator}.
query { announcements( currency: "USD" # required — 3-letter code indicator: "inflation" # required — indicator slug startDate: "2025-01-01" # optional endDate: "2026-01-01" # optional ) { currency indicator hasOfficialForecast startDate endDate cbTarget { description current { effectiveFrom target } } data { date val announcementDatetime pctChange } } }
Query field
dataCatalogue
List all available indicators and their metadata for a given currency. Mirrors /v1/data_catalogue/{currency}.
query { dataCatalogue(currency: "EUR") { currency indicators { slug name unit frequency hasOfficialForecast } } }
Query field
calendar
Get upcoming scheduled release dates for a currency's macro indicators. Mirrors /v1/calendar/{currency}.
query { calendar( currency: "GBP" indicator: "inflation" # optional filter ) { currency indicator data { announcementDatetime release } } }
Example Queries
One request, three datasets
The reason to reach for GraphQL instead of REST: aliases let a single round trip return a policy-rate series, the next CPI release, and the currency's full indicator coverage.
query MacroSnapshot {
policy: announcements(currency: "USD", indicator: "policy_rate", startDate: "2026-01-01") {
indicator
data { date val announcementDatetime }
}
upcoming: calendar(currency: "USD", indicator: "inflation") {
data { announcementDatetime release }
}
coverage: dataCatalogue(currency: "USD") {
indicators { slug name frequency }
}
}
Inflation history with revisions and the central-bank target
Request retained revision values and the central-bank target alongside the series. This projection supplies epoch and value, without capture clocks or strict point-in-time replay. Use REST announcement history for complete public revision evidence and as_of.
query CpiWithRevisions {
announcements(currency: "USD", indicator: "inflation", startDate: "2025-01-01") {
currency
indicator
hasOfficialForecast
cbTarget {
description
current { effectiveFrom target }
}
data {
date
val
pctChange
source
sourceUrl
revisions { epoch val }
}
}
}
Discover coverage before querying it
dataCatalogue needs no API key. Use it to resolve valid indicator slugs, units, and release frequency for a currency before requesting the series itself.
query EurCoverage {
dataCatalogue(currency: "EUR") {
currency
indicators {
slug
name
unit
frequency
hasOfficialForecast
}
}
}
Upcoming releases across several currencies
Alias the calendar field once per currency to build a multi-currency release schedule in one request. This query is also open without an API key.
query ReleaseWeek {
usd: calendar(currency: "USD") {
data { announcementDatetime release }
}
eur: calendar(currency: "EUR") {
data { announcementDatetime release }
}
gbp: calendar(currency: "GBP", indicator: "inflation") {
data { announcementDatetime release }
}
}
Authentication
Authentication for the GraphQL endpoint follows the same rules as the REST API. Send your API key in the X-API-Key header (Authorization: Bearer YOUR_API_KEY is also accepted):
curl -X POST https://api.fxmacrodata.com/v1/graphql \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "{ announcements(currency: \"EUR\", indicator: \"inflation\") { currency data { date val } } }"}'
-
No key required:
dataCatalogueandcalendarqueries are open. -
USD no-key evaluation:
announcements(currency: "USD", ...)is publicly available without a key for the most recent 90 days up to 100 requests/day, on a 15-minute release delay. The response reports the delay infreemiumDelayedandfreemiumWithheldCount. An API key removes the delay and is required for higher-volume use or to query an earlierstartDate. - API key required: Announcements for non-USD currencies require an Individual plan API key.
-
Legacy query parameter:
?api_key=YOUR_API_KEYon the endpoint URL is still accepted for existing integrations but is deprecated, because keys in URLs end up in logs. Prefer theX-API-Keyheader.
REST vs GraphQL
| REST | GraphQL | |
|---|---|---|
| Endpoint | /v1/announcements/{currency}/{indicator} | /v1/graphql |
| Response shape | Fixed — full payload always returned | Flexible — request only the fields you need |
| Multiple queries | Multiple HTTP requests | Single request, batched fields |
| Introspection | OpenAPI/Swagger schema, public | GraphQL introspection (__schema, __type) with an API key; anonymous introspection is refused, and the schema on this page is the public reference |
| Best for | Simple integrations, caching, CDN proxying | Custom clients, dashboards, complex queries |