---
title: "Get commodity indicator data"
method: GET
path: "/v1/commodities/{indicator}"
tags: ["commodities"]
---

# Get commodity indicator data

`GET /v1/commodities/{indicator}`

## Request

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

Returns commodity and energy price observations with source provenance.

**Supported indicators:** `crude_oil_inventories`, `gold`, `natural_gas`, `natural_gas_storage`, `oil_brent`, `oil_wti`, `platinum`, `silver`.

The supported-indicator list above is the complete list of indicators this endpoint serves.

**Precious metals** — official central-bank publications, USD/troy oz.

- **Gold**, **silver**, **platinum** (and **palladium** where listed above): National Bank of Ukraine official accounting prices of banking metals (https://bank.gov.ua/en/markets/exchangerates), converted to USD with the NBU official UAH/USD rate for the same official rate date. `date` is the official rate date and `announcement_date` is the Kyiv business day the NBU set it; no publication clock is asserted. Source: National Bank of Ukraine (https://bank.gov.ua/en/open-data).
- Gold comparisons use the Narodowy Bank Polski calculated gold price (PLN per gram, converted with the same-date NBP USD mid rate). Cross-checks are best effort over the most recent 93 calendar days; where a comparison is available, rows carry `cross_check_divergence_pct`. NBP rows (`source_series_id` starting `NBP:`) are served only for dates the NBU did not supply.
- These are official reference prices, not executable quotes or LBMA auction prices. Weekday-label coverage is included.

**Energy** — sourced from the U.S. Energy Information Administration (https://api.eia.gov/v2/).

- **WTI crude oil** (`oil_wti`): Cushing, OK spot price, USD/barrel.
- **Brent crude oil** (`oil_brent`): Europe spot price, USD/barrel.
- **Natural gas** (`natural_gas`): Henry Hub spot price, USD/MMBtu.

**Query Parameters:**
- `start_date`: Earliest date to include (YYYY-MM-DD). Defaults to 365 days ago.
- `end_date`: Latest date to include (YYYY-MM-DD). Defaults to today.

**Authentication:** A professional API key is required. Supply it via `?api_key=<key>` or the `X-API-Key` header.

## Path parameters

- `indicator` 'crude_oil_inventories' | 'gold' | 'natural_gas' | 'natural_gas_storage' | 'oil_brent' | 'oil_wti' | 'platinum' | 'silver', required: Commodity indicator slug

## Query parameters

- `start_date` string: Start date YYYY-MM-DD
- `end_date` string: End date YYYY-MM-DD
- `limit` integer: Maximum rows to return. Defaults to 20. Maximum 100.
- `offset` integer: Number of rows to skip after most-recent-first ordering.
- `page` integer, nullable: One-based page number. When supplied, it takes precedence over offset.
- `api_key` string: Your Individual or Business API key

## Response `200`

Time-series data for the requested commodity indicator.

- CommodityResponse
  - `currency` string, required
  - `indicator` string, required
  - `source` string, nullable
  - `source_url` string, nullable
  - `provenance` object, required: Publisher and source lineage, shared by the market-data endpoints.
    - `publisher` string, nullable
    - `publisher_url` string, nullable
    - `storage` string, nullable: Data provider label for the served series. Always `FXMacroData`.
    - `source_store` string, nullable: Source series reference, when reported.
    - `served_by` string, nullable: FXMacroData endpoint that serves this series.
    - `timestamp_field` string, nullable
    - `value_field` string, nullable
  - `has_official_forecast` boolean, required
  - `last_updated` string, nullable
  - `latest_available_date` string, 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
  - `start_date` string, required
  - `end_date` string, required
  - `pagination` object, required: Offset pagination state for one page of results.
    - `limit` integer, nullable
    - `offset` integer, nullable
    - `returned_count` integer, nullable
    - `total_count` integer, nullable
    - `has_more` boolean, nullable
    - `next_offset` integer, nullable
    - `page_includes_latest_available` boolean, nullable
  - `data` CommodityDataPoint[], required
    - `source_permission_status` string, nullable
    - `date` string, required
    - `val` number, nullable
    - `announcement_datetime` integer, nullable
    - `source` string, nullable
    - `source_url` string, nullable
    - `source_type` string, nullable
    - `source_chart_timestamp` integer, nullable
    - `source_chart_timestamp_ms` integer, nullable
    - `source_chart_period` string, nullable
    - `quote_time_status` string, nullable
    - `sampling_method` string, nullable
    - `publication_time_status` string, nullable
    - `point_in_time_safe` boolean, nullable
    - `provenance_version` integer, nullable
    - `is_official` boolean, nullable
    - `source_series_id` string, nullable
    - `announcement_date` string, nullable
    - `announcement_timezone` string, nullable
    - `time_announced` boolean, nullable
    - `release_time_status` string, nullable
    - `release_date_status` string, nullable
    - `source_value` number, nullable
    - `source_unit` string, nullable
    - `conversion_rate` number, nullable
    - `conversion_unit` string, nullable
    - `conversion_source` string, nullable
    - `fallback_for_source` string, nullable
    - `cross_check_source` string, nullable
    - `cross_check_series_id` string, nullable
    - `cross_check_val` number, nullable
    - `cross_check_divergence_pct` number, nullable
    - `cross_check_divergent` boolean, nullable
    - `pct_change` number, nullable
    - `pct_change_12m` number, nullable

## Other responses

- `404`: Unsupported commodity indicator.
- `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)