NAV
bash php javascript

Introduction

Welcome to the CommoPrices API Documentation v1.0

Our API allows to get information on prices and values of more than 4,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) four kind (~structure) of data series.

Two of them are generic :

And another one is 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

Regular commodity prices

CommoPrices provides prices from different databases.

“Regular” means that all thoses databases render JSON with the same structure.

Those databases have different endpoints :

database endpoint availability
WRB /v1/wrb open
COM /v1/com premium
COP /v1/cop premium
CRP /v1/crp premium
FAG /v1/fag premium
INP /v1/inp premium
SOE /v1/soe premium
LCO /v1/lco premium
SOA /v1/soa premium
EOI /v1/eoi premium
ELE /v1/ele premium
CEP /v1/cep premium
JMA /v1/jma premium
ITC /v1/itc premium
UNC /v1/unc premium
OVO /v1/ovo premium
USD /v1/usd premium
CDA /v1/cda premium
FSP /v1/fsp premium
FIS /v1/fis premium
ELI /v1/eli premium
ALY* /v1/aly premium

GET infos for all commodities

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.commoprices.com/v1/wrb",
  "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/v1/wrb",
  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/v1/wrb"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": [
    {
      "database": "wrb",
      "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
    },
    {
      "...": "..."
    },
    {
      "...": "..."
    },
    {
      "database": "wrb",
      "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
    }
  ]
}

WRB database will be used in right panel as an example.

This endpoint retrieves the information concerning the database (listed above).

HTTP Request

GET https://api.commoprices.com/v1/<database>

URL Parameters

Parameter Description
database The code of the database to retrieve. (eg. wrb)

Query Parameters

Parameter Default Description
lang en Define the language of the response

GET info for one commodity

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.commoprices.com/v1/wrb/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/v1/wrb/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/v1/wrb/WRB-ALUMINUM"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": {
    "database": "wrb",
    "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
  }
}

WRB database will be used in right panel as an example.

This endpoint retrieves the information concerning a single commodity.

HTTP Request

GET https://api.commoprices.com/v1/<database>/<code>

URL Parameters

Parameter Description
database The code of the database to retrieve. (eg. wrb)
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/v1/wrb/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/v1/wrb/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/v1/wrb/WRB-ALUMINUM/data"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": {
    "info": {
      "database": "wrb",
      "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
        ]
      ]
    }
  }
}

WRB database will be used in right panel as an example.

This endpoint retrieves the prices of a single commodity.

HTTP Request

GET https://api.commoprices.com/v1/<database>/<code>/data

URL Parameters

Parameter Description
database The code of the database to retrieve. (eg. wrb)
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)

Indexes

CommoPrices provides indexes from different databases.

Those databases have different endpoints :

database endpoint availability
CRI /v1/cri premium
INI /v1/ini premium
LLO /v1/llo premium
SYN /v1/syn premium

GET infos for all indexes

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.commoprices.com/v1/llo",
  "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/v1/llo",
  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/v1/llo"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:


{
  "status": "success",
  "data": [
    {
      "database": "llo",
      "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
    },
    {
        "...":  "...",
        "...":  "...",
    }
    {
      "database": "llo",
      "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
    },
  ]
}

LLO database will be used in right panel as an example.

This endpoint retrieves the information concerning the database (listed above).

HTTP Request

GET https://api.commoprices.com/v1/<database>

URL Parameters

Parameter Description
database The code of the database to retrieve

Query Parameters

Parameter Default Description
lang en Define the language of the response

GET info for one index

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.commoprices.com/v1/llo/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/v1/llo/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/v1/llo/LLO-BDI"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": {
    "info": {
      "database": "llo",
      "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
    }
  }
}

LLO database will be used in right panel as an example.

This endpoint retrieves the information concerning a single index.

HTTP Request

GET https://api.commoprices.com/v1/<database>/<code>

URL Parameters

Parameter Description
database The code of the database to retrieve. (eg. wrb)
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 index

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.commoprices.com/v1/llo/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/v1/llo/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/v1/llo/LLO-BDI/data"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": {
    "info": {
       "database": "llo",
       "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
        ]
      ]
    }
  }
}

LLO database will be used in right panel as an example.

This endpoint retrieves the values of a single index of the database.

HTTP Request

GET https://api.commoprices.com/v1/<database>/<code>/data

URL Parameters

Parameter Description
database The code of the database to retrieve. (eg. wrb)
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)

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/v1/tfr",
  "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/v1/tfr",
  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/v1/tfr"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": [
    {
      "database": "tfr",
      "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"
      }
    },
    {
      "...": "...",
      "...": "..."
    },
    {
      "database": "tfr",
      "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/v1/tfr

Query Parameters

Parameter Default Description
lang en Define the language of the response

GET info for one commodity

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.commoprices.com/v1/tfr/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/v1/tfr/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/v1/tfr/nc8_12074090"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": {
    "info": {
      "database": "tfr",
      "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/v1/tfr/<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/v1/tfr/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/v1/tfr/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/v1/tfr/nc8_12074090/data"
  -H "Authorization: Bearer myApiToken"
  -H "Accept: application/json"

The above command returns JSON structured like this:

{
  "status": "success",
  "data": {
    "info": {
      "database": "tfr",
      "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": [
        [
          "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/v1/tfr/<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)

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/v1/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 quarterly : Q.

Another example : if the original frequency is D (daily), you can then query for M or Q.

Period Code
Daily D
Monthly M
Quarterly Q

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
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.