---
title: "Get upcoming economic data release dates"
method: GET
path: "/v1/calendar/{currency}"
tags: ["calendar"]
---

# Get upcoming economic data release dates

`GET /v1/calendar/{currency}`

## Request

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

Returns upcoming economic data release dates for a given currency.

Announcement rows keep the `release` slug mapping to `/v1/announcements/{currency}/{indicator}`, while other domains such as COT may also include additive fields like `domain`, `endpoint_family`, and `endpoint_path`. Each row also includes a deterministic `calendar_event_id` for joins across calendar exports.

**Path Parameters:**
- `currency`: The 3-letter currency code (e.g., USD).

**Query Parameters:**
- `indicator`: Optional. Filter to a specific indicator (e.g., gdp, inflation, unemployment, non_farm_payrolls).

- `start_date`: Optional inclusive lower bound, YYYY-MM-DD.
- `end_date`: Optional inclusive upper bound, YYYY-MM-DD.

Past releases are retained for a bounded window. When `start_date` is given, `history_start_date` reports the oldest retained release and `history_truncated` is true if the requested window starts before it. Released values and their announcement times for older periods are available from `/v1/announcements/{currency}/{indicator}`.

**Time not announced:** some official publishers announce a release date but not its time. Those rows are included with `time_announced: false` and `announcement_date` set to the publisher's local date; their `announcement_datetime` is 00:00 of that date in the publisher's timezone and is not a release time. Rows with an exact official time have `time_announced: true`. When the publisher later announces the time, the timed row replaces the date-only row.

**Returns:** List of release rows sorted by announcement time ascending (nearest scheduled release first). Core fields remain `announcement_datetime` and `release`; additive routing metadata may also be present.

## Path parameters

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

## Query parameters

- `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': Filter by indicator name (e.g., gdp, inflation, unemployment)
- `start_date` string: Optional inclusive lower bound in YYYY-MM-DD format.
- `end_date` string: Optional inclusive upper bound in YYYY-MM-DD format.
- `timezone` string: Optional IANA timezone for an additional converted timestamp field, for example America/Sao_Paulo.
- `api_key` string: Your Individual or Business API key

## Response `200`

Upcoming release dates for the selected currency and optional indicator filter.

- CalendarResponse
  - `currency` string, required
  - `timezone` string, nullable
  - `requested_timezone` string, nullable
  - `indicator` string, nullable
  - `requested_indicator` string, nullable
  - `start_date` string, nullable
  - `end_date` string, nullable
  - `history_start_date` string, nullable
  - `history_truncated` boolean, nullable
  - `data_quality` DataQuality, required
    - `source_freshness` string, nullable
    - `source_monitoring_complete` boolean, nullable
    - `known_source_gap` boolean, nullable
    - `source_checked_at` integer, nullable
    - `source_check_expires_at` integer, nullable
    - `latest_published_period` string, nullable
    - `source_permission_status` string, nullable
    - `commodity_coverage` CommodityCoverage
      - `scope` string, required
      - `requested_start` string, nullable
      - `requested_end` string, nullable
      - `available_start` string, nullable
      - `available_end` string, nullable
      - `input_row_count` integer, required
      - `row_count` integer, required
      - `distinct_date_count` integer, required
      - `duplicate_date_row_count` integer, required
      - `excluded_weekend_row_count` integer, required
      - `invalid_date_row_count` integer, required
      - `expected_weekday_label_count` integer, required
      - `missing_weekday_label_count` integer, required
      - `largest_missing_weekday_run` integer, required
      - `largest_calendar_gap_days` integer, required
      - `missing_weekday_ranges` CommodityMissingWeekdayRange[], required
        - `start_date` string, required
        - `end_date` string, required
        - `weekday_count` integer, required
      - `longest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `latest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `sparse_history` boolean, required
      - `coverage_basis` string, required
      - `continuous_coverage_verified` boolean
      - `reference_only` boolean
      - `executable_quotes` boolean
      - `provenance_version` integer, required
      - `repaired_excluded_weekend_row_count` integer
      - `repaired_invalid_date_row_count` integer
    - `stored_history_coverage` CommodityCoverage
      - `scope` string, required
      - `requested_start` string, nullable
      - `requested_end` string, nullable
      - `available_start` string, nullable
      - `available_end` string, nullable
      - `input_row_count` integer, required
      - `row_count` integer, required
      - `distinct_date_count` integer, required
      - `duplicate_date_row_count` integer, required
      - `excluded_weekend_row_count` integer, required
      - `invalid_date_row_count` integer, required
      - `expected_weekday_label_count` integer, required
      - `missing_weekday_label_count` integer, required
      - `largest_missing_weekday_run` integer, required
      - `largest_calendar_gap_days` integer, required
      - `missing_weekday_ranges` CommodityMissingWeekdayRange[], required
        - `start_date` string, required
        - `end_date` string, required
        - `weekday_count` integer, required
      - `longest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `latest_continuous_weekday_segment` CommodityCoverageSegment, required
        - `start_date` string, nullable
        - `end_date` string, nullable
        - `row_count` integer, required
      - `sparse_history` boolean, required
      - `coverage_basis` string, required
      - `continuous_coverage_verified` boolean
      - `reference_only` boolean
      - `executable_quotes` boolean
      - `provenance_version` integer, required
      - `repaired_excluded_weekend_row_count` integer
      - `repaired_invalid_date_row_count` integer
    - `point_in_time_basis` string, nullable
    - `is_official` boolean, required
    - `is_proxy` boolean, required
    - `is_fallback` boolean, required
    - `is_stale` boolean, required
    - `has_announcement_datetime` boolean, required
    - `point_in_time_safe` boolean, required: Whether the returned values have verified availability and vintage evidence; estimated release times do not qualify.
    - `unverified_vintage_count` integer
    - `unknown_publication_time_count` integer
    - `latest_available_date` string, nullable
    - `last_updated` string, nullable
    - `data_lag_days` integer, nullable
    - `source_name` string, nullable
    - `source_type` 'official' | 'public' | 'fallback' | 'derived', required
    - `is_derived` boolean
    - `row_count` integer
    - `announcement_datetime_count` integer
    - `missing_announcement_datetime_count` integer
    - `has_assumed_release_times` boolean: True when at least one row in the quality scope carries a publication timestamp derived from the publication lag measured on that series' own confirmed releases, because no official release calendar reaches the period.
    - `assumed_release_time_count` integer: Number of rows in the quality scope whose publication timestamp was derived rather than captured. Compare against row_count to size the derived portion of the requested window.
    - `bounded_release_time_count` integer: Legacy rows carrying an upper-bound estimate flag; this does not certify replay safety.
    - `unbounded_release_time_count` integer: Assumed timestamps without proven availability bounds.
    - `quality_scope` string
    - `stale_after_days` integer, nullable
    - `requested_window_has_data` boolean, nullable
    - `requested_window_latest_date` string, nullable
    - `requested_window_includes_latest_available` boolean, nullable
    - `page_includes_latest_available` boolean, nullable
    - `returned_latest_available_before_window` boolean, nullable
    - `staleness_days` integer, nullable
    - `reason` string, nullable
    - `datetime_field` string, nullable
    - `datetime_precision` string, nullable
    - `datetime_semantics` string, nullable
    - `source_legs` object[], nullable
    - `historical_point_in_time` PointInTimeCompleteness: Coverage of source-confirmed publication timestamps for a dataset.
      - `row_count` integer, required
      - `announcement_datetime_count` integer, required
      - `missing_announcement_datetime_count` integer, required
      - `assumed_release_time_count` integer
      - `bounded_release_time_count` integer
      - `unbounded_release_time_count` integer
      - `unverified_vintage_count` integer
      - `unknown_publication_time_count` integer
      - `point_in_time_safe` boolean, required
  - `data` CalendarReleaseRow[], required
    - `announcement_datetime` integer, required
    - `release` string, required
    - `calendar_event_id` string, nullable
    - `announcement_datetime_utc` string, nullable
    - `announcement_datetime_local` string, nullable
    - `announcement_datetime_requested_timezone` string, nullable
    - `release_date_confirmed` boolean, nullable
    - `release_time_assumed` boolean, nullable
    - `release_time_status` string, nullable
    - `release_date_status` string, nullable
    - `release_time_assumption` string, nullable
    - `time_announced` boolean, nullable: true when the official publisher has announced the exact release time, so announcement_datetime is the scheduled release instant. false when the publisher has announced only the release date (time not announced): announcement_date then holds the publisher's local date, announcement_datetime is 00:00 of that date in the publisher's timezone and is a day marker, not a release time. false is also used for rows with release_time_assumed=true. A row with time_announced=false is replaced by a timed row once an official source publishes the time.
    - `announcement_date` string, nullable: Official release date (YYYY-MM-DD) in the publisher's local timezone. Present when time_announced is false because the publisher has announced the date but not the time.
    - `name` string, nullable
    - `unit` string, nullable: Unit of the corresponding normalized historical series.
    - `value_unit` string, nullable: Unit of the values this release publishes, as served by /v1/announcements/{currency}/{indicator} for the same release (for example Persons, %YoY, Million Barrels). Taken from the series catalogue; omitted when the catalogue declares no unit.
    - `frequency` string, nullable: Observation frequency of the corresponding historical series.
    - `annualization` string, nullable: Declared annualization basis of the historical series, such as SAAR for an annual-rate level.
    - `annualization_source_url` string, nullable: Official source documenting the declared annualization basis; not captured-vintage evidence.
    - `source` string, nullable
    - `source_url` string, nullable
    - `source_release` string, nullable
    - `schedule_url` string, nullable
    - `release_stage` string, nullable
    - `reference_period` string, nullable
    - `dataset_codes` union
      - string
      - string[]
    - `date` string, nullable
    - `domain` string, nullable
    - `data_currency` string, nullable
    - `endpoint_family` string, nullable
    - `endpoint_path` string, nullable
    - `requires_api_key` boolean, nullable
    - `event_importance` string, nullable: high, medium or low. Always consistent with market_tier (1 = high, 2 = medium, 3 = low).
    - `market_tier` integer, nullable: Cross-market importance tier of the release type (1 = policy rates, CPI, GDP, labour market, retail sales; 2 = trade, PPI, surveys; 3 = everything else). A release listed as top tier for the row's own currency is promoted to 1.
    - `top_tier_for_currency` boolean, nullable: True when the release is one of the handful of events that move this currency, from the per-currency list in calendar_top_tier_overrides.json (e.g. dairy exports for NZD, Tankan for JPY, IPCA-15 for BRL). Currencies without a list use market_tier == 1. A global tier-1 release can therefore carry market_tier 1 with top_tier_for_currency false.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/fxmacrodata/apis/fx-macrodata-api.md) · [All operations](https://skmtc.dev/fxmacrodata/apis/fx-macrodata-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fxmacrodata/apis/fx-macrodata-api/revisions/fadaa543b154?raw)