The UN Comtrade MBS Data API

Notice: this API consists of several trade data series identified by series_type. All data is publicly accessible.

You can download underlying data of Monthly Bulletin of Statistics (MBS) Analytical Trade Tables and World Tables of International Trade Statistics Yearbook (ITSY). The archived MBS trade tables in original format (PDF) are available from MBS in Prints.

Learn more about UN Comtrade Data APIs.

Introduction

The MBS data API gives users access to historical time series of several MBS trade tables, notably Tables 18-19,35-43 (see description below). Data availability and frequency of update depend on data series. You can find the relevant information at Monthly Bulletin of Statistics Analytical Trade Tables.

T18 Fuel Imports (1980-~)
T19 Fuel Indicators (1980-~)
T35 Total trade - value (1946-~)
T36 Total trade - value, volume, unit value (1945-~)
T37 Trade indices - individual countries/areas (1945-~)
T38 Conversion factors (1946-~)
T39 Trade indices - regions (1945-~)
T40 Manufactured Goods Exports (1980-~)
T41 Exports by provenance and destination (2000-~)
T42 Exports by commodity classes and by regions: developed economies (2000-~)
T43 Exports by commodity classes and by regions (2000-~)
TD1 Value of world exports by provenance and destination
TD2 Value of world exports by provenance and destination
TE2 Growth of world exports by provenance and destination
TF2 Structure of world exports by provenance and destination
TF3 Structure of world exports by provenance and destination

Policy on use and re-dissemination

Please check out the full policy if you are thinking about re-disseminating UN Comtrade data, one relevant quotation from the policy is:

"UNSD allows the use of UN COMTRADE data within data extraction and/or visualization/analytical applications, either free-of-charge or with fees..." (point xiv)

Generally speaking, if you are unsure whether it is alright to use the data, just contact us at comtrade@un.org. We love to hear about new uses for trade data.

Usage limits

Rate limit: none

Usage limit: none

If you hit a usage limit a 409 (conflict) error is returned along with a message specifying why the request was blocked and when requests may resume.

These limits are enforced to prevent abuse of the UN Comtrade API, and may be changed in the future without notice. We will change them, quickly, if we start detecting the API causing us performance problems. If you exceed the limits or otherwise abuse the service, the UN Comtrade API may stop working for you temporarily. If you continue to exceed this limit in a way that indicates blatant abuse, your access to the UN Comtrade API may be blocked. If that happens to you and you feel it was without cause, contact us at comtrade@un.org and we'll discuss how to resolve the problem.

All of these limits are to ensure the environment stays up and responsive for everyone who would like to use it. If you find you need to exceed our rate limits you may need to create a local cache of our data.

Data request format

Data request takes the following form:

http://comtrade.un.org/api/getMBSData?parameters

The output is in JavaScript Object Notation (JSON or CSV).

Parameters

  • series_type (default = any) Type of data series: combination of table number, frequency, type of measurement and currenty. See list of valid data series (JSON).
    NOTE: As an example data series of T37.Q.W.$ indicates quarterly data on Purchasing Power of Exports of table number 37 (external trade indices) in US$.
  • table_type (default = any) MBS Table numbers: MBS and ITSY table identifier. See list of valid table number (JSON).
  • country_code (default = any) reference country/area: the area that reported the trade to UNSD and may consist of country groups. See list of valid areas (JSON).
  • period_type (default = any) data set frequency: Valid values:
    • A Annual
    • Q Quarterly
    • M Monthly
  • period time period (default = any):Regardless the frequency (period_type), the generic format is always YYYYXX. For annual, quarterly and monthly, the accepted values are XX, 21-24 and 1-12, respectively. As an example:

    Annual (2016): 201652

    Quarterly (Q3 2016):201623

    Monthly (January 2016):201601.

  • year reference year (default = any):The reference year of period. As an example: 2015,2016

  • fmt output format (default = json): Valid value are json or csv.

Data response format

JavaScript Object Notation (JSON)

The response includes basic information about the file and the URI to use in order to download the bulk data.

[
              {
                 "validation":{
                    "status":{
                       "name":"Ok",
                       "value":0,
                       "category":0,
                       "description":"",
                       "helpUrl":"For more reference visit http://comtrade.un.org/data/doc/API_MBS"
                    },
                    "message":null,
                    "count":{
                       "value":2,                     
                       "started":"2016-11-01T09:46:49.6655933-04:00",
                       "finished":"2016-11-01T09:46:50.6596627-04:00",
                       "durationSeconds":0.0940694
                    },
                    "datasetTimer":{
                       "started":"2016-11-01T09:46:49.6655933-04:00",
                       "finished":"2016-11-01T09:46:50.3596627-04:00",
                       "durationSeconds":0.6940694
                    }
                 },
                 "dataset":[
                    {
                       "series_type":"T35.A.V.$",
                       "table_type":"T35",
                       "table_type_desc":"Total trade - value",
                       "country_code":842,
                       "country_type":"C",
                       "country_english_name":"United States",
                       "year":2015,
                       "period_type":"A",
                       "period_number":0,
                       "period":"201552",
                       "period_in_date":"01/01/2015",
                       "trade_flow":"X",
                       "trade_flow_desc":"Exports",
                       "commodity_group_code":1,
                       "commodity_group_name":"Total",
                       "partner_country_code":0,
                       "partner_country_english_name":"World",
                       "base_year":null,
                       "currency_type":"$",
                       "value":1504580.0,
                       "value_unit":"M",
                       "value_type":"V",
                       "value_type_desc":"Value",
                       "estimation_type":"A",
                       "estimation_type_desc":"Actual"
                    },
                    {
                       "series_type":"T35.A.V.$",
                       "table_type":"T35",
                       "table_type_desc":"Total trade - value",
                       "country_code":842,
                       "country_type":"C",
                       "country_english_name":"United States",
                       "year":2015,
                       "period_type":"A",
                       "period_number":0,
                       "period":"201552",
                       "period_in_date":"01/01/2015",
                       "trade_flow":"M",
                       "trade_flow_desc":"Imports",
                       "commodity_group_code":1,
                       "commodity_group_name":"Total",
                       "partner_country_code":0,
                       "partner_country_english_name":"World",
                       "base_year":null,
                       "currency_type":"$",
                       "value":2315300.0,
                       "value_unit":"M",
                       "value_type":"V",
                       "value_type_desc":"Value",
                       "estimation_type":"A",
                       "estimation_type_desc":"Actual"
                    }
                 ]
              }
            ]
            

API call: http://comtrade.un.org/api/getMBSData?series_type=T35.A.V.$&country_code=842&year=2015

Comma-separated Values (CSV)

Text strings with commas or newlines in them are surrounded by quotes. A few lines of sample data:

            series_type,table_type,table_type_desc,country_code,country_type,country_english_name,year,period_type,period_number,period,period_in_date,trade_flow,trade_flow_desc,commodity_group_code,commodity_group_name,partner_country_code,partner_country_english_name,base_year,currency_type,value,value_unit,value_type,value_type_desc,estimation_type,estimation_type_desc
T35.A.V.$,T35,Total trade - value,842,C,United States,2015,A,0,201552,01/01/2015,M,Imports,1,Total,0,World,,$,2315300,M,V,Value,A,Actual
T35.A.V.$,T35,Total trade - value,842,C,United States,2015,A,0,201552,01/01/2015,X,Exports,1,Total,0,World,,$,1504580,M,V,Value,A,Actual

API call: http://comtrade.un.org/api/getMBSData?series_type=T35.A.V.$&country_code=842&year=2015&fmt=csv

Additional description of columns

  • trade_flow Flow of trade: when applicable, it indicates exports (X), imports (M), or Cost of Insurance-Freight (CA).
  • base_year Base year of trade indices: when applicable, it refers to base year of external trade indices.
  • currency_type currency unit: when applicable. $ is US dollar, N is National Currency, and SDR is IMF SDR.
  • value_unit Describe the unit of column "value": when applicable, it denotes the unit of values. M is million.
  • value_type Describe attribute (i.e., ratio, volume, etc.) of column "value": see list of valid attributes (JSON).
  • estimation_type Indicate reported or estimated data: A is as reported by reporting countries/areas and C may contain estimate.

Footnote request format

Footnote request takes the following form:

http://comtrade.un.org/api/api/getMBSFootNote?parameters

The output is in JavaScript Object Notation (JSON or CSV).

Parameters

  • table_type (default = any) MBS Table numbers: MBS and ITSY table identifier. See list of valid table number (JSON).
  • country_code (default = any) reference country/area: the area that reported the trade to UNSD and may consist of country groups. See list of valid areas (JSON).
  • fmt output format (default = json): Valid value are json or csv.

Footnote response format

JavaScript Object Notation (JSON)

The response includes basic information about the file and the URI to use in order to download the bulk data.

{[
   "validation":{
      "status":{
         "name":"Ok",
         "value":0,
         "category":0,
         "description":"",
         "helpUrl":"For more reference visit http://comtrade.un.org/data/doc/API_MBS"
      },
      "message":null,
      "count":{
         "value":273,
         "started":"2016-11-02T07:55:20.037814-04:00",
         "finished":"2016-11-02T07:55:20.0668047-04:00",
         "durationSeconds":0.0301233
      },
      "datasetTimer":{
         "started":"2016-11-02T07:57:26.8037814-04:00",
         "finished":"2016-11-02T07:57:27.0368047-04:00",
         "durationSeconds":0.2330233
      }
   },
   "dataset":[
      {
         "table_type":"T35",
         "table_type_desc":"Total trade - value",
         "country_code":16,
         "country_english_name":"American Samoa",
         "footnote_for":"T",
         "footnote_for_desc":"General footnote",
         "footnote_id":59,
         "footnote_english_text":"Year ending 30 September of the years stated.",
         "footnote_french_text":"Année finissant le 30 septembre de l'année indiquée."
      },
      {
         "table_type":"T36",
         "table_type_desc":"Total trade - value, volume, unit value",
         "country_code":16,
         "country_english_name":"American Samoa",
         "footnote_for":"C",
         "footnote_for_desc":"Countries/Areas",
         "footnote_id":59,
         "footnote_english_text":"Year ending 30 September of the years stated.",
         "footnote_french_text":"Année finissant le 30 septembre de l'année indiquée."
      }, ...
            ]
            

API call: http://comtrade.un.org/api/getMBSFootNote?table_type=T35,T36

Comma-separated Values (CSV)

Text strings with commas or newlines in them are surrounded by quotes. A few lines of sample data:

            table_type,table_type_desc,country_code,country_english_name,footnote_for,footnote_for_desc,footnote_id,footnote_english_text,footnote_french_text
T35,Total trade - value,16,American Samoa,T,General footnote,59,Year ending 30 September of the years stated.,Année finissant le 30 septembre de l'année indiquée.
T35,Total trade - value,24,Angola,T,General footnote,30,Imports FOB.,Importations FOB.
...

API call: http://comtrade.un.org/api/getMBSFootNote?table_type=T35,T36&fmt=csv

Additional description of columns

  • footnote_for Which level a specific footnote is attached to: check footnote_for_desc for detailed description.