announcements

Get macroeconomic indicator data

Fetches historical data for a given macroeconomic indicator of a currency.

Authentication & limits:

  • USD data is publicly accessible without an API key, but anonymous callers are limited to the most recent 90 days. Requests for an earlier start_date are clamped to that 90-day window, and the response then carries a freemium_window object naming the cutoff so a shortened history is distinguishable from a short series.
  • Anonymous USD data is also delayed by 15 minutes. A release is served once it is 15 minutes old; until then it is withheld, and latest_available_date reports the newest observation the caller can actually read. Every anonymous response carries a freemium_delay object naming the cutoff, the number of withheld releases and when the next one becomes available. An API key removes the delay.
  • All other currencies require an Individual or Business API key supplied via ?api_key=<key> or the X-API-Key header.
  • Authenticated callers (any valid API key) receive the full requested history for every supported currency, including USD.

Path Parameters:

  • currency: The 3-letter currency code (USD, AUD, EUR, GBP, CHF).
  • indicator: The indicator name (e.g., inflation, unemployment).

Query Parameters:

  • start_date: Optional. Start date in YYYY-MM-DD format. When omitted by authenticated callers, the endpoint pages through the full available history. Anonymous USD requests are capped to the freemium window.

  • end_date: Optional. End date in YYYY-MM-DD format. Defaults to today.

  • limit: Optional page size. Defaults to 20.

  • page: Optional one-based page number. When provided, it takes precedence over offset.

  • offset: Optional zero-based row offset for offset-based pagination.

  • series_mode: Optional. raw (default) selects the direct underlying indicator series; canonical applies configured remaps.

  • value_mode: normalized (default) returns presentation-ready values. source requires series_mode=raw and returns values and revision values as published by the source, without normalization, derived changes, companion fills or carry-forward. Use source mode for historical research. The response declares value_mode and value_metadata.source_unit; an unknown source unit is null.

Empty windows:

  • A valid series with no observations inside the requested window returns 200 with data: [], requested_window_has_data: false, and a no_data object carrying error_code, latest_available_date, recommended_start_date and available_observation_count. This is a successful query, not an error, and should not be retried; widen the window instead.
  • Anonymous USD callers see this whenever a quarterly or annual series' latest observation predates the 90-day freemium window; no_data.freemium_clamped marks that case.
  • 404 on this endpoint means the currency or indicator slug is not published. Use /v1/data_catalogue/{currency} to list valid slugs.

Response fields:

  • remap: Metadata about the canonical remap rule application (applied, rule_id, segments, and transform mode).
  • 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.
  • earliest_available_date / latest_available_date: The full coverage span available in the response window before any pagination is applied.
  • pagination: Page metadata for the returned data[] slice (limit, offset, returned_count, total_count, has_more, next_offset).
  • data[].announcement_id: Stable identifier for this unique announcement, in the form {currency}_{indicator}_{date} (lowercase, e.g. usd_inflation_2026-01-31). Use this to join predictions from /v1/predictions/{currency}/{indicator} and revision history back to the underlying observation.
  • data[].announcement_datetime: Release timestamp as Unix epoch seconds (UTC).
  • data[].announcement_datetime_local: ISO 8601 release time with offset, rendered in the source agency's local timezone (e.g. USD → America/New_York, AUD → Australia/Sydney).
  • data[].official_planned_release_datetime: Official planned release timestamp from the publisher's release calendar, as Unix epoch seconds (UTC). Present when the release was captured against a pre-announced official release time.
  • data[].official_actual_release_datetime: Official release timestamp on the source row, as Unix epoch seconds (UTC). This is normally the same as announcement_datetime unless the source exposes a separate publication timestamp.
  • data[].collected_at_ns / data[].collected_at_iso: Exact time FXMacroData first captured this row from the official source.
  • data[].release_timing: scheduled_at is the official schedule. published_at equals published_by, the observed upper publication bound, not an exact publisher timestamp. published_after is the proven lower bound. picked_up_at is accepted capture; available_at is store commit, not client receipt. source_pickup_latency_min_ms / source_pickup_latency_max_ms measure publication-to-capture bounds; latency_ms and pickup_ms_* end at store commit. publication_delay_ms is a schedule-to-observed-bound diagnostic. Missing measurements remain null. The 1000ms source_pickup_slo_ms is a classification threshold, not a measured latency or guarantee. An unverified publication clock stays unverified.
  • data[].ingestion_latency_ms / ingestion_latency_reference: Deprecated optional diagnostics retained when stored. They measure collection against the original named schedule or actual-release reference, and are never recomputed from the new timing fields. See /documentation/deprecation-policy#legacy-announcement-latency.
  • data[].publication_time_status: what announcement_datetime is evidence of - confirmed (the publisher's own timestamp), unverified (a real timestamp whose origin the row does not prove; with publication_time_basis=official_schedule it is the publisher's scheduled release instant that the value was captured against), assumed_historical (derived from measured lag, pre-launch rows only) or unknown (no time; the row is served on its period date). A schedule instant is never promoted to confirmed.
  • fields=compact: trims each row to date, val, previous_value, change_from_previous, announcement_datetime, announcement_datetime_local and publication_time_status, with revisions[] folded into revisions_summary. The envelope, pagination and dataset_version are the same as the full view.
  • source_series_name: The actual underlying source series used for this standardized indicator.
  • value_name: The actual series name used for the returned val. For policy_rate, this is the canonical policy-series label chosen by the platform (for example, ECB Deposit Facility Rate or Federal Funds Target Range Upper Bound).
  • source_local_name: Official local-language series label when available.
  • is_proxy: True when the standardized indicator is populated using a documented proxy rather than a directly named national headline series.
  • proxy_note: Short explanation of the proxy choice when is_proxy=true.
  • policy_role: For policy_rate, the role of the canonical rate inside its official rate family (for example primary or target_upper).
  • policy_structure: For policy_rate, the policy-regime structure such as single_primary, target_range, primary_plus_corridor, or non_rate_regime.
  • comparison_compatible: For policy_rate, whether the returned val can be honestly used in cross-country policy-rate comparisons.
  • policy_family: Optional top-level metadata listing sibling policy-rate indicators in the same official family.
  • data[].predicted_value (deprecated — use /v1/predictions/{currency}/{indicator} instead): Market or professional-forecaster expectation for this indicator reading, in the same units as val. Present only where a prediction source is available.
  • data[].prediction_type (deprecated — use /v1/predictions/{currency}/{indicator} instead): Legacy per-source category. See prediction_class on /v1/predictions for the consolidated axis: market_consensus covers both compiled consensus and forecaster surveys, and market_prediction is market-implied, not a survey.
  • data[].prediction_source (deprecated — use /v1/predictions/{currency}/{indicator} instead): Stable identifier for the prediction source (e.g. ecb_spf for the ECB Survey of Professional Forecasters). Null when predicted_value is absent.
get/v1/announcements/{currency}/{indicator}

Request

  • Base URL: https://api.fxmacrodata.com
  • URL: https://api.fxmacrodata.com/v1/announcements/{currency}/{indicator}
  • Auth: one of:
    • none
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

currency'AUD' | 'BRL' | 'CAD' | 'CHF' | 'CNH' | 'CNY' | 'DKK' | 'EUR' | 'GBP' | 'HUF' | 'ILS' | 'JPY' | 'KRW' | 'MYR' | 'NGN' | 'NOK' | 'NZD' | 'PEN' | 'SEK' | 'THB' | 'TWD' | 'USD' required
Example:AUD

Required path parameter. Allowed values: 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' required
Example:afe_dollar_index

Required path parameter. 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.

Query parameters

start_datestring

Start date YYYY-MM-DD

Example:2025-01-01

Optional query parameter. Start date YYYY-MM-DD

end_datestring

End date YYYY-MM-DD

Example:2026-03-01

Optional query parameter. End date YYYY-MM-DD

series_modestring

Optional series rendering mode. canonical applies configured remap rules (for continuity across methodology transitions). raw returns the direct indicator series without remapping.

Example:raw

Optional query parameter. Optional series rendering mode. canonical applies configured remap rules (for continuity across methodology transitions). raw returns the direct indicator series without remapping.

limitinteger

Maximum number of rows to return in data[]. Rows are ordered most-recent-first, so limit=10 returns the 10 most recent observations within the requested window. Use together with offset to page through long histories. Defaults to 20. Maximum 100.

Example:20

Optional query parameter. Maximum number of rows to return in data[]. Rows are ordered most-recent-first, so limit=10 returns the 10 most recent observations within the requested window. Use together with offset to page through long histories. Defaults to 20. Maximum 100.

offsetinteger

Number of rows to skip from the start of data[] (after most-recent-first ordering). Use with limit for pagination. Defaults to 0.

Optional query parameter. Number of rows to skip from the start of data[] (after most-recent-first ordering). Use with limit for pagination. Defaults to 0.

pageinteger nullable

One-based page number for callers that prefer page-based pagination. When supplied, offset is derived as (page - 1) * limit.

Example:1

Optional query parameter. One-based page number for callers that prefer page-based pagination. When supplied, offset is derived as (page - 1) * limit.

seasonality'sa' | 'nsa' nullable

Optional seasonal adjustment selector. Supported public values are sa and nsa; check supported_options.seasonality in the response/catalogue for values available on this endpoint.

Example:sa

Optional query parameter. Optional seasonal adjustment selector. Supported public values are sa and nsa; check supported_options.seasonality in the response/catalogue for values available on this endpoint. Allowed values: sa, nsa.

frequency'level' | 'yoy' | 'qoq' | 'mom' nullable

Optional returned change basis. Supported public values are level, yoy, qoq, and mom; check supported_options.frequency for values available on this endpoint.

Example:level

Optional query parameter. Optional returned change basis. Supported public values are level, yoy, qoq, and mom; check supported_options.frequency for values available on this endpoint. Allowed values: level, yoy, qoq, mom.

annualization'not_annualized' | 'saar' nullable

Optional annualization selector. Supported public values are not_annualized and saar; check supported_options.annualization for values available on this endpoint.

Example:not_annualized

Optional query parameter. Optional annualization selector. Supported public values are not_annualized and saar; check supported_options.annualization for values available on this endpoint. Allowed values: not_annualized, saar.

period_aggregation'monthly' | 'quarterly_average' nullable

Optional period-aggregation selector. Supported public values are monthly and quarterly_average; check supported_options.period_aggregation for values available on this endpoint.

Example:monthly

Optional query parameter. Optional period-aggregation selector. Supported public values are monthly and quarterly_average; check supported_options.period_aggregation for values available on this endpoint. Allowed values: monthly, quarterly_average.

revisions'latest' | 'first' | 'final' | 'all' nullable

Optional revision view. Supported public values are latest, first, final, and all; unsupported views return unsupported_series_option with supported values.

Example:latest

Optional query parameter. Optional revision view. Supported public values are latest, first, final, and all; unsupported views return unsupported_series_option with supported values. Allowed values: latest, first, final, all.

basis'real' | 'nominal' nullable

Optional real/nominal selector. Supported public values are real and nominal; only endpoints with known basis metadata accept it.

Example:real

Optional query parameter. Optional real/nominal selector. Supported public values are real and nominal; only endpoints with known basis metadata accept it. Allowed values: real, nominal.

official_onlyboolean

When true, return only official-source rows and remove explicit fallback observations. Prohibited private aggregator rows are always removed regardless of this setting.

Example:true

Optional query parameter. When true, return only official-source rows and remove explicit fallback observations. Prohibited private aggregator rows are always removed regardless of this setting.

fieldsstring nullable

Row field set. Omitted or full returns every documented row field. compact returns only date, val, previous_value, change_from_previous, announcement_datetime, announcement_datetime_local and publication_time_status per row, with the revision ledger folded into revisions_summary (count, first, latest, revised). The envelope, pagination and dataset_version are unchanged.

Example:compact

Optional query parameter. Row field set. Omitted or full returns every documented row field. compact returns only date, val, previous_value, change_from_previous, announcement_datetime, announcement_datetime_local and publication_time_status per row, with the revision ledger folded into revisions_summary (count, first, latest, revised). The envelope, pagination and dataset_version are unchanged.

as_ofstring nullable

Optional query parameter.

availability'public' | 'captured'

Optional query parameter.

dataset_versionstring nullable

Optional query parameter.

value_mode'normalized' | 'source'

Optional query parameter.

api_keystring

Your Individual or Business API key

Deprecated: legacy query-string API key. Still accepted so existing integrations keep working, but new integrations must send the key in the X-API-Key header (or Authorization: Bearer). A key is required for non-USD, paid-only, or full-history requests. Responses to requests authenticated this way carry a Deprecation header.

Response

Normalized macro series for one currency and indicator.

currencystring required
indicatorstring required
namestring nullable
unitstring nullable

Unit of data[].val in this response, from the series catalogue: the normalized unit by default, the percent unit of a derived frequency view (%YoY, %QoQ, %MoM), or value_metadata.source_unit when value_mode=source. Omitted when the catalogue declares no unit.

value_namestring nullable
sourcestring nullable
source_urlstring nullable
source_series_idstring nullable
source_series_namestring nullable
source_local_namestring nullable
seasonal_adjustmentstring nullable
price_basisstring nullable
is_proxyboolean
proxy_notestring nullable
policy_rolestring nullable
policy_structurestring nullable
comparison_compatibleboolean nullable
has_official_forecastboolean required
requested_start_datestring nullable
requested_end_datestring nullable
requested_window_has_databoolean nullable
page_includes_latest_availableboolean nullable
start_datestring required
end_datestring required
earliest_available_datestring nullable
latest_available_datestring nullable
selected_series_idstring nullable
supported_optionsobject nullable
replayobject nullable
dataset_versionstring nullable
value_mode'normalized' | 'source'
value_metadataobject nullable
no_dataobject nullable

Example response

{
  "unit": "Persons",
  "data": [
    {
      "publication_time_status": "confirmed",
      "publication_time_precision": "minute",
      "publication_time_basis": "official_schedule",
      "announcement_source_url": "https://www.bls.gov/news.release/archives/cpi_08122026.htm"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.