Frequently Asked Questions

What data sources does the API cover?

The API aggregates data from three U.S. government sources: CFTC (Commitments of Traders positioning data), EIA (Energy Information Administration — crude oil, natural gas, refined products), and USDA (crop production, WASDE forecasts, crop progress). See Data Coverage for the full list of commodities and series.

How often is data updated?

CFTC COT data is updated weekly (Fridays at 3:30pm ET). EIA petroleum data is updated weekly (Wednesdays at 10:30am ET). USDA WASDE reports are released monthly (~12th of the month). Our ingestion lag is under 30 minutes for weekly data. See the Status page for current data freshness.

Do you offer real-time commodity prices?

No — this API is focused on government fundamentals data (inventories, positioning, crop progress), not tick-by-tick prices. If you need real-time price feeds, you'll need a separate market data provider. Fundamentals data complements price data by explaining why prices move.

Can I download data in bulk or CSV format?

The API returns JSON. To get bulk data, paginate through the series endpoint — all historical data is available going back to each source's earliest records (subject to your tier's historical limit). CSV export is not currently supported; JSON is easily converted with pandas or standard library tools.

What's included in the free tier?

The free tier includes 1,000 requests/day, 10 requests/minute, and up to 12 months of historical data. No credit card required. See Rate Limits for full tier comparison.

What's your uptime target?

The API targets 99.9% uptime. Planned maintenance is scheduled for Sundays 2:00–4:00am ET with at least 48 hours notice. Check the Status page for current system health.

How do I authenticate API requests?

Pass your API key in the Authorization header:

curl https://commodityfundamentals.com/api/v1/commodities \
  -H "Authorization: Bearer YOUR_API_KEY"

See Authentication for full details.

Do you offer a Python or R library?

Not yet — a Python SDK is on the roadmap. In the meantime, the API is straightforward to call with requests in Python or httr in R. See the Quick Start for working examples.

What format is data returned in?

All responses are JSON with a consistent envelope: a data array and a meta object with pagination info. Dates are ISO 8601. Numbers are returned as floats with units specified in the series metadata.

How does this compare to scraping government sites directly?

Government sites frequently change formats, go down during shutdowns, and return inconsistent data. This API normalizes data from CFTC, EIA, and USDA into a single consistent schema with predictable update timing, pagination, and error handling — so you don't maintain fragile scrapers.