NAV
bash php javascript

Introduction

Welcome to the CommoPrices API Documentation v2.0

Our API allows to get information on prices and values of more than 10,500 commodities and indexes.

Before starting

If you do not know what we do, please visit :

What we provide

We are providing (for the API) three kinds (~structure) of data series.

Two of them are generic :

1/ Regular commodity prices
2/ Index data series

And on other is highly specific :

3/ Trade database for France

Want to use our widget ?

Our widget allows non-experienced developers to integrate a very nice chart on your website.
Please register (or login) and follow our tutorial to install the widget.

Want to test requests ?

We recommend the use of the awesome Postman which will allow you to simulate a HTTP request. You will then be able to generate code for your own programming language (click on Generate Code in the app to do so).

Authentication

To authorize, use this code:

var settings = {
async: true,
crossDomain: true,
url: "api_endpoint_here",
method: "GET",
headers: {
authorization: "Bearer myApiToken",
accept: "application/json"
}
};

$.ajax(settings).done(function(response) {
console.log(response);
});
$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "api_endpoint_here",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"accept: application/json",
"authorization: Bearer myApiToken"
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
curl "api_endpoint_here"
-H "Authorization: Bearer myApiToken"
-H "Accept: application/json"

Make sure to replace myApiToken with your API key.

CommoPrices uses API token to allow access to the API.
You can register a new CommoPrices API token by registering.

CommoPrices expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer myApiToken

0. Retrieve all open and premium dataseries

CommoPrices provides open and premium dataseries.

Get open dataseries

GET https://api.commoprices.com/v2/open

Get all dataseries

GET https://api.commoprices.com/v2/all

1. Regular commodity prices

CommoPrices provides prices from different sources.

GET infos for all commodities

var settings = {
  async: true,
  crossDomain: true,
  url: "https://api.commoprices.com/v2/prices",
  method: "GET",
  headers: {
    authorization: "Bearer myApiToken",
    accept: "application/json"
  }
};

$.ajax(settings).done(function(response) {
  console.log(response);
});
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.commoprices.com/v2/prices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer myApiToken"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl "https://api.commoprices.com/v2/prices"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "meta": {
    "total": 254,
    "per_page": 100,
    "current_page": 2,
    "last_page": 3,
    "from": 101,
    "to": 200,
    "has_more_pages": true
  },
  "data": [
    {
      "type": "price",
      "code": "WRB-ALUMINUM",
      "name": "Aluminum, 99.5% minimum purity, spot, CIF UK ports",
      "original_currency": {
        "name": "US Dollar",
        "code": "USD",
        "symbol": "$",
        "prefix": null,
        "base_code": "USD"
      },
      "original_unit": {
        "name": "metric ton",
        "abbr": "mt",
        "prefix": null,
        "suffix": null,
        "base_abbr": "mt"
      },
      "original_price_unit": {
        "name": "US Dollar per metric ton",
        "abbr": "$ / mt"
      },
      "source": "LME via WRB",
      "oldest_available_date": "2012-01-01",
      "frequency": "M",
      "warning": null,
      "spec": null
    },
    {
      "...": "..."
    },
    {
      "...": "..."
    },
    {
      "type": "price",
      "code": "PBANSOP",
      "name": "Bananas, Central American and Ecuador, FOB U.S. Ports",
      "original_currency": {
        "name": "US Dollar",
        "code": "USD",
        "symbol": "$",
        "prefix": null,
        "base_code": "USD"
      },
      "original_unit": {
        "name": "metric ton",
        "abbr": "mt",
        "prefix": null,
        "suffix": null,
        "base_abbr": "mt"
      },
      "original_price_unit": {
        "name": "US Dollar per metric ton",
        "abbr": "$ / mt"
      },
      "source": "WRB",
      "oldest_available_date": "2012-01-01",
      "frequency": "M",
      "warning": null,
      "spec": null
    }
  ]
}

HTTP Request

GET https://api.commoprices.com/v2/prices

Query Parameters

Parameter Default Description
lang en Define the language of the response
page 1 Pagination of the request

GET info for one commodity

var settings = {
  async: true,
  crossDomain: true,
  url: "https://api.commoprices.com/v2/dataseries/WRB-ALUMINUM",
  method: "GET",
  headers: {
    authorization: "Bearer myApiToken",
    accept: "application/json"
  }
};

$.ajax(settings).done(function(response) {
  console.log(response);
});
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.commoprices.com/v2/dataseries/WRB-ALUMINUM",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer myApiToken"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl "https://api.commoprices.com/v2/dataseries/WRB-ALUMINUM"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": {
    "type": "price",
    "code": "WRB-ALUMINUM",
    "name": "Aluminum, 99.5% minimum purity, spot, CIF UK ports",
    "original_currency": {
      "name": "US Dollar",
      "code": "USD",
      "symbol": "$",
      "prefix": null,
      "base_code": "USD"
    },
    "original_unit": {
      "name": "metric ton",
      "abbr": "mt",
      "prefix": null,
      "suffix": null,
      "base_abbr": "mt"
    },
    "original_price_unit": {
      "name": "US Dollar per metric ton",
      "abbr": "$ / mt"
    },
    "source": "LME via WRB",
    "oldest_available_date": "2012-01-01",
    "frequency": "M",
    "warning": null,
    "spec": null
  }
}

This endpoint retrieves the information concerning a single commodity.

HTTP Request

GET https://api.commoprices.com/v2/dataseries/<code>

URL Parameters

Parameter Description
code The code of the commodity to retrieve

Query Parameters

Parameter Default Description
lang en Define the language of the response

GET data for one commodity

var settings = {
  async: true,
  crossDomain: true,
  url: "https://api.commoprices.com/v2/dataseries/WRB-ALUMINUM/data",
  method: "GET",
  headers: {
    authorization: "Bearer myApiToken",
    accept: "application/json"
  }
};

$.ajax(settings).done(function(response) {
  console.log(response);
});
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.commoprices.com/v2/dataseries/WRB-ALUMINUM/data",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer myApiToken"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl "https://api.commoprices.com/v2/dataseries/WRB-ALUMINUM/data"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "meta": {
    "data_endpoints": {
      "called": 12,
      "quota": 50,
      "remaining": 38
    },
    "current_period": {
      "start": 1522533600,
      "end": 1525125599
    }
  },
  "data": {
    "info": {
      "type": "price",
      "code": "WRB-ALUMINUM",
      "name": "Aluminum, 99.5% minimum purity, spot, CIF UK ports",
      "original_currency": {
        "name": "US Dollar",
        "code": "USD",
        "symbol": "$",
        "prefix": null,
        "base_code": "USD"
      },
      "original_unit": {
        "name": "metric ton",
        "abbr": "mt",
        "prefix": null,
        "suffix": null,
        "base_abbr": "mt"
      },
      "original_price_unit": {
        "name": "US Dollar per metric ton",
        "abbr": "$ / mt"
      },
      "source": "LME via WRB",
      "oldest_available_date": "2012-01-01",
      "frequency": "M",
      "warning": null,
      "spec": null
    },
    "request": {
      "start_date": "2012-01-01",
      "order": "asc",
      "frequency": "M",
      "currency": {
        "name": "US Dollar",
        "code": "USD",
        "symbol": "$",
        "prefix": null,
        "base_code": "USD"
      },
      "unit": {
        "name": "metric ton",
        "abbr": "mt",
        "prefix": null,
        "suffix": null,
        "base_abbr": "mt"
      },
      "price_unit": {
        "name": "US Dollar per metric ton",
        "abbr": "$ / mt"
      },
      "column_names": ["date", "price"],
      "dataseries": [
        ["2012-01-31", 2151],
        ["2012-02-29", 2208],
        ["...", "..."],
        ["...", "..."],
        ["2016-03-31", 1531]
      ]
    }
  }
}

This endpoint retrieves the prices of a single commodity.

HTTP Request

GET https://api.commoprices.com/v2/dataseries/<code>/data

Premium Plan

If you do have a premium plan from CommoPrices API, a meta field will be added between status and success.

However, if you do not have a premium plan, you will not see this meta field appearing.

URL Parameters

Parameter Description
code The code of the commodity to retrieve

Query Parameters

Parameter Default Description
lang en Define the language of the response
currency _data.info.original_currency.code_ Define the currency of the response
start_date _data.info.oldest_available_date_ Define the start date for the response
end_date null Define the last date in the response
unit _data.info.original_unit_
(see query docs for unit)
Define the unit of the response
period data.info.frequency Define the frequency of the response (monthly, quarterly or yearly averaged)

2. Indexes

CommoPrices provides indexes from different sources.

GET infos for all indexes

var settings = {
  async: true,
  crossDomain: true,
  url: "https://api.commoprices.com/v2/indexes",
  method: "GET",
  headers: {
    authorization: "Bearer myApiToken",
    accept: "application/json"
  }
};

$.ajax(settings).done(function(response) {
  console.log(response);
});
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.commoprices.com/v2/indexes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer myApiToken"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl "https://api.commoprices.com/v2/indexes"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:


{
  "status": "success",
  "meta": {
      "total": 97,
      "per_page": 100,
      "current_page": 1,
      "last_page": 1,
      "from": 1,
      "to": 97,
      "has_more_pages": false
  },
  "data": [
    {
      "type": "index",
      "code": "LLO-BDI",
      "name": "Baltic Dry Index | World ",
      "index": {
        "base": null,
        "date_reference": null
      },
      "source": "Lloyds' List",
      "oldest_available_date": "2009-03-16",
      "frequency": "D",
      "warning": null,
      "spec": null
    },
    {
        "...":  "...",
        "...":  "...",
    }
    {
      "type": "index",
      "code": "LLO-BCI",
      "name": "Baltic Capesize Index | ",
      "index": {
        "base": null,
        "date_reference": null
      },
      "source": "Lloyds' List",
      "oldest_available_date": "2009-03-16",
      "frequency": "D",
      "warning": null,
      "spec": null
    },
  ]
}

This endpoint retrieves the information concerning all the indexes available.

HTTP Request

GET https://api.commoprices.com/v2/trades

Query Parameters

Parameter Default Description
lang en Define the language of the response
page 1 Pagination of the request

GET info for one index

var settings = {
  async: true,
  crossDomain: true,
  url: "https://api.commoprices.com/v2/dataseries/LLO-BDI",
  method: "GET",
  headers: {
    authorization: "Bearer myApiToken",
    accept: "application/json"
  }
};

$.ajax(settings).done(function(response) {
  console.log(response);
});
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.commoprices.com/v2/dataseries/LLO-BDI",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer myApiToken"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl "https://api.commoprices.com/v2/dataseries/LLO-BDI"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": {
    "info": {
      "type": "index",
      "code": "LLO-BDI",
      "name": "Baltic Dry Index | World ",
      "index": {
        "base": null,
        "date_reference": null
      },
      "source": "Lloyds' List",
      "oldest_available_date": "2009-03-16",
      "frequency": "D",
      "warning": null,
      "spec": null
    }
  }
}

This endpoint retrieves the information concerning a single index.

HTTP Request

GET https://api.commoprices.com/v2/dataseries/<code>

URL Parameters

Parameter Description
code The code of the index to retrieve

Query Parameters

Parameter Default Description
lang en Define the language of the response

GET data for one index

var settings = {
  async: true,
  crossDomain: true,
  url: "https://api.commoprices.com/v2/dataseries/LLO-BDI/data",
  method: "GET",
  headers: {
    authorization: "Bearer myApiToken",
    accept: "application/json"
  }
};

$.ajax(settings).done(function(response) {
  console.log(response);
});
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.commoprices.com/v2/dataseries/LLO-BDI/data",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer myApiToken"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl "https://api.commoprices.com/v2/dataseries/LLO-BDI/data"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "meta": {
    "data_endpoints": {
      "called": 12,
      "quota": 50,
      "remaining": 38
    },
    "current_period": {
      "start": 1522533600,
      "end": 1525125599
    }
  },
  "data": {
    "info": {
      "type": "index"
      "code": "LLO-BDI",
      "name": "Baltic Dry Index | World ",
      "index": {
        "base": null,
        "date_reference": null
      },
      "source": "Lloyds' List",
      "oldest_available_date": "2009-03-16",
      "frequency": "D",
      "warning": null,
      "spec": null
    },
    "request": {
      "start_date": "2009-03-16",
      "order": "asc",
      "frequency": "D",
      "column_names": ["date", "index"],
      "dataseries": [
        ["2009-03-16", 2058],
        ["2009-03-17", 1974],
        ["...", "..."],
        ["...", "..."],
        ["2016-05-27", 606]
      ]
    }
  }
}

This endpoint retrieves the values of a single index.

HTTP Request

GET https://api.commoprices.com/v2/dataseries/<code>/data

Premium Plan

If you do have a premium plan from CommoPrices API, a meta field will be added between status and success.

However, if you do not have a premium plan, you will not see this meta field appearing.

URL Parameters

Parameter Description
code The code of the commodity to retrieve

Query Parameters

Parameter Default Description
lang en Define the language of the response
start_date _data.info.oldest_available_date_ Define the start date for the response
end_date null Define the last date in the response
period data.infofrequency Define the frequency of the response (monthly, quarterly or yearly averaged)

3. Trade Data (FR)

CommoPrices provides more than 1,600 price dataseries of trade data from France.

GET infos for all commodities

var settings = {
  async: true,
  crossDomain: true,
  url: "https://api.commoprices.com/v2/trades",
  method: "GET",
  headers: {
    authorization: "Bearer myApiToken",
    accept: "application/json"
  }
};

$.ajax(settings).done(function(response) {
  console.log(response);
});
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.commoprices.com/v2/trades",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer myApiToken"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl "https://api.commoprices.com/v2/trades"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "meta": {
    "total": 1834,
    "per_page": 100,
    "current_page": 19,
    "last_page": 19,
    "from": 1801,
    "to": 1834,
    "has_more_pages": false
  },
  "data": [
    {
      "type": "trade",
      "code": "nc8_18010000",
      "name": "Cocoa - beans or broken beans, raw or roasted",
      "original_currency": {
        "name": "Euro",
        "code": "EUR",
        "symbol": "€",
        "prefix": null,
        "base_code": "EUR"
      },
      "original_unit": {
        "name": "metric ton",
        "abbr": "mt",
        "prefix": null,
        "suffix": null,
        "base_abbr": "mt"
      },
      "original_price_unit": {
        "name": "Euro per metric ton",
        "abbr": "€ / mt"
      },
      "source": "Eurostat / CommoPrices [France]",
      "oldest_available_date": "2012-01-01",
      "frequency": "M",
      "warning": null,
      "spec": {
        "flows": {
          "available": ["import", "export"],
          "default": "import"
        },
        "reference_country": "France"
      }
    },
    {
      "...": "...",
      "...": "..."
    },
    {
      "type": "trade",
      "code": "nc8_09011100",
      "name": "Coffee - non-roasted, not decaffeinated",
      "original_currency": {
        "name": "Euro",
        "code": "EUR",
        "symbol": "€",
        "prefix": null,
        "base_code": "EUR"
      },
      "original_unit": {
        "name": "metric ton",
        "abbr": "mt",
        "prefix": null,
        "suffix": null,
        "base_abbr": "mt"
      },
      "original_price_unit": {
        "name": "Euro per metric ton",
        "abbr": "€ / mt"
      },
      "source": "Eurostat / CommoPrices [France]",
      "oldest_available_date": "2012-01-01",
      "frequency": "M",
      "warning": null,
      "spec": {
        "flows": {
          "available": ["import", "export"],
          "default": "import"
        },
        "reference_country": "France"
      }
    }
  ]
}

This endpoint retrieves the information concerning all traded commodities.

HTTP Request

GET https://api.commoprices.com/v2/trades

Query Parameters

Parameter Default Description
lang en Define the language of the response
page 1 Pagination of the request

GET info for one commodity

var settings = {
  async: true,
  crossDomain: true,
  url: "https://api.commoprices.com/v2/dataseries/nc8_12074090",
  method: "GET",
  headers: {
    authorization: "Bearer myApiToken",
    accept: "application/json"
  }
};

$.ajax(settings).done(function(response) {
  console.log(response);
});
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.commoprices.com/v2/dataseries/nc8_12074090",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer myApiToken"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl "https://api.commoprices.com/v2/dataseries/nc8_12074090"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": {
    "info": {
      "type": "trade",
      "code": "nc8_12074090",
      "name": "Sesame - seeds, whether or not broken",
      "original_currency": {
        "name": "Euro",
        "code": "EUR",
        "symbol": "€",
        "prefix": null,
        "base_code": "EUR"
      },
      "original_unit": {
        "name": "metric ton",
        "abbr": "mt",
        "prefix": null,
        "suffix": null,
        "base_abbr": "mt"
      },
      "original_price_unit": {
        "name": "Euro per metric ton",
        "abbr": "€ / mt"
      },
      "source": "Eurostat / CommoPrices [France]",
      "oldest_available_date": "2012-01-01",
      "frequency": "M",
      "warning": null,
      "spec": {
        "flows": {
          "available": ["import", "export"],
          "default": "import"
        },
        "reference_country": "France"
      }
    }
  }
}

This endpoint retrieves the information concerning a single traded commodity.

HTTP Request

GET https://api.commoprices.com/v2/dataseries/<code>

URL Parameters

Parameter Description
code The code of the commodity to retrieve

Query Parameters

Parameter Default Description
lang en Define the language of the response

GET data for one commodity

var settings = {
  async: true,
  crossDomain: true,
  url: "https://api.commoprices.com/v2/dataseries/nc8_12074090/data",
  method: "GET",
  headers: {
    authorization: "Bearer myApiToken",
    accept: "application/json"
  }
};

$.ajax(settings).done(function(response) {
  console.log(response);
});
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.commoprices.com/v2/dataseries/nc8_12074090/data",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Bearer myApiToken"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl "https://api.commoprices.com/v2/dataseries/nc8_12074090/data"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "meta": {
    "data_endpoints": {
      "called": 12,
      "quota": 50,
      "remaining": 38
    },
    "current_period": {
      "start": 1522533600,
      "end": 1525125599
    }
  },
  "data": {
    "info": {
      "type": "trade",
      "code": "nc8_12074090",
      "name": "Sesame - seeds, whether or not broken",
      "original_currency": {
        "name": "Euro",
        "code": "EUR",
        "symbol": "€",
        "prefix": null,
        "base_code": "EUR"
      },
      "original_unit": {
        "name": "metric ton",
        "abbr": "mt",
        "prefix": null,
        "suffix": null,
        "base_abbr": "mt"
      },
      "original_price_unit": {
        "name": "Euro per metric ton",
        "abbr": "€ / mt"
      },
      "source": "Eurostat / CommoPrices [France]",
      "oldest_available_date": "2012-01-01",
      "frequency": "M",
      "warning": null,
      "spec": {
        "flows": {
          "available": [
            "import",
            "export"
          ],
          "default": "import"
        },
        "reference_country": "France"
      }
    },
    "request": {
      "start_date": "2012-01-01",
      "order": "asc",
      "frequency": "M",
      "country": "Global",
      "currency": {
        "name": "Euro",
        "code": "EUR",
        "symbol": "€",
        "prefix": null,
        "base_code": "EUR"
      },
      "unit": {
        "name": "metric ton",
        "abbr": "mt",
        "prefix": null,
        "suffix": null,
        "base_abbr": "mt"
      },
      "price_unit": {
        "name": "Euro per metric ton",
        "abbr": "€ / mt"
      },
      "flow": "import",
      "major_countries": [
        "IN": "India",
        "ML": "Mali",
        "NL": "The Netherlands",
        "BE": "Belgium",
        "PY": "Paraguay",
        "GT": "Guatemala",
        "DE": "Germany",
        "ET": "Ethiopia",
        "GB": "United Kingdom"
      ],
      "column_names": [
        "date",
        "price",
        "volume"
      ],
      "dataseries": [
        "Global": [
          [
            "2012-01-31",
            1404,
            615.1
          ],
          [
            "2012-02-29",
            1416,
            763.5
          ],
          [
            "...",
            "...",
            "..."
          ],
          [
            "2016-02-29",
            1608,
            868.3
          ]
        ],
        "IN": [
          [
            "2012-01-31",
            1404,
            615.1
          ],
          [
            "2012-02-29",
            1416,
            763.5
          ],
          [
            "...",
            "...",
            "..."
          ],
          [
            "2016-02-29",
            1608,
            868.3
          ]
        ],
        [
          "...."
        ],
        "GB": [
          [
            "2012-01-31",
            1404,
            615.1
          ],
          [
            "2012-02-29",
            1416,
            763.5
          ],
          [
            "...",
            "...",
            "..."
          ],
          [
            "2016-02-29",
            1608,
            868.3
          ]
        ],
      ]
    }
  }
}

This endpoint retrieves the prices and volumes of a single commodity.

HTTP Request

GET https://api.commoprices.com/v2/dataseries/<code>/data

Premium Plan

If you do have a premium plan from CommoPrices API, a meta field will be added between status and success.

However, if you do not have a premium plan, you will not see this meta field appearing.

URL Parameters

Parameter Description
code The code of the commodity to retrieve

Query Parameters

Parameter Default Description
lang en Define the language of the response
currency _data.info.original_currency.code_ Define the currency of the response
start_date _data.info.oldest_available_date_ Define the start date for the response
end_date null Define the last date in the response
unit _data.info.original_unit_
(see query docs for unit)
Define the unit of the response
period data.info.frequency Define the frequency of the response (monthly, quarterly or yearly averaged)

Specific parameters for Customs Trade Data

Parameter Default Description
flow data.info.spec.flows.default Define the flow of the trade data you want to analyze. Possible values : import or export
country global Define the country of the trade data you want to analyze.
Use : 2-letters code in _data.request.major_countries_.
Nota : By default, we are displaying “Global” which is a weighted average of the major countries.

Query parameters

To add a query parameter to your query, you just need to append it to the endpoint.

Check this example :
https://api.commoprices.com/v2/wrb/WRB-ALUMINIUM/data?lang=fr&start_date=2017-01-01&currency=GBP

Languages

Only two languages are available at the moment :

Name Code
English en
French fr

Dates

All the dates have the following format : YYYY-MM-DD.

Start Date

Set the start date for the query.

By default, the start_date is set to the oldest_available_date.

End Date

Set the end date for the query.

By default, the end_date is set to the latest_available_date.

Period

Period parameter allows to request the dataseries in a different format.

For instance, if the original frequency of the commodity is M (monthly), you can query the request to get data averaged quarter Q, semester S or yearly Y, but not day D nor week W.

Period Code
Day D
Week W
Month M
Quarter Q
Semester S
Year Y

Currencies

Here are the currencies availalbles to get the commodities priced in your currency :

Name Symbol Code
Euro EUR
US Dollar $ USD
Australian dollar AU$ AUD
Bulgarian lev лв BGN
Brazilian real R$ BRL
Canadian dollar $CA CAD
Swiss franc CHF CHF
Chinese yuan renminbi ¥ CNY
Czech koruna CZK
Danish krone kr DKK
UK pound sterling £ GBP
Hong Kong dollar HK$ HKD
Croatian kuna kn HRK
Hungarian forint Ft HUF
Indonesian rupiah Rp IDR
Israeli shekel ILS ILS
Indian rupee INR INR
Japanese yen ¥ JPY
Korean won (Republic) KRW
Mexican peso MXN MXN
Malaysian ringgit RM MYR
Norwegian krone kr NOK
New Zealand dollar NZD NZD
Philippine peso PHP
Polish zloty PLN
Romanian leu lei RON
Russian rouble руб RUB
Swedish krona kr SEK
Singapore dollar SGD SGD
Thai baht ฿ THB
Turkish lira TRY TRY
South African rand R ZAR

Units

We have different types of units for our API.

You first need to understand that our commodities have different units. Some are in metric tons, some in litre or MMBTU or even hour.
And you cannot compare metric tons with hours for instance, so you need to understand before making the query what is type is the unit of the commodity you are working on.

Following are all the different types :

Volume

Unit Ratio to Reference Unit code
Barrel 0.1589870 1
Litre 0.001 5
Cubic meter 1 (this is the reference unit) 7
Bushel US 0.0352391 12
gallon US 0.0037854 14

Weight

Unit Ratio to Reference Unit code
Carat 0.0002 2
Gram 0.001 3
Kilogram 1 (this is the reference unit) 4
Metric ton 1000 10
Pound 0.4535923 11
Long ton 1016.05 15
Short ton 907.185 16
Troy ounce 0.0311035 17

Surface

Unit Ratio to Reference Unit code
Square meter 1 (this is the reference unit) 6

Count

Unit Ratio to Reference Unit code
Piece 1 (this is the reference unit) 8

Energy

Unit Ratio to Reference Unit code
MMBTU 293.071107 9
Kilowatt hour 1 (this is the reference unit) 20

Time

Unit Ratio to Reference Unit code
Hour 1 (this is the reference unit) 18
Month 720 19

Errors

The above command returns JSON structured like this:

{
  "status": "error",
  "errors": {
    "message": "This commodity (POPUM) does not exist in WRB's database.",
    "status_code": 404,
    "documentation_url": "https://api.commoprices.com/docs#Errors",
    "email_support": "api@commoprices.com"
  }
}

The CommoPrices API uses the following error codes:

Code Meaning
400 Bad Request – There was an error while processing the request payload (malformed JSON, for instance)
401 Unauthorized – The request is not authenticated, or invalid API key
402 Payment required - You have reached your maximum of quota
403 Forbidden – The request is successfully authenticated (see 401), but the action requires a different type of key
404 Not Found – There is no resource behind the URI
405 Method Not Allowed - You may have used a POST query instead of a GET
429 Too Many Requests – You have sent too many requests in a given amount of time (“rate limiting”)
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.