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 :
- Our main website : https://commoprices.com
- Our API homepage : https://api.commoprices.com
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 :
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",
"structure": "commo",
"code": "JMQWQ",
"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",
"structure": "commo",
"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/JMQWQ",
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/JMQWQ",
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/JMQWQ"
-H "Authorization: Bearer myApiToken"
-H "Accept: application/json"
The above command returns JSON structured like this:
{
"status": "success",
"data": {
"type": "price",
"structure": "commo",
"code": "JMQWQ",
"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/JMQWQ/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/JMQWQ/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/JMQWQ/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",
"structure": "commo",
"code": "JMQWQ",
"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
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) |
round |
null |
Define the precision of the response |
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",
"structure": "commo",
"code": "SAYBQ",
"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",
"structure": "commo",
"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/SAYBQ",
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/SAYBQ",
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/SAYBQ"
-H "Authorization: Bearer myApiToken"
-H "Accept: application/json"
The above command returns JSON structured like this:
{
"status": "success",
"data": {
"info": {
"type": "index",
"structure": "commo",
"code": "SAYBQ",
"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/SAYBQ/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/SAYBQ/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/SAYBQ/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",
"structure": "commo",
"code": "SAYBQ",
"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
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) |
round |
null |
Define the precision of the response |
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",
"structure": "commo",
"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",
"structure": "commo",
"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/ZQTLR",
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/ZQTLR",
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/ZQTLR"
-H "Authorization: Bearer myApiToken"
-H "Accept: application/json"
The above command returns JSON structured like this:
{
"status": "success",
"data": {
"info": {
"type": "trade",
"structure": "commo",
"code": "ZQTLR",
"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/ZQTLR/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/ZQTLR/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/ZQTLR/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",
"structure": "commo",
"code": "ZQTLR",
"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
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) |
round |
null |
Define the precision of the response |
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/dataseries/JMQWQ/data?lang=fr&start_date=2017-01-01¤cy=GBP
Languages
Only two languages are available at the moment :
Name | Code |
---|---|
English | en |
French | fr |
Deutsch | de |
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
.
- if
start_date
is older thanoldest_available_date
, thenstart_date
will be set atoldest_available_date
- if
start_date
is more recent thanlatest_available_date
, then response will be empty of values in thedata.request.dataseries
field.
End Date
Set the end date for the query.
By default, the end_date
is set to the latest_available_date
.
- if
end_date
is more recent thanlatest_available_date
, thenend_date
will be set atlatest_available_date
- if
end_date
is older thanoldest_available_date
, then response will be empty of values in thedata.request.dataseries
field.
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 | Kč | 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 | zł | 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 |
Indexing
On any kind of dataseries, you can ask our API to index the data.
For instance, you could ask to set the data as an index with a base (ie 100) and a reference date (ie 2017-01-01)
indexing_base
must be a positive numerical value
indexing_date_reference
must have the following format : YYYY-MM-DD
Fill
We have three different options to fill data with values.
They are all independent and can be use seperately or all together (or only two out of the three available).
Gap Filling
This option will fill the gaps between two datapoints by creating a new datapoint with the value of the oldest point.
For instance, if you have one point (2018-03-31 for 532 €/t) and another one (2018-06-30 for 514€/t), the fill_gaps
option will create two other points inbetween : (2018-04-30 for 532€/t) and (2018-05-31 for 532€/t).
Please note that this option will add a new field on columns
and dataseries
so you can differentiate points that are filled and those who are not.
Fill From
This option will create datapoints from the specified date if the dataseries is starting after it.
Fill Until
This option will create datapoints up to the specified date if the dataseries is starting before it.
Rounding
By default, the data is rounded according to its order of magnitude. The number of decimals depends on the value of the first point:
Value | Number of decimals |
---|---|
< 0.01 | 7 |
0.01 <= … < 0.1 | 5 |
0.1 <= … < 1 | 3 |
1 <= … < 100 | 2 |
100 <= … < 1000 | 1 |
>= 1000 | 0 |
The number of decimals can be overridden by passing a positive integer value to the round
parameter.
The maximum number of decimals will always be the precision available to us regardless of the query parameter. Thus if we know only 2 decimals for a point and the query parameter is round=3
, the result will only have 2 decimals.
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": "contact@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. |