Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: FX Macrodata Data Catalogue API
description: Official-source macroeconomic indicators, release calendars, central-bank policy rates, FX reference rates, COT positioning and commodities across 22 currencies. USD data is available without an API key; other currencies and datasets need an `X-API-Key` header.
version: 1.0.0
servers:
- url: https://api.fxmacrodata.com
description: FXMacroData API
security:
- {}
- APIKeyHeader: []
- HTTPBearer: []
tags:
- name: data_catalogue
description: Cross-domain metadata index for available indicators.
paths:
/v1/data_catalogue/{currency}:
get:
tags:
- data_catalogue
summary: Get Currently Available Macroeconomic Indicators
description: 'Returns the currently available macroeconomic indicators for a specific currency.
Availability reflects the data currently served, so temporarily
unavailable series are excluded until data is available again. The
catalogue is refreshed on a regular schedule.
This endpoint also replaces the deprecated `/v1/capabilities` and
`/v1/coverage_matrix` endpoints. Coverage is included directly on each
catalogue entry. To also include the legacy top-level coverage list, call it
with `include_coverage=true`. To include capability metadata, call it with
`include_capabilities=true`.
Each entry includes:
* **name**: The full descriptive name of the metric.
* **unit**: The unit of measurement (e.g., %YoY, Billions of USD).
* **frequency**: How often the data is updated (Daily, Monthly, Quarterly).
* **source** / **source_url**: The publisher or source family for the series, when available.
* **source_series_id** / **source_series_name**: The upstream source identifier and exact source-series label, when available.
* **seasonal_adjustment**: Seasonal basis (`SA`, `NSA`, `UNKNOWN`, or `NOT_APPLICABLE`).
* **price_basis**: GDP/level price basis (`REAL`, `NOMINAL`, or `UNKNOWN`) when applicable.
* **aliases** / **related_indicators**: Optional flat discovery metadata for common alternative names and adjacent indicators.
* **standardization_note**: Optional note explaining sign, unit, scope, or cross-currency comparability choices.
* **has_official_forecast**: Whether the relevant central bank or statistics agency publishes a preliminary, flash, or advance estimate of this indicator before the main/final data release.
* **coverage**: Earliest/latest available dates, row count, recency status, and coverage quality for that indicator.'
operationId: get_data_catalogue_v1_data_catalogue__currency__get
parameters:
- name: currency
in: path
required: true
schema:
type: string
description: The 3-letter currency code (e.g., USD, AUD, EUR, GBP, CHF)
examples:
- USD
title: Currency
enum:
- AUD
- BRL
- CAD
- CHF
- CNH
- CNY
- DKK
- EUR
- GBP
- HUF
- ILS
- JPY
- KRW
- MYR
- NGN
- NOK
- NZD
- PEN
- SEK
- THB
- TWD
- USD
example: AUD
description: 'Required path parameter. The 3-letter currency code (e.g., USD, AUD, EUR, GBP, CHF) Allowed values: AUD, BRL, CAD, CHF, CNH, CNY, DKK, EUR, GBP, HUF, ILS, JPY, KRW, MYR, NGN, NOK, NZD, PEN, SEK, THB, TWD, USD.'
- name: include_capabilities
in: query
required: false
schema:
type: boolean
description: Include currency-scoped endpoint/auth metadata that replaces the deprecated /v1/capabilities response.
default: false
title: Include Capabilities
description: Optional query parameter. Include currency-scoped endpoint/auth metadata that replaces the deprecated /v1/capabilities response.
- name: include_coverage
in: query
required: false
schema:
type: boolean
description: Also include the legacy currency-scoped coverage list that replaces the deprecated /v1/coverage_matrix response. Per-indicator coverage is included in catalogue entries by default.
default: false
title: Include Coverage
description: Optional query parameter. Also include the legacy currency-scoped coverage list that replaces the deprecated /v1/coverage_matrix response. Per-indicator coverage is included in catalogue entries by default.
- name: indicator
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Optional indicator filter when include_coverage=true.
examples:
- inflation
title: Indicator
enum:
- afe_dollar_index
- average_hourly_earnings
- average_hourly_earnings_mom
- balance_on_goods
- balance_on_services
- bgcr
- breakeven_inflation_rate
- broad_dollar_index
- broad_money
- building_approvals
- building_permits
- business_confidence
- capital_account_balance
- cb_assets
- commodity_price_energy
- commodity_price_ex_energy
- commodity_price_index
- commodity_prices
- consumer_confidence
- core_inflation
- core_inflation_median
- core_inflation_mom
- core_inflation_trim
- core_pce
- core_pce_mom
- credit_growth
- crude_oil_inventories
- current_account_balance
- dairy_exports
- deposit_rates
- durable_goods_orders
- effr
- eme_dollar_index
- employment
- exports
- financial_account_balance
- foreign_reserves
- full_time_employment
- fx_reserves
- gdp
- gdp_growth_q4_yoy
- gold_reserves
- gov_bond_10y
- gov_bond_15y
- gov_bond_1_5m
- gov_bond_1m
- gov_bond_1y
- gov_bond_20y
- gov_bond_25y
- gov_bond_2m
- gov_bond_2y
- gov_bond_30y
- gov_bond_3m
- gov_bond_3y
- gov_bond_40y
- gov_bond_4m
- gov_bond_4y
- gov_bond_5y
- gov_bond_6m
- gov_bond_6y
- gov_bond_7y
- gov_bond_8y
- gov_bond_9y
- government_debt
- house_price_index
- house_prices
- household_credit
- household_spending
- housing_starts
- import_prices
- imports
- industrial_production
- inflation
- inflation_linked_bond
- inflation_mom
- initial_jobless_claims
- international_assets
- international_liabilities
- job_openings
- m1
- m2
- m3
- nairu
- natural_gas_storage
- net_foreign_asset_position
- non_farm_payrolls
- non_farm_payrolls_change
- obfr
- part_time_employment
- participation_rate
- pce
- pce_mom
- policy_rate
- policy_rate_midpoint
- policy_rate_mlf
- policy_rate_mro
- policy_rate_target_lower
- ppi
- primary_income_balance
- productivity
- real_yield_20y
- real_yield_30y
- real_yield_5y
- real_yield_7y
- retail_sales
- retail_sales_control_group
- retail_sales_ex_autos
- retail_sales_ex_autos_and_gas
- risk_free_rate
- secondary_income_balance
- sight_deposits
- snb_balance_sheet
- sofr_average_180d
- sofr_average_30d
- sofr_average_90d
- sofr_index
- terms_of_trade
- tgcr
- trade_balance
- trade_weighted_index
- trimmed_mean_inflation
- unemployment
- wage_price_index
- wages
example: afe_dollar_index
description: 'Optional query parameter. Optional indicator filter when include_coverage=true. Allowed values: afe_dollar_index, average_hourly_earnings, average_hourly_earnings_mom, balance_on_goods, balance_on_services, bgcr, breakeven_inflation_rate, broad_dollar_index, broad_money, building_approvals, building_permits, business_confidence, capital_account_balance, cb_assets, commodity_price_energy, commodity_price_ex_energy, commodity_price_index, commodity_prices, consumer_confidence, core_inflation, core_inflation_median, core_inflation_mom, core_inflation_trim, core_pce, core_pce_mom, credit_growth, crude_oil_inventories, current_account_balance, dairy_exports, deposit_rates, durable_goods_orders, effr, eme_dollar_index, employment, exports, financial_account_balance, foreign_reserves, full_time_employment, fx_reserves, gdp, gdp_growth_q4_yoy, gold_reserves, gov_bond_10y, gov_bond_15y, gov_bond_1_5m, gov_bond_1m, gov_bond_1y, gov_bond_20y, gov_bond_25y, gov_bond_2m, gov_bond_2y, gov_bond_30y, gov_bond_3m, gov_bond_3y, gov_bond_40y, gov_bond_4m, gov_bond_4y, gov_bond_5y, gov_bond_6m, gov_bond_6y, gov_bond_7y, gov_bond_8y, gov_bond_9y, government_debt, house_price_index, house_prices, household_credit, household_spending, housing_starts, import_prices, imports, industrial_production, inflation, inflation_linked_bond, inflation_mom, initial_jobless_claims, international_assets, international_liabilities, job_openings, m1, m2, m3, nairu, natural_gas_storage, net_foreign_asset_position, non_farm_payrolls, non_farm_payrolls_change, obfr, part_time_employment, participation_rate, pce, pce_mom, policy_rate, policy_rate_midpoint, policy_rate_mlf, policy_rate_mro, policy_rate_target_lower, ppi, primary_income_balance, productivity, real_yield_20y, real_yield_30y, real_yield_5y, real_yield_7y, retail_sales, retail_sales_control_group, retail_sales_ex_autos, retail_sales_ex_autos_and_gas, risk_free_rate, secondary_income_balance, sight_deposits, snb_balance_sheet, sofr_average_180d, sofr_average_30d, sofr_average_90d, sofr_index, terms_of_trade, tgcr, trade_balance, trade_weighted_index, trimmed_mean_inflation, unemployment, wage_price_index, wages.'
responses:
'200':
description: Indicator metadata keyed by indicator slug, with optional capability and coverage metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/DataCatalogueResponse'
example:
gdp:
name: GDP
unit: '%QoQ'
frequency: Quarterly
has_official_forecast: true
inflation:
name: Inflation (CPI)
unit: '%YoY'
frequency: Monthly
has_official_forecast: false
unemployment:
name: Unemployment Rate
unit: '%'
frequency: Monthly
has_official_forecast: false
policy_rate:
name: Policy Interest Rate
unit: '%'
frequency: Daily
has_official_forecast: false
gov_bond_10y:
name: 10-Year Government Bond Yield
unit: '%'
frequency: Daily
has_official_forecast: false
'404':
description: Currency not found.
content:
application/json:
example:
detail: Currency 'XYZ' not found.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
x-parameter-availability:
currency:
- AUD
- BRL
- CAD
- CHF
- CNH
- CNY
- DKK
- EUR
- GBP
- HUF
- ILS
- JPY
- KRW
- MYR
- NGN
- NOK
- NZD
- PEN
- SEK
- THB
- TWD
- USD
indicator:
- afe_dollar_index
- average_hourly_earnings
- average_hourly_earnings_mom
- balance_on_goods
- balance_on_services
- bgcr
- breakeven_inflation_rate
- broad_dollar_index
- broad_money
- building_approvals
- building_permits
- business_confidence
- capital_account_balance
- cb_assets
- commodity_price_energy
- commodity_price_ex_energy
- commodity_price_index
- commodity_prices
- consumer_confidence
- core_inflation
- core_inflation_median
- core_inflation_mom
- core_inflation_trim
- core_pce
- core_pce_mom
- credit_growth
- crude_oil_inventories
- current_account_balance
- dairy_exports
- deposit_rates
- durable_goods_orders
- effr
- eme_dollar_index
- employment
- exports
- financial_account_balance
- foreign_reserves
- full_time_employment
- fx_reserves
- gdp
- gdp_growth_q4_yoy
- gold_reserves
- gov_bond_10y
- gov_bond_15y
- gov_bond_1_5m
- gov_bond_1m
- gov_bond_1y
- gov_bond_20y
- gov_bond_25y
- gov_bond_2m
- gov_bond_2y
- gov_bond_30y
- gov_bond_3m
- gov_bond_3y
- gov_bond_40y
- gov_bond_4m
- gov_bond_4y
- gov_bond_5y
- gov_bond_6m
- gov_bond_6y
- gov_bond_7y
- gov_bond_8y
- gov_bond_9y
- government_debt
- house_price_index
- house_prices
- household_credit
- household_spending
- housing_starts
- import_prices
- imports
- industrial_production
- inflation
- inflation_linked_bond
- inflation_mom
- initial_jobless_claims
- international_assets
- international_liabilities
- job_openings
- m1
- m2
- m3
- nairu
- natural_gas_storage
- net_foreign_asset_position
- non_farm_payrolls
- non_farm_payrolls_change
- obfr
- part_time_employment
- participation_rate
- pce
- pce_mom
- policy_rate
- policy_rate_midpoint
- policy_rate_mlf
- policy_rate_mro
- policy_rate_target_lower
- ppi
- primary_income_balance
- productivity
- real_yield_20y
- real_yield_30y
- real_yield_5y
- real_yield_7y
- retail_sales
- retail_sales_control_group
- retail_sales_ex_autos
- retail_sales_ex_autos_and_gas
- risk_free_rate
- secondary_income_balance
- sight_deposits
- snb_balance_sheet
- sofr_average_180d
- sofr_average_30d
- sofr_average_90d
- sofr_index
- terms_of_trade
- tgcr
- trade_balance
- trade_weighted_index
- trimmed_mean_inflation
- unemployment
- wage_price_index
- wages
components:
schemas:
DataCatalogueItem:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
unit:
anyOf:
- type: string
- type: 'null'
title: Unit
frequency:
anyOf:
- type: string
- type: 'null'
title: Frequency
source:
anyOf:
- type: string
- type: 'null'
title: Source
source_url:
anyOf:
- type: string
- type: 'null'
title: Source Url
source_url_scope:
anyOf:
- type: string
- type: 'null'
title: Source Url Scope
calendar_release_name:
anyOf:
- type: string
- type: 'null'
title: Calendar Release Name
calendar_source_url:
anyOf:
- type: string
- type: 'null'
title: Calendar Source Url
annualization_source_url:
anyOf:
- type: string
- type: 'null'
title: Annualization Source Url
source_series_id:
anyOf:
- type: string
- type: 'null'
title: Source Series Id
source_series_name:
anyOf:
- type: string
- type: 'null'
title: Source Series Name
source_history_start:
anyOf:
- type: string
- type: 'null'
title: Source History Start
seasonal_adjustment:
anyOf:
- type: string
- type: 'null'
title: Seasonal Adjustment
price_basis:
anyOf:
- type: string
- type: 'null'
title: Price Basis
annualization:
anyOf:
- type: string
- type: 'null'
title: Annualization
period_aggregation:
anyOf:
- type: string
- type: 'null'
title: Period Aggregation
has_official_forecast:
anyOf:
- type: boolean
- type: 'null'
title: Has Official Forecast
is_proxy:
anyOf:
- type: boolean
- type: 'null'
title: Is Proxy
proxy_note:
anyOf:
- type: string
- type: 'null'
title: Proxy Note
aliases:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Aliases
related_indicators:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Related Indicators
standardization_note:
anyOf:
- type: string
- type: 'null'
title: Standardization Note
description:
anyOf:
- type: string
- type: 'null'
title: Description
local_name:
anyOf:
- type: string
- type: 'null'
title: Local Name
maturity_months:
anyOf:
- type: integer
- type: number
- type: 'null'
title: Maturity Months
yield_type:
anyOf:
- type: string
- type: 'null'
title: Yield Type
geography:
anyOf:
- type: string
- type: 'null'
title: Geography
period_basis:
anyOf:
- type: string
- type: 'null'
title: Period Basis
methodology_id:
anyOf:
- type: string
- type: 'null'
title: Methodology Id
freshness_threshold_days:
anyOf:
- type: integer
- type: 'null'
title: Freshness Threshold Days
release_calendar_url:
anyOf:
- type: string
- type: 'null'
title: Release Calendar Url
source_permission_status:
anyOf:
- type: string
- type: 'null'
title: Source Permission Status
source_terms_url:
anyOf:
- type: string
- type: 'null'
title: Source Terms Url
source_permission_evidence:
anyOf:
- type: string
- type: 'null'
title: Source Permission Evidence
source_attribution:
anyOf:
- type: string
- type: 'null'
title: Source Attribution
fallback_source:
anyOf:
- type: string
- type: 'null'
title: Fallback Source
fallback_source_series_id:
anyOf:
- type: string
- type: 'null'
title: Fallback Source Series Id
fallback_source_url:
anyOf:
- type: string
- type: 'null'
title: Fallback Source Url
country:
anyOf:
- type: string
- type: 'null'
title: Country
release_stage:
anyOf:
- type: string
- type: 'null'
title: Release Stage
terms:
anyOf:
- type: string
- type: 'null'
title: Terms
supported_frequency_options:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Supported Frequency Options
series_variants:
anyOf:
- items:
$ref: '#/components/schemas/CatalogueSeriesVariant'
type: array
- type: 'null'
title: Series Variants
coverage:
anyOf:
- $ref: '#/components/schemas/CatalogueCoverage'
- type: 'null'
supported_options:
anyOf:
- $ref: '#/components/schemas/CatalogueSupportedOptions'
- type: 'null'
type: object
title: DataCatalogueItem
CatalogueSeriesVariant:
properties:
series_id:
anyOf:
- type: string
- type: 'null'
title: Series Id
name:
anyOf:
- type: string
- type: 'null'
title: Name
storage_indicator:
anyOf:
- type: string
- type: 'null'
title: Storage Indicator
description: Indicator slug whose observations make up this series variant.
source:
anyOf:
- type: string
- type: 'null'
title: Source
source_series_id:
anyOf:
- type: string
- type: 'null'
title: Source Series Id
source_series_name:
anyOf:
- type: string
- type: 'null'
title: Source Series Name
source_url:
anyOf:
- type: string
- type: 'null'
title: Source Url
source_url_scope:
anyOf:
- type: string
- type: 'null'
title: Source Url Scope
calendar_release_name:
anyOf:
- type: string
- type: 'null'
title: Calendar Release Name
calendar_source_url:
anyOf:
- type: string
- type: 'null'
title: Calendar Source Url
annualization_source_url:
anyOf:
- type: string
- type: 'null'
title: Annualization Source Url
seasonal_adjustment:
anyOf:
- type: string
- type: 'null'
title: Seasonal Adjustment
price_basis:
anyOf:
- type: string
- type: 'null'
title: Price Basis
annualization:
anyOf:
- type: string
- type: 'null'
title: Annualization
period_aggregation:
anyOf:
- type: string
- type: 'null'
title: Period Aggregation
frequency_selector:
anyOf:
- type: string
- type: 'null'
title: Frequency Selector
unit:
anyOf:
- type: string
- type: 'null'
title: Unit
frequency:
anyOf:
- type: string
- type: 'null'
title: Frequency
is_default:
anyOf:
- type: boolean
- type: 'null'
title: Is Default
has_official_forecast:
anyOf:
- type: boolean
- type: 'null'
title: Has Official Forecast
standardization_note:
anyOf:
- type: string
- type: 'null'
title: Standardization Note
coverage:
anyOf:
- $ref: '#/components/schemas/CatalogueCoverage'
- type: 'null'
type: object
title: CatalogueSeriesVariant
CatalogueSupportedOptions:
properties:
basis:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Basis
frequency:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Frequency
revisions:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Revisions
seasonality:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Seasonality
annualization:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Annualization
period_aggregation:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Period Aggregation
type: object
title: CatalogueSupportedOptions
DataCatalogueResponse:
additionalProperties:
$ref: '#/components/schemas/DataCatalogueItem'
propertyNames:
pattern: ^[a-z0-9_]+$
type: object
title: DataCatalogueResponse
description: 'Indicator slug to catalogue entry.
The response is a JSON object whose keys are the indicator slugs published
for the currency (for example ``gdp``, ``inflation``, ``policy_rate``) and
whose values are ``DataCatalogueItem`` objects. Because the slug set
differs by currency, entries are described by ``additionalProperties``
rather than fixed ``properties``. The same slugs are accepted by
``/v1/announcements`` and ``/v1/predictions`` for that currency.'
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
CatalogueCoverage:
properties:
available:
anyOf:
- type: boolean
- type: 'null'
title: Available
requires_api_key:
anyOf:
- type: boolean
- type: 'null'
title: Requires Api Key
earliest_available_date:
anyOf:
- type: string
- type: 'null'
title: Earliest Available Date
latest_available_date:
anyOf:
- type: string
- type: 'null'
title: Latest Available Date
latest_release_date:
anyOf:
- type: string
- type: 'null'
title: Latest Release Date
row_count:
anyOf:
- type: integer
- type: 'null'
title: Row Count
value_available:
anyOf:
- type: boolean
- type: 'null'
title: Value Available
has_recent_data:
anyOf:
- type: boolean
- type: 'null'
title: Has Recent Data
recent_observation_count:
anyOf:
- type: integer
- type: 'null'
title: Recent Observation Count
coverage_quality:
anyOf:
- type: string
- type: 'null'
title: Coverage Quality
history_coverage_quality:
anyOf:
- type: string
- type: 'null'
title: History Coverage Quality
freshness_quality:
anyOf:
- type: string
- type: 'null'
title: Freshness Quality
usable_for_context:
anyOf:
- type: boolean
- type: 'null'
title: Usable For Context
usable_for_signal:
anyOf:
- type: boolean
- type: 'null'
title: Usable For Signal
data_lag_days:
anyOf:
- type: integer
- type: 'null'
title: Data Lag Days
stale_after_days:
anyOf:
- type: integer
- type: 'null'
title: Stale After Days
has_yoy_transform:
anyOf:
- type: boolean
- type: 'null'
title: Has Yoy Transform
has_qoq_transform:
anyOf:
- type: boolean
- type: 'null'
title: Has Qoq Transform
has_mom_transform:
anyOf:
- type: boolean
- type: 'null'
title: Has Mom Transform
source_freshness:
anyOf:
- type: string
- type: 'null'
title: Source Freshness
source_monitoring_complete:
anyOf:
- type: boolean
- type: 'null'
title: Source Monitoring Complete
known_source_gap:
anyOf:
- type: boolean
- type: 'null'
title: Known Source Gap
source_checked_at:
anyOf:
- type: integer
- type: 'null'
title: Source Checked At
source_check_expires_at:
anyOf:
- type: integer
- type: 'null'
title: Source Check Expires At
latest_published_period:
anyOf:
- type: string
- type: 'null'
title: Latest Published Period
is_stale:
anyOf:
- type: boolean
- type: 'null'
title: Is Stale
type: object
title: CatalogueCoverage
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
description: 'FXMacroData API key. Preferred transport for server-side clients: the key stays out of URLs and access logs.'
HTTPBearer:
type: http
scheme: bearer
description: 'FXMacroData API key or OAuth access token supplied as ``Authorization: Bearer <key>``.'
APIKeyQuery:
type: apiKey
in: query
name: api_key
x-deprecated: true
description: 'Deprecated. FXMacroData API key as a query parameter. Still accepted so existing integrations keep working, but new integrations must use the X-API-Key header (APIKeyHeader) or Authorization: Bearer. The only exception is browser EventSource clients of the live-delivery streams, which cannot set request headers.'