What is the value?
date is the period, val the value in the normalised unit, original_val and original_unit the publisher's own print. previous_value and change_from_previous compare it with the row before.
Data contract
Response fields
Every field you can meet on an announcement row, in its revisions and release timing, and in the envelope around it, defined in one line each. The definitions follow the production OpenAPI schema; the announcements endpoint page explains how the series are built, and point-in-time backtesting shows the fields in use.
How to read a row
Three questions decide how a row can be used.
When did it become public?
announcement_datetime is the publication instant, and publication_time_status says what kind of evidence stands behind it. release_timing bounds the publication and shows when the value was readable through the API.
Which vintage is it?
vintage_status, is_first_release and revisions[] tell first prints from revisions. With as_of, availability picks the clock and data_quality.point_in_time_safe says whether the whole response is replay-safe.
Announcement row
Each element of data[] on /v1/announcements/{currency}/{indicator}, /v1/latest/announcements/... and /v1/recent/announcements/... is one published observation. Fields are omitted when they do not apply to the row, so read them as optional unless marked required.
| Field | Type | Definition |
|---|---|---|
| date | string, required | Reference period of the observation as YYYY-MM-DD. |
| val | number or null | Value in the normalised unit named by the response metadata; null when the publisher released a placeholder. |
| original_val | number | Value exactly as the publisher printed it, before unit normalisation. Present when it differs from val. |
| original_unit | string | Publisher's unit for original_val. |
| announcement_id | string | Stable identifier of this release row. |
| observation_id | string | Identifier of the observation (period) this row describes, shared across its vintages. |
| source | string | Name of the official publisher the value was read from. |
| source_url | string | URL the value was read from. |
| source_url_scope | release | dataset | series | What source_url points at: the specific release document, the dataset it belongs to, or the series landing page. |
| announcement_source_url | string | Release-scoped citation such as the publisher's news-release page for this period. Present only when a release-level URL exists; dataset and landing-page URLs stay in source_url. |
| source_artifact_sha256 | string | SHA-256 digest of the source document the value was read from, for independent verification. |
| previous_value | number | Value of the preceding row in the series. |
| previous_date | string | Reference period of the preceding row. |
| previous_announcement_datetime | integer | Publication time of the preceding row, Unix epoch seconds (UTC). |
| change | number | Headline movement the publisher itself reports, on series where the official print is a change (for example non-farm payrolls). Absent elsewhere. |
| change_from_previous | number | val minus previous_value, computed by FXMacroData. Omitted on series whose publisher supplies the headline change. |
| pct_change_from_previous | number | Percentage difference between val and previous_value. |
| pct_change_yoy, pct_change_qoq, pct_change_mom, pct_change_12m, pct_change, val_mom | number | Derived percentage changes over the named horizon. Present when the series supports that transform; the frequency query parameter selects which one becomes val. |
| announcement_datetime | integer or null | When the value was published, Unix epoch seconds (UTC). Null when publication_time_status is unknown; what the number means is stated by publication_time_status. |
| announcement_datetime_local | string | The same instant written in the publisher's local time zone. |
| publication_time_status | string | What announcement_datetime actually is: confirmed, unverified, assumed_historical or unknown. See the values below. Gate point-in-time work on this per row. |
| publication_time_precision | minute | day | unknown | Resolution of announcement_datetime: minute when the publisher gave a clock time, day when only the release date was sourced. |
| publication_time_basis | string | Where an unverified time came from. official_schedule means the publisher's own calendar listed the release at this time. Absent on confirmed rows. |
| release_time_assumed | boolean | True when announcement_datetime was derived from the publication lag measured on this series' confirmed releases. Only permitted where both the period and the estimated publication precede 2025-11-06. |
| release_time_upper_bound | boolean | Legacy estimate flag kept for older rows; it does not establish point-in-time safety. |
| publication_at_ns, publication_at_ns_string | integer, string | Publication instant stated by the publisher, Unix epoch nanoseconds (UTC), and the same value as a decimal string. Present only when the source states one. |
| observed_at_ns, observed_at_ns_string | integer, string | When FXMacroData observed this value at the source, Unix epoch nanoseconds (UTC). |
| collected_at_ns, collected_at_ns_string, collected_at_iso | integer, string, string | When FXMacroData first captured this value from the official source, as epoch nanoseconds and ISO 8601. |
| capture_time_basis | string | Which moment the capture time records: fetch_completed (the read that returned the value finished) or first_fresh_fetch_completed (the first read that showed the new period finished). |
| official_planned_release_datetime, official_planned_release_datetime_local | integer, string | Release time scheduled in the publisher's own calendar, as epoch seconds and local time. |
| official_actual_release_datetime, official_actual_release_datetime_local | integer, string | Release time the publisher recorded for the actual publication, where it publishes one. |
| vintage_status | string | source_vintage when the value is a vintage the publisher released; legacy_snapshot when it is a stored snapshot that predates vintage tracking. |
| is_first_release | boolean | True when this value is the first print for the period rather than a revision. |
| selected_vintage_known_at_ns | string | With as_of: the instant the returned vintage became known, Unix epoch nanoseconds, as a decimal string. |
| replay_vintage_verified | boolean | With as_of: true when the returned vintage is proven to have been knowable at that instant under the chosen availability basis. |
| release_timing | object | Scheduled, published, collected and available times for a release captured at release time. Fields below. |
| revisions | array | Every published value recorded for this period, newest last, when the request asks for revisions=all. Entry fields below. |
| revisions_summary | object | count of distinct published values, first and latest value, and revised (true when a later vintage changed the first print). |
| outside_requested_window | boolean | True when the row lies before the requested window and is returned as the latest official observation preceding it. |
| requested_start_date, requested_end_date | string | The window the caller asked for, echoed on an outside-window row. |
| returned_reason | string | Why an outside-window row was returned: latest_official_observation_before_requested_window. |
| staleness_days | integer | Days between the requested start date and the date of the outside-window row returned in its place. |
| geography, period_basis, methodology_id, source_methodology_status, source_period_label_conflict | string, string, string, string, boolean | Series metadata carried on the row: geographic scope, how the period is defined, the methodology identifier, the publisher's methodology status, and whether the publisher labelled the period differently from the stored date. |
| canonical_indicator, raw_indicator, remap_applied, remap_rule_id, remap_segment_id | string, string, boolean, string, string | With series_mode=canonical: the canonical slug the row is served under, the stored slug it came from, and the continuity rule that mapped it. |
release_timing
Present on rows captured at release time from the official source. The publication window is bounded by FXMacroData's own reads of the source; it is not a timestamp supplied by the publisher. All times are ISO 8601 UTC.
| Field | Type | Definition |
|---|---|---|
| scheduled_at | string or null | Official scheduled release time. Latency is never measured from this time. |
| published_at | string or null | When the official source actually published the value: the first read of the source that showed this period, microsecond precision. Same instant as published_by. |
| available_at | string or null | When the value was committed to the FXMacroData store and readable through the API, microsecond precision. Null on rows captured before this time was recorded. |
| latency_ms | number or null | Milliseconds from publication to available_at, measured from published_after so it is the longest the gap can have been. Never measured from the scheduled time. |
| publication_delay_ms | number or null | Milliseconds from scheduled_at to published_at: how long after the scheduled time the source published (negative when early). |
| published_after | string or null | The source still showed the previous period after this instant, or its Last-Modified header placed the update after it. Null when no such read was made. |
| published_by | string or null | The first read of the source that showed this period completed at this instant, so the release was public by then. Null when the window could not be bounded. |
| publication_window_basis | string or null | How the window was bounded: poll_bracket (a read showing the previous period, then one showing this period), last_modified (the source's Last-Modified header sets the lower bound) or first_new_period_read_only (only the upper bound is known). |
| collected_at | string or null | When FXMacroData first captured this value from the source. Same instant as collected_at_iso. |
| pickup_ms_min | number or null | Milliseconds from published_by to available_at: the shortest time the value can have taken to become available after publication. |
| pickup_ms_max | number or null | Milliseconds from published_after to available_at: the value was available through the API within this long of publication. Null when no read showed the previous period still in place. |
revisions[] entry
One published value for the period, identified by its release epoch. val is null when the publisher released a placeholder for that vintage.
| Field | Type | Definition |
|---|---|---|
| epoch | integer | Publication time of this vintage, Unix epoch seconds (UTC). |
| val | number or null | Value published in this vintage. |
| change | number | Difference between this vintage and the one before it. |
| is_first_release | boolean | True for the first print of the period. |
| vintage_status | string | source_vintage or legacy_snapshot, as on the row. |
| publication_time_status, publication_time_precision | string | Evidence class and resolution of epoch, with the same values as on the row. |
| publication_at_ns, publication_at_ns_string | integer, string | Publisher-stated publication instant in epoch nanoseconds, when the source states one. |
| observed_at_ns, observed_at_ns_string | integer, string | When FXMacroData observed this vintage at the source. |
| capture_time_basis | string | Which moment the capture time records, as on the row. |
| source_url, announcement_source_url, source_artifact_sha256 | string | Where this vintage was read from and the digest of that document. |
Response envelope
Top-level fields on /v1/announcements/{currency}/{indicator} around data[].
| Field | Type | Definition |
|---|---|---|
| currency, indicator | string | Currency code and indicator slug the response is for. |
| name, value_name | string | Display name of the series and of the value it reports. |
| source, source_url, source_series_id, source_series_name, source_local_name | string | Publisher, its URL, the publisher's own series identifier and name, and the series name in the publisher's language. |
| seasonal_adjustment, price_basis | string | Whether the series is seasonally adjusted, and whether prices are real or nominal, as published. |
| is_proxy, proxy_note | boolean, string | True when the series stands in for a concept the publisher does not release directly, with the note explaining the proxy. |
| provenance | object | Publisher, storage, served_by, timestamp_field and value_field: how the served rows were produced. |
| policy_role, policy_structure, policy_family, comparison_compatible | string, string, array, boolean | For policy-rate series: the role of this rate in the central bank's framework, the structure (single rate, corridor, band), the related rates, and whether it is comparable across currencies. |
| has_official_forecast | boolean, required | True when the publisher releases an official forecast for this series. |
| start_date, end_date | string, required | Window the returned rows cover after window rules and free-tier limits are applied. |
| requested_start_date, requested_end_date, requested_window_has_data, page_includes_latest_available | string, string, boolean, boolean | What the caller asked for, whether any row falls inside it, and whether this page contains the newest available observation. |
| earliest_available_date, latest_available_date | string | First and last observation dates stored for the series. |
| cb_target | object | For inflation series: the central bank's target with its history (effective_from, target, lower, upper, notes). |
| remap, filters, selected_series_id, selected_series | object | Which series variant the request resolved to and the selectors (seasonality, frequency, revisions, annualization, period_aggregation, basis) that chose it. |
| supported_options | object | Selector values this endpoint accepts, keyed by selector name. Unsupported values return unsupported_series_option. |
| data_quality | object, required | Quality summary for the returned rows. Key fields below. |
| replay | object | With as_of: the replay cutoff (as_of, as_of_ns), the availability mode, the dataset_version hash, and per-series evidence. |
| dataset_version | string | Hash of the sources and value settings behind the response. Send it back as dataset_version to be told (409 dataset_version_changed) when a replay would no longer be reproducible. |
| value_mode, value_metadata | string, object | normalized (default) or source; value_metadata states the source unit and whether normalisation was applied. |
| pagination | object, required | limit, offset, returned_count, total_count, has_more, next_offset and page_includes_latest_available. |
| freemium_window | object | Present when free access clamped the window: applied, max_days, cutoff_date and message. |
| freemium_delay | object | Present when free access withheld recent releases: applied, delay_seconds, delay_minutes, cutoff, cutoff_iso, withheld_count, message, subscribe_url, next_available_at and next_available_at_iso. |
| no_data | object | Present on a valid series with no rows in the requested window, explaining why. |
data_quality
Fields most callers gate on. The object carries further counters that follow the same naming.
| Field | Type | Definition |
|---|---|---|
| point_in_time_safe | boolean | Whether the returned values have verified availability and vintage evidence. Estimated release times never qualify. |
| point_in_time_basis | string | With as_of: source_publication when availability=public, value_capture when availability=captured. |
| source_type | official | public | fallback | derived | What kind of source produced the rows. |
| is_official, is_proxy, is_fallback, is_derived | boolean | Source classification flags for the rows returned. |
| is_stale, stale_after_days, data_lag_days | boolean, integer, integer | Whether the newest observation is older than the series' freshness threshold, that threshold, and the publisher's usual lag. |
| source_freshness, source_monitoring_complete, known_source_gap, source_checked_at, source_check_expires_at, latest_published_period | string, boolean, boolean, integer, integer, string | Result of the last check against the publisher: whether a newer period is known to exist upstream and when the check was made. |
| has_announcement_datetime, announcement_datetime_count, missing_announcement_datetime_count, row_count | boolean, integer, integer, integer | How many returned rows carry a publication time. |
| unverified_vintage_count, unknown_publication_time_count | integer | Rows whose vintage or publication time is not evidenced. |
| has_assumed_release_times, assumed_release_time_count, bounded_release_time_count, unbounded_release_time_count | boolean, integer, integer, integer | Rows whose publication time was derived rather than captured, and how many of those carry an availability bound. |
| quality_scope | string | Which rows the summary describes: the requested window, the page, latest, or recent. |
| requested_window_has_data, requested_window_latest_date, returned_latest_available_before_window, staleness_days, reason | boolean, string, boolean, integer, string | Window outcome: whether the window had rows, the newest date inside it, and whether an older row was returned in its place. |
| latest_available_date, last_updated | string | Newest stored observation and when the series was last refreshed. |
| datetime_field, datetime_precision, datetime_semantics | string | Which field carries the row's time, at what resolution, and what that time means. |
publication_time_status values
Present on every row that carries a value. Only confirmed is evidence of when the value became public.
| Value | Meaning |
|---|---|
| confirmed | Read from the publisher's own release: an embargo instant printed on the document, or a publication timestamp the source served with the data. |
| unverified | A real timestamp whose origin this row does not evidence. Most historical rows are in this state. It is not an estimate, and it is not proof. |
| assumed_historical | Derived by FXMacroData from the lag its own confirmed releases show. Only permitted where both the period and the estimated publication precede 2025-11-06; release_time_assumed is true. |
| unknown | No publication time. announcement_datetime is null and the observation is served on its period date alone. |
vintage_status values
States whether a value is a publisher vintage or an older stored snapshot.
| Value | Meaning |
|---|---|
| source_vintage | The value is a vintage the publisher released and FXMacroData captured as such. |
| legacy_snapshot | The value is a stored snapshot from before vintage tracking; it may not be the first print for its period. |
availability values (with as_of)
Chooses which clock decides whether a value was knowable at as_of.
| Value | Meaning |
|---|---|
| public | Default. A value counts as known once the publisher released it; data_quality.point_in_time_basis is source_publication. |
| captured | A value counts as known once FXMacroData had captured it; data_quality.point_in_time_basis is value_capture. |
revisions values
Selects which vintage fills val for each period.
| Value | Meaning |
|---|---|
| latest | Default. The most recent published value for each period. |
| first | The first print for each period. |
| final | The final published value for each period. |
| all | The latest value in val, with every vintage listed under revisions[] and summarised in revisions_summary. |
source_url_scope values
What kind of page source_url is.
| Value | Meaning |
|---|---|
| release | The specific release document for this period. |
| dataset | The dataset or table the value belongs to. |
| series | The publisher's series landing page. |
AI Answer-Ready
Key Facts
- Page
- Response Fields
- Section
- Documentation
- Canonical URL
- https://fxmacrodata.com/documentation/response-fields
- Source
- FXMacroData editorial and official publisher references
- Last Updated
- See page metadata
Provenance And Trust
Cite the canonical URL and source field above. Where available, this page maps to official publisher releases and timestamped updates.
Quick Q&A
What is this page about? This page explains Response Fields with directly usable context for trading, research, and API workflows.
What source should be cited? Use the canonical URL and the listed source field; cite official publisher references when available.
How fresh is this content? The last updated value above reflects the page metadata or latest available data timestamp.
Can this be used in AI assistants? Yes. This section is intentionally structured for retrieval and citation in chat assistants.
Prompt Packs
Use these in ChatGPT, Claude, Gemini, Mistral, Perplexity, or Grok for consistent source-aware outputs.