API Reference / Glossary
This page explains the keys returned in MacroSignal API responses.
Event object fields
- actual_value
- Type: number | null — The actual reported value for the series. Null until the release is published.
- category
- Type: string — High-level category for the release (example: "inflation", "labor").
- country
- Type: string — ISO 3166-1 alpha-2 country code for the release (example: "US").
- currency
- Type: string — ISO 4217 currency code most associated with the release (example: "USD").
- event_definition_id
- Type: string — Stable identifier for the economic series or release (example: "us-cpi-yoy").
- event_definition_name
- Type: string — Human-friendly name of the series or release (example: "US CPI YoY").
- event_instance_id
- Type: string — Unique id for a specific release/instance (example: "us-cpi-2026-03-11").
- event_instance_name
- Type: string — Readable name for this particular release (example: "US CPI YoY (Mar 2026)").
- forecast_value
- Type: number | null — The consensus forecast value (if applicable).
- impact_score
- Type: number — Normalized score between 0.0 and 1.0 estimating likely market impact (higher = greater expected impact).
- importance
- Type: string — Importance label (enum: "low", "medium", "high") used for filtering and UI display.
- previous_value
- Type: number | null — The previously reported value for the series (if applicable).
- reference
- Type: string — Human-readable reference period for the release (example: "Mar 2026").
- reference_date
- Type: string (date) — Reference date in ISO 8601 date format: YYYY-MM-DD (example: "2026-03-11").
- source
- Type: string — Primary data source or agency publishing the release (example: "BLS", "BEA").
- status
- Type: string — Status of the instance (enum: "scheduled", "released", "cancelled").
- timestamp
- Type: string (date-time) — ISO 8601 timestamp in UTC or with timezone offset. Format: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS±hh:mm (example: "2026-03-11T08:30:00Z"). This represents when the event occurs or when the release is published.
- timezone
- Type: string — Timezone identifier for the timestamp (prefer IANA tz names, e.g. "America/New_York" — otherwise use "UTC").
- updated_at
- Type: string (date-time) — ISO 8601 timestamp indicating when the event data was last updated in MacroSignal. Format: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS±hh:mm.
If you need more detail about any field or have a suggestion for additional metadata, open an issue or contact support.