Commodities-API Node.js SDK

Official Node.js SDK for Commodities-API – the ultimate API for accessing comprehensive and accurate real-time and historical rates on hundreds of commodities.

Commodities-API supports 850+ symbols with updates as fast as every 60 seconds (depending on your plan). Start a 7‑day free trial and cancel anytime.

Key Features

• Built for developers: Simple, typed API designed for Node.js and TypeScript.
• Robust JSON API: Thin, predictable wrapper over the Commodities-API JSON endpoints.
• Top-tier security: Your API key is sent over HTTPS to trusted, enterprise-grade infrastructure.
• Reliable data sources: Data aggregated from reputable financial and commodity providers.
• Flexible integration: Works in any Node.js app (CommonJS or ESM) and with TypeScript.
• Historical data access: Query historical and time-series data for deeper analysis.
• Exceptional accuracy: Real-time and historical data with high precision.
• User-friendly documentation: See the full API docs at commodities-api.com/documentation.
• Specialized support: Dedicated support team to help with integration and use-cases.

Supported Commodities

Commodities-API covers a wide range of instruments, including:

• Precious metals: Gold (XAU), Silver (XAG), and more.
• Energy: Crude oil benchmarks, gas, and other energy products.
• Agricultural products: Coffee, wheat, sugar, and many others.
• Indexes and more: Various commodity and FX-related symbols.

You can find the full, always up-to-date list of supported symbols in the Supported Commodities section of the official documentation.

Installation

Install the SDK from npm:

npm install @commodities-api/sdk

This package is written in TypeScript and ships with type definitions out of the box.

Getting Started

First, sign up at Commodities-API to get your API key and some free credits.

Basic Usage (TypeScript / ESM)

import { CommoditiesClient } from "@commodities-api/sdk";

const client = new CommoditiesClient("REPLACE-WITH-YOUR-ACCESS-KEY");

async function main() {
  const latest = await client.latest({
    base: "USD",
    symbols: "XAU,XAG"
  });

  console.log(latest);
}

main().catch(err => {
  console.error(err);
  process.exit(1);
});

Basic Usage (CommonJS)

// If your project uses CommonJS, you can import via dynamic import:
(async () => {
  const { CommoditiesClient } = await import("@commodities-api/sdk");

  const client = new CommoditiesClient("REPLACE-WITH-YOUR-ACCESS-KEY");
  const latest = await client.latest({
    base: "USD",
    symbols: "XAU,XAG"
  });

  console.log(latest);
})();

Example Response

Example response for a successful latest request:

{
  "data": {
    "success": true,
    "timestamp": 1715796300,
    "date": "2024-05-15",
    "base": "USD",
    "rates": {
      "RICE": 0.052356020942408,
      "SUGAR": 5.3676865271068,
      "USD": 1,
      "WHEAT": 0.0036618232950551,
      "USDRICE": 19.100000000000136,
      "USDSUGAR": 0.1863000000000006,
      "USDWHEAT": 273.08799999999803
    },
    "unit": {
      "RICE": "per cwt",
      "WHEAT": "per metric ton",
      "SUGAR": "per lb"
    }
  }
}

The exact structure of the data object depends on the endpoint and your plan. Refer to the official documentation for the complete schema.

Available Methods

All methods live on the CommoditiesClient class.

• latest(params?: LatestParams)
  Fetches the most recent rates for the requested symbols.

  await client.latest({
    base: "USD",
    symbols: "RICE,WHEAT,SUGAR"
  });

• historical(params: HistoricalParams)
  Get historical rates for a given date (YYYY-MM-DD).

  await client.historical({
    date: "2024-05-15",
    base: "USD",
    symbols: "RICE,WHEAT,SUGAR"
  });

• timeSeries(params: TimeSeriesParams)
  Retrieve time-series data between two dates.

  await client.timeSeries({
    start_date: "2024-05-01",
    end_date: "2024-05-15",
    base: "USD",
    symbols: "RICE,WHEAT,SUGAR"
  });

• fluctuation(params: FluctuationParams)
  Get day-to-day or period fluctuation data.

  await client.fluctuation({
    start_date: "2024-05-01",
    end_date: "2024-05-15",
    base: "USD",
    symbols: "RICE,WHEAT,SUGAR"
  });

• convert(params: ConvertParams)
  Convert an amount between two symbols.

  await client.convert({
    from: "USD",
    to: "XAU",
    amount: 100
  });

• symbols()
  List available symbols and their metadata (depends on plan).

  await client.symbols();

• seasonality(params: SeasonalityParams)
  Retrieve seasonality metrics for a given symbol.

  await client.seasonality({
    symbol: "WHEAT",
    group_by: "month",
    base: "USD",
    years: 5
  });

Types like LatestParams, HistoricalParams, TimeSeriesParams, etc. are exported from the SDK for strong typing in TypeScript projects.

Error Handling

All requests may throw a CommoditiesApiError when:

• The API returns an error payload, or
• The network fails, or
• The response is not valid JSON.

import { CommoditiesClient, CommoditiesApiError } from "@commodities-api/sdk";

const client = new CommoditiesClient("REPLACE-WITH-YOUR-ACCESS-KEY");

async function main() {
  try {
    const latest = await client.latest({ base: "USD", symbols: "XAU,XAG" });
    console.log(latest);
  } catch (err) {
    if (err instanceof CommoditiesApiError) {
      console.error("Status code:", err.statusCode);
      console.error("Error code:", err.errorCode);
      console.error("Message:", err.message);
    } else {
      console.error("Unexpected error:", err);
    }
  }
}

main().catch(console.error);

Documentation & Support

• API documentation: https://commodities-api.com/documentation
• Website: https://commodities-api.com

If you have questions or need help with integration, please reach out through the official support channels listed in the Commodities-API dashboard.