API Specification

Unified REST API aggregating freely-available government commodity data

Base URL

https://commodityfundamentals.com/api/v1

Authentication

All endpoints require authentication. Two methods are supported:

Method	Type	Description
BearerAuth	Bearer token	Pass your API key as a Bearer token in the Authorization header.
ApiKeyQuery	Query parameter	Pass your API key as the `api_key` query parameter. Not recommended for production.

Commodities

GET /commodities

Returns a paginated list of all available commodities with their metadata.

Parameters

Parameter	Type	Required	Description
category	string (energy, metals, agriculture, softs)	Optional	Filter by commodity category
search	string	Optional	Search commodities by name or symbol
sort_order	string (asc, desc) [default: asc]	Optional	Sort order for results (default asc)
page	integer [default: 1]	Optional	Page number (default 1)
per_page	integer [default: 25]	Optional	Results per page, max 100 (default 25)

Response

{
  "data": [
    {
      "id": "WTI_CRUDE_OIL",
      "name": "WTI Crude Oil",
      "symbol": "CL",
      "category": "energy",
      "exchange": "NYMEX",
      "unit": "USD/barrel"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 13,
    "total_pages": 1
  }
}

Error Responses

401 Unauthorized 429 Rate limited

GET /commodities/{slug}

Returns detailed information for a single commodity, including all available data series and date ranges.

Parameters

Parameter	Type	Required	Description
slug	string	Required	Commodity identifier (e.g., `WTI_CRUDE_OIL`)

Response

{
  "data": {
    "id": "WTI_CRUDE_OIL",
    "name": "WTI Crude Oil",
    "symbol": "CL",
    "category": "energy",
    "exchange": "NYMEX",
    "unit": "USD/barrel",
    "description": "West Texas Intermediate light sweet crude oil futures contract.",
    "contract_size": "1,000 barrels",
    "tick_size": 0.01,
    "available_series": [
      {
        "type": "price",
        "frequency": "daily",
        "first_date": "1983-03-30",
        "last_date": "2024-06-21"
      },
      {
        "type": "cot_legacy",
        "frequency": "weekly",
        "first_date": "1986-01-15",
        "last_date": "2024-06-18"
      },
      {
        "type": "cot_disaggregated",
        "frequency": "weekly",
        "first_date": "2006-06-13",
        "last_date": "2024-06-18"
      }
    ]
  }
}

Error Responses

401 Unauthorized 404 Not found 429 Rate limited

Time Series

GET /commodities/{slug}/series

Returns historical time series data for a specific commodity and series type.

Parameters

Parameter	Type	Required	Description
slug	string	Required	Commodity identifier (e.g., `WTI_CRUDE_OIL`)
type	string (price, volume, open_interest, production, stocks, yield, planted_acres, harvested_acres, refinery_inputs, ending_stocks)	Required	The type of data series to retrieve
start_date	string	Optional	Start date in ISO 8601 format. Defaults to 1 year ago.
end_date	string	Optional	End date in ISO 8601 format. Defaults to today.
frequency	string (daily, weekly, monthly) [default: daily]	Optional	Data frequency
transform	string (none, change, pct_change, cumulative) [default: none]	Optional	Mathematical transform applied to the data
limit	integer	Optional	Maximum number of data points to return (max 10,000)
sort_order	string (asc, desc) [default: asc]	Optional	Sort order for results (default asc)

Response

{
  "data": [
    {
      "date": "2024-01-05",
      "value": 2044.5,
      "open": 2062.98,
      "high": 2078.4,
      "low": 2024.1,
      "close": 2044.5
    },
    {
      "date": "2024-01-12",
      "value": 2049.7,
      "open": 2046.8,
      "high": 2062.3,
      "low": 2017.3,
      "close": 2049.7
    }
  ],
  "meta": {
    "commodity_id": "GOLD",
    "type": "price",
    "frequency": "weekly",
    "unit": "USD/troy oz",
    "transform": "none",
    "count": 25
  }
}

Error Responses

400 Bad request 401 Unauthorized 404 Not found 429 Rate limited

CFTC

GET /commodities/{slug}/cot

Returns CFTC Commitments of Traders report data for a specific commodity contract.

Parameters

Parameter	Type	Required	Description
slug	string	Required	Commodity identifier (e.g., `WTI_CRUDE_OIL`)
format	string (legacy, disaggregated) [default: legacy]	Optional	Report format
start_date	string	Optional	Start date in ISO 8601 format
end_date	string	Optional	End date in ISO 8601 format
sort_order	string (asc, desc) [default: desc]	Optional	Sort order for results (default desc)
page	integer [default: 1]	Optional	Page number (default 1)
per_page	integer [default: 25]	Optional	Results per page, max 100 (default 25)

Response

{
  "data": [
    {
      "report_date": "2024-06-18",
      "commodity": "WTI_CRUDE_OIL",
      "exchange": "NYMEX",
      "format": "legacy",
      "open_interest": 1823456,
      "commercial": {
        "long": 456789,
        "short": 523456,
        "spreading": 0,
        "net": -66667
      },
      "non_commercial": {
        "long": 634567,
        "short": 234567,
        "spreading": 312345,
        "net": 400000
      },
      "non_reportable": {
        "long": 107755,
        "short": 140088,
        "net": -32333
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 24,
    "total_pages": 1
  }
}

Error Responses

400 Bad request 401 Unauthorized 404 Not found 429 Rate limited

Schemas

Data models used across API responses.

`CommoditySummary`

Field	Type	Description
id *	string	Unique commodity identifier (screaming snake case)
name *	string	WTI Crude Oil
symbol	string	Exchange ticker symbol
category *	string (energy, metals, agriculture, softs)	energy
exchange	string	NYMEX
unit	string	USD/barrel

`CommodityDetail`

Field	Type	Description
id *	string	WTI_CRUDE_OIL
name *	string	WTI Crude Oil
symbol	string	CL
category *	string (energy, metals, agriculture, softs)
exchange	string	NYMEX
unit	string	USD/barrel
description	string	West Texas Intermediate light sweet crude oil futures contract.
contract_size	string	1,000 barrels
tick_size	number	0.01
available_series	object[]

`TimeSeriesPoint`

Field	Type	Description
date *	string	2024-01-05
value *	number	Primary value (close price, or transformed value)
open	number	Opening price (price series only)
high	number	High price (price series only)
low	number	Low price (price series only)
close	number	Closing price (price series only)
volume	integer	Trading volume (price series only)

`SeriesMeta`

Field	Type	Description
commodity_id *	string	GOLD
type *	string (price, volume, open_interest, production, stocks, yield, planted_acres, harvested_acres, refinery_inputs, ending_stocks)
frequency *	string (daily, weekly, monthly)
unit	string	USD/troy oz
transform *	string (none, change, pct_change, cumulative)
count *	integer	Number of data points returned
request_id *	string	Unique request identifier for support and debugging

`CftcReport`

Legacy format includes: commercial, non_commercial, non_reportable. Disaggregated format includes: producer_merchant, swap_dealer, managed_money, other_reportable. Fields for the other format will be absent.

Field	Type	Description
report_date *	string	2024-06-18
commodity *	string	WTI_CRUDE_OIL
exchange	string	NYMEX
format *	string (legacy, disaggregated)
open_interest *	integer	1823456
commercial	PositionGroup
non_commercial	PositionGroupWithSpreading
non_reportable	PositionGroupNet
producer_merchant	PositionGroup
swap_dealer	PositionGroupWithSpreading
managed_money	PositionGroupWithSpreading
other_reportable	PositionGroupWithSpreading

`PositionGroup`

Field	Type	Description
long	integer
short	integer
net	integer	Computed as long minus short

`PositionGroupWithSpreading`

Field	Type	Description
long	integer
short	integer
spreading	integer
net	integer	Computed as long minus short

`PositionGroupNet`

Field	Type	Description
long	integer
short	integer
net	integer	Computed as long minus short

`PaginationMeta`

Field	Type	Description
page *	integer	1
per_page *	integer	25
total *	integer	Total number of records matching the query
total_pages *	integer	6
request_id *	string	Unique request identifier for support and debugging

Download

The raw OpenAPI 3.1.0 specification is available for code generation, testing, and tooling:

Download v1.yaml