openapi: 3.2.0
info:
  title: FX Macrodata Factors 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: Factors
paths:
  /v1/factors/{currency}/{factor}:
    get:
      tags:
      - Factors
      summary: Get a precomputed FX factor for one currency
      description: 'Returns a factor series for one explicit currency and one explicit factor. Factor values are precomputed snapshots; component macro indicators are not recalculated per request.


        **Path Parameters:**

        - `currency`: Three-letter currency code, for example `EUR` or `USD`.

        - `factor`: Factor slug. Currently supported: `monetary_stance`.


        **Query Parameters:**

        - `start_date` / `end_date`: Optional date window. With no dates, the latest snapshot is returned.

        - `include_components`: Include component scores and input values.

        - `include_sources`: Include FXMacroData source endpoint URLs.


        Use `/v1/data_catalogue/{currency}?include_capabilities=true` for factor discovery metadata.


        **Authentication:** USD factor data is public without an API key. Anonymous requests are subject to a 100 requests/day per-IP fair-use limit. Other currencies require an Individual or Business API key sent in the `X-API-Key` header.'
      operationId: get_currency_factor_v1_factors__currency___factor__get
      parameters:
      - name: currency
        in: path
        required: true
        schema:
          type: string
          title: Currency
          enum:
          - AUD
          - CAD
          - CHF
          - EUR
          - GBP
          - JPY
          - NZD
          - USD
          example: AUD
        description: 'Required path parameter. Allowed values: AUD, CAD, CHF, EUR, GBP, JPY, NZD, USD.'
      - name: factor
        in: path
        required: true
        schema:
          type: string
          description: Factor slug, for example monetary_stance.
          examples:
          - monetary_stance
          title: Factor
          enum:
          - monetary_stance
          example: monetary_stance
        description: 'Required path parameter. Factor slug, for example monetary_stance. Allowed values: monetary_stance.'
      - name: start_date
        in: query
        required: false
        schema:
          type: string
          description: Inclusive start date YYYY-MM-DD. With no dates, returns latest only.
          examples:
          - '2026-01-01'
          title: Start Date
        description: Optional query parameter. Inclusive start date YYYY-MM-DD. With no dates, returns latest only.
      - name: end_date
        in: query
        required: false
        schema:
          type: string
          description: Inclusive end date YYYY-MM-DD. Defaults to today when start_date is supplied.
          examples:
          - '2026-07-19'
          title: End Date
        description: Optional query parameter. Inclusive end date YYYY-MM-DD. Defaults to today when start_date is supplied.
      - name: include_components
        in: query
        required: false
        schema:
          type: boolean
          description: Include component scores and source observations.
          default: false
          title: Include Components
        description: Optional query parameter. Include component scores and source observations.
      - name: include_sources
        in: query
        required: false
        schema:
          type: boolean
          description: Include FXMacroData source endpoint URLs.
          default: false
          title: Include Sources
        description: Optional query parameter. Include FXMacroData source endpoint URLs.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum rows to return. Defaults to 20. Maximum 100.
          default: 20
          title: Limit
        description: Optional query parameter. Maximum rows to return. Defaults to 20. Maximum 100.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of rows to skip after most-recent-first ordering.
          default: 0
          title: Offset
        description: Optional query parameter. Number of rows to skip after most-recent-first ordering.
      - name: api_key
        in: query
        required: false
        schema:
          type: string
          description: Your Individual or Business API key
          title: Api Key
        description: '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.'
        deprecated: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FactorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-parameter-availability:
        currency:
        - AUD
        - CAD
        - CHF
        - EUR
        - GBP
        - JPY
        - NZD
        - USD
        factor:
        - monetary_stance
components:
  schemas:
    CommodityCoverageSegment:
      properties:
        start_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Start Date
        end_date:
          anyOf:
          - type: string
          - type: 'null'
          title: End Date
        row_count:
          type: integer
          title: Row Count
      type: object
      required:
      - row_count
      title: CommodityCoverageSegment
    PointInTimeCompleteness:
      properties:
        row_count:
          type: integer
          title: Row Count
        announcement_datetime_count:
          type: integer
          title: Announcement Datetime Count
        missing_announcement_datetime_count:
          type: integer
          title: Missing Announcement Datetime Count
        assumed_release_time_count:
          type: integer
          title: Assumed Release Time Count
          default: 0
        bounded_release_time_count:
          type: integer
          title: Bounded Release Time Count
          default: 0
        unbounded_release_time_count:
          type: integer
          title: Unbounded Release Time Count
          default: 0
        unverified_vintage_count:
          type: integer
          title: Unverified Vintage Count
          default: 0
        unknown_publication_time_count:
          type: integer
          title: Unknown Publication Time Count
          default: 0
        point_in_time_safe:
          type: boolean
          title: Point In Time Safe
      type: object
      required:
      - row_count
      - announcement_datetime_count
      - missing_announcement_datetime_count
      - point_in_time_safe
      title: PointInTimeCompleteness
      description: Coverage of source-confirmed publication timestamps for a dataset.
    CommodityMissingWeekdayRange:
      properties:
        start_date:
          type: string
          title: Start Date
        end_date:
          type: string
          title: End Date
        weekday_count:
          type: integer
          title: Weekday Count
      type: object
      required:
      - start_date
      - end_date
      - weekday_count
      title: CommodityMissingWeekdayRange
    DataQuality:
      properties:
        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
        source_permission_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Permission Status
        commodity_coverage:
          anyOf:
          - $ref: '#/components/schemas/CommodityCoverage'
          - type: 'null'
        stored_history_coverage:
          anyOf:
          - $ref: '#/components/schemas/CommodityCoverage'
          - type: 'null'
        point_in_time_basis:
          anyOf:
          - type: string
          - type: 'null'
          title: Point In Time Basis
        is_official:
          type: boolean
          title: Is Official
        is_proxy:
          type: boolean
          title: Is Proxy
        is_fallback:
          type: boolean
          title: Is Fallback
        is_stale:
          type: boolean
          title: Is Stale
        has_announcement_datetime:
          type: boolean
          title: Has Announcement Datetime
        point_in_time_safe:
          type: boolean
          title: Point In Time Safe
          description: Whether the returned values have verified availability and vintage evidence; estimated release times do not qualify.
        unverified_vintage_count:
          type: integer
          title: Unverified Vintage Count
          default: 0
        unknown_publication_time_count:
          type: integer
          title: Unknown Publication Time Count
          default: 0
        latest_available_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Available Date
        last_updated:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Updated
        data_lag_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Data Lag Days
        source_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Name
        source_type:
          type: string
          enum:
          - official
          - public
          - fallback
          - derived
          title: Source Type
        is_derived:
          type: boolean
          title: Is Derived
          default: false
        row_count:
          type: integer
          title: Row Count
          default: 0
        announcement_datetime_count:
          type: integer
          title: Announcement Datetime Count
          default: 0
        missing_announcement_datetime_count:
          type: integer
          title: Missing Announcement Datetime Count
          default: 0
        has_assumed_release_times:
          type: boolean
          title: Has Assumed Release Times
          description: 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.
          default: false
        assumed_release_time_count:
          type: integer
          title: Assumed Release Time Count
          description: 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.
          default: 0
        bounded_release_time_count:
          type: integer
          title: Bounded Release Time Count
          description: Legacy rows carrying an upper-bound estimate flag; this does not certify replay safety.
          default: 0
        unbounded_release_time_count:
          type: integer
          title: Unbounded Release Time Count
          description: Assumed timestamps without proven availability bounds.
          default: 0
        quality_scope:
          type: string
          title: Quality Scope
          default: full_result
        stale_after_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Stale After Days
        requested_window_has_data:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Requested Window Has Data
        requested_window_latest_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Requested Window Latest Date
        requested_window_includes_latest_available:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Requested Window Includes Latest Available
        page_includes_latest_available:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Page Includes Latest Available
        returned_latest_available_before_window:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Returned Latest Available Before Window
        staleness_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Staleness Days
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        datetime_field:
          anyOf:
          - type: string
          - type: 'null'
          title: Datetime Field
        datetime_precision:
          anyOf:
          - type: string
          - type: 'null'
          title: Datetime Precision
        datetime_semantics:
          anyOf:
          - type: string
          - type: 'null'
          title: Datetime Semantics
        source_legs:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Source Legs
        historical_point_in_time:
          anyOf:
          - $ref: '#/components/schemas/PointInTimeCompleteness'
          - type: 'null'
      type: object
      required:
      - is_official
      - is_proxy
      - is_fallback
      - is_stale
      - has_announcement_datetime
      - point_in_time_safe
      - source_type
      title: DataQuality
    FactorDataPoint:
      properties:
        date:
          type: string
          title: Date
        val:
          anyOf:
          - type: number
          - type: 'null'
          title: Val
        score:
          anyOf:
          - type: number
          - type: 'null'
          title: Score
        level_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Level Score
        impulse_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Impulse Score
        rate_repricing_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Rate Repricing Score
        macro_pressure_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Macro Pressure Score
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        stance_context:
          anyOf:
          - type: string
          - type: 'null'
          title: Stance Context
        announcement_datetime:
          anyOf:
          - type: integer
          - type: 'null'
          title: Announcement Datetime
        coverage_ratio:
          anyOf:
          - type: number
          - type: 'null'
          title: Coverage Ratio
        component_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Component Count
        point_in_time_safe:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Point In Time Safe
          description: True only when every input observation behind this row carries a publication timestamp captured from its release. An input dated from that series' measured publication lag clears it, because the composite could not be shown to have been knowable at its own announcement_datetime.
        release_time_assumed:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Release Time Assumed
          description: Present and true when at least one input observation carries a derived publication timestamp. Omitted when every input was captured from its release.
        assumed_release_time_inputs:
          anyOf:
          - type: integer
          - type: 'null'
          title: Assumed Release Time Inputs
          description: Number of input observations behind this row whose publication timestamp was derived.
        components:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Components
        source_observations:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Source Observations
        source_endpoints:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Source Endpoints
      additionalProperties: true
      type: object
      required:
      - date
      title: FactorDataPoint
    FactorResponse:
      properties:
        currency:
          type: string
          title: Currency
        factor:
          type: string
          title: Factor
        methodology:
          type: string
          title: Methodology
        as_of:
          anyOf:
          - type: string
          - type: 'null'
          title: As Of
        score:
          anyOf:
          - type: number
          - type: 'null'
          title: Score
        level_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Level Score
        impulse_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Impulse Score
        rate_repricing_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Rate Repricing Score
        macro_pressure_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Macro Pressure Score
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        stance_context:
          anyOf:
          - type: string
          - type: 'null'
          title: Stance Context
        latest_available_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Available Date
        last_updated:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Updated
        start_date:
          type: string
          title: Start Date
        end_date:
          type: string
          title: End Date
        data_quality:
          $ref: '#/components/schemas/DataQuality'
        pagination:
          properties:
            limit:
              anyOf:
              - type: integer
              - type: 'null'
              title: Limit
            offset:
              anyOf:
              - type: integer
              - type: 'null'
              title: Offset
            returned_count:
              anyOf:
              - type: integer
              - type: 'null'
              title: Returned Count
            total_count:
              anyOf:
              - type: integer
              - type: 'null'
              title: Total Count
            has_more:
              anyOf:
              - type: boolean
              - type: 'null'
              title: Has More
            next_offset:
              anyOf:
              - type: integer
              - type: 'null'
              title: Next Offset
            page_includes_latest_available:
              anyOf:
              - type: boolean
              - type: 'null'
              title: Page Includes Latest Available
          type: object
          title: Pagination
          description: Offset pagination state for one page of results.
        data:
          items:
            $ref: '#/components/schemas/FactorDataPoint'
          type: array
          title: Data
      type: object
      required:
      - currency
      - factor
      - methodology
      - start_date
      - end_date
      - data_quality
      - pagination
      - data
      title: FactorResponse
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CommodityCoverage:
      properties:
        scope:
          type: string
          title: Scope
        requested_start:
          anyOf:
          - type: string
          - type: 'null'
          title: Requested Start
        requested_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Requested End
        available_start:
          anyOf:
          - type: string
          - type: 'null'
          title: Available Start
        available_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Available End
        input_row_count:
          type: integer
          title: Input Row Count
        row_count:
          type: integer
          title: Row Count
        distinct_date_count:
          type: integer
          title: Distinct Date Count
        duplicate_date_row_count:
          type: integer
          title: Duplicate Date Row Count
        excluded_weekend_row_count:
          type: integer
          title: Excluded Weekend Row Count
        invalid_date_row_count:
          type: integer
          title: Invalid Date Row Count
        expected_weekday_label_count:
          type: integer
          title: Expected Weekday Label Count
        missing_weekday_label_count:
          type: integer
          title: Missing Weekday Label Count
        largest_missing_weekday_run:
          type: integer
          title: Largest Missing Weekday Run
        largest_calendar_gap_days:
          type: integer
          title: Largest Calendar Gap Days
        missing_weekday_ranges:
          items:
            $ref: '#/components/schemas/CommodityMissingWeekdayRange'
          type: array
          title: Missing Weekday Ranges
        longest_continuous_weekday_segment:
          $ref: '#/components/schemas/CommodityCoverageSegment'
        latest_continuous_weekday_segment:
          $ref: '#/components/schemas/CommodityCoverageSegment'
        sparse_history:
          type: boolean
          title: Sparse History
        coverage_basis:
          type: string
          title: Coverage Basis
        continuous_coverage_verified:
          type: boolean
          title: Continuous Coverage Verified
          default: false
        reference_only:
          type: boolean
          title: Reference Only
          default: true
        executable_quotes:
          type: boolean
          title: Executable Quotes
          default: false
        provenance_version:
          type: integer
          title: Provenance Version
        repaired_excluded_weekend_row_count:
          type: integer
          title: Repaired Excluded Weekend Row Count
          default: 0
        repaired_invalid_date_row_count:
          type: integer
          title: Repaired Invalid Date Row Count
          default: 0
      type: object
      required:
      - scope
      - input_row_count
      - row_count
      - distinct_date_count
      - duplicate_date_row_count
      - excluded_weekend_row_count
      - invalid_date_row_count
      - expected_weekday_label_count
      - missing_weekday_label_count
      - largest_missing_weekday_run
      - largest_calendar_gap_days
      - missing_weekday_ranges
      - longest_continuous_weekday_segment
      - latest_continuous_weekday_segment
      - sparse_history
      - coverage_basis
      - provenance_version
      title: CommodityCoverage
  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.'