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 :

3/ Trade database for France

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

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"

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

You must replace myApiToken with your personal API key.

Instead of using Authorization: Bearer myApiToken, you can append a parameter to the endpoint you are requesting : ?api_token=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"

{
  "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

To move through pagination, you need to append the following parameter : ?page=3.

Query Parameters

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

warning field is null unless the dataseries is discontinued (~stopped)

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"

{
  "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

warning field is null unless the dataseries is discontinued (~stopped)

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"

{
  "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

warning field is null unless the dataseries is discontinued (~stopped)

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"


{
  "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

To move through pagination, you need to append the following parameter : ?page=3.

Query Parameters

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

warning field is null unless the dataseries is discontinued (~stopped)

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"

{
  "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

warning field is null unless the dataseries is discontinued (~stopped)

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"

{
  "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

warning field is null unless the dataseries is discontinued (~stopped)

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"

{
  "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

To move through pagination, you need to append the following parameter : ?page=3.

Query Parameters

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

warning field is null unless the dataseries is discontinued (~stopped)

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"

{
  "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

warning field is null unless the dataseries is discontinued (~stopped)

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"

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

warning field is null unless the dataseries is discontinued (~stopped)

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&currency=GBP

Languages

Only two languages are available at the moment :

Name	Code
English	`en`
French	`fr`
Deutsch	`de`

Use the code in your query, like this for instance : lang=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.

if start_date is older than oldest_available_date, then start_date will be set at oldest_available_date
if start_date is more recent than latest_available_date, then response will be empty of values in the data.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 than latest_available_date, then end_date will be set at latest_available_date
if end_date is older than oldest_available_date, then response will be empty of values in the data.request.dataseries field.

Use the dates in your query, like this for instance : start_date=2016-06-22&end_date=2016-11-19

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`

Use the code in your query, like this for instance : period=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	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`

Use the code in your query, like this for instance : currency=CHF

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

Use the code in your query, like this for instance : unit=10 (only if base_code of unit is a weight)

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

Use like this for instance : indexing_base=100&indexing_date_reference=2017-01-01

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.

Use like this for instance : ?fill_gaps or ?fill_gaps=true

Fill From

This option will create datapoints from the specified date if the dataseries is starting after it.

Use like this for instance : fill_from=2005-01-01

Fill Until

This option will create datapoints up to the specified date if the dataseries is starting before it.

Use like this for instance : fill_to=2020-01-01

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.

The query round=3 will return results rounded to 3 decimals.

Errors

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

Introduction

Before starting

What we provide

Want to use our widget ?

Want to test requests ?

Authentication

0. Retrieve all open and premium dataseries

Get open dataseries

Get all dataseries

1. Regular commodity prices

GET infos for all commodities

HTTP Request

Query Parameters

GET info for one commodity

HTTP Request

URL Parameters

Query Parameters

GET data for one commodity

HTTP Request

URL Parameters

Query Parameters

2. Indexes

GET infos for all indexes

HTTP Request

Query Parameters

GET info for one index

HTTP Request

URL Parameters

Query Parameters

GET data for one index

HTTP Request

URL Parameters

Query Parameters

3. Trade Data (FR)

GET infos for all commodities

HTTP Request

Query Parameters

GET info for one commodity

HTTP Request

URL Parameters

Query Parameters

GET data for one commodity

HTTP Request

URL Parameters

Query Parameters

Specific parameters for Customs Trade Data

Query parameters

Languages

Dates

Start Date

End Date

Period

Currencies

Units

Volume

Weight

Surface

Count

Energy

Time

Indexing

Fill

Gap Filling

Fill From

Fill Until

Rounding

Errors