The UN Comtrade data extraction API

Notice: this API may be considered stable. However, new fields may be added in the future.

While this API is still subject to change, changes that remove fields will be announced and a method of accessing legacy field formats will be made available during a transition period.

New fields may be added to the CSV or JSON output formats without warning. Please write your code that accesses the API accordingly.

Legacy web services / API

Need an API that is ready for production? If you are a registered user, you can continue to use the legacy API for production purposes. We will warn everyone before the legacy API is retired.

Introduction

This page documents the new UN Comtrade data extraction API(s), the proposed replacement for the legacy UN Comtrade Web Services / API. The legacy API will continue to exist until at least the end of August 2015, and likely longer. After that, depending on the status of the new API and the needs of our user community the legacy API will begin to be phased out. Six months before any phase out of the legacy API occurs we will send a communication to all registered users announcing the transition.

The legacy API has served everyone well. But it is time to modernize. Core reasons for building this new API include updated data collection / dissemination recommendations (IMTS 2010), new data exchange standards (JSON, SDMX 2.1) and a need to balance open access to data against server capacity. But since we're making changes we'll also try to integrate your recommendations. Take a look at the planned features. If you see anything you'd like added to the list please let us know, we value your feedback.

For now, the new UN Comtrade data extraction API allows you to extract data in JSON or CSV format. You can use it to simplify to downloading a larger data series or to integrate UN Comtrade data into your web pages using AJAX calls. If you use the API to develop an interesting visualization we encourage you to share that with us, and perhaps we'll include a link to your creation on UN Comtrade Labs or highlight it on our twitter feed.

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.

Authentication

This is a Public API and no authentication is required. However, authenticated users have higher usage limits. Authenticated users can access the API in one of the following two methods described below.

IP Address Authentication for Authenticated Users

If you are an authenticated user and are accessing the API via an IP address listed on your account, your account should be recognized (and there is no need to use the authorization code method below). To validate whether you are accessing UN Comtrade from an authorized IP address visit http://comtrade.un.org/ws/CheckRights.aspx.

How Authenticated Users can obtain their Authorization Code (pass via the "token" parameter)

If you are an authenticated user not accessing the API via an IP address listed on your account, you will need to use the token parameter steps below to pass an authorization code.

  1. Going to the My account Account Info tab in the legacy interface. (URL: http://comtrade.un.org/db/u/uAccountInfo.aspx)
  2. Make sure your correct email is indicated at the top of the resulting page; otherwise, edit as necessary.
  3. Go to the bottom for your Authorization Code.
  4. To test the validity of your authorization code visit: http://comtrade.un.org/ws/CheckRights.aspx.

Usage limits

Rate limit (guest): 1 request every second (per IP address or authenticated user). Rate limit (authenticated): 1 request every second (per IP address or authenticated user).

Usage limit (guest): 100 requests per hour (per IP address or authenticated user).

Usage limit (authenticated): 10,000 requests per hour (per IP address or authenticated user).

Parameter combination limit: ps, r and p are limited to 5 codes each. Only one of the above codes may use the special ALL value in a given API call. Classification codes (cc) are limited to 20 items. ALL is always a valid classification code.

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 availability request format

Data request takes the following form:

http://comtrade.un.org/api//refs/da/view?parameters

The output is in JavaScript Object Notation (JSON).

Parameters

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

[
    {
        "type": "COMMODITIES",
        "freq": "MONTHLY",
        "px": "HS",
        "r": "76",
        "rDesc": "Brazil",
        "ps": "201607",
        "TotalRecords": 126827,
        "IsOriginal": 1,
        "IsPartnerDetail": 1,
        "UploadTime": "2016-08-05T00:00:00"
    },
    {
        "type": "COMMODITIES",
        "freq": "MONTHLY",
        "px": "HS",
        "r": "579",
        "rDesc": "Norway",
        "ps": "201607",
        "TotalRecords": 110618,
        "IsOriginal": 1,
        "IsPartnerDetail": 1,
        "UploadTime": "2016-08-30T00:00:00"
    },
    ...
]
            

API call: http://comtrade.un.org/api/refs/da/view?type=C&freq=M&ps=201607&px=HS

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.

UN Comtrade data request format

UN Comtrade data request takes the following form:

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

The output may be one of (determined by the fmt parameter):

  • json (default) JavaScript Object Notation (JSON)
  • csv Comma-separated Values (CSV)

Parameters

UN Comtrade data response format

Warning: this API could change at any moment!

That means the response formats might change too. Yes, we said it at the top of the page too. We really mean it.

Comma-separated Values (CSV) - Beta API Response

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

Classification,Year,Period,Period Desc.,Aggregate Level,Is Leaf Code,Trade Flow Code,Trade Flow,Reporter Code,Reporter,Reporter ISO,Partner Code,Partner,Partner ISO,2nd Partner Code,2nd Partner,2nd Partner ISO,Customs Proc. Code,Customs,Mode of Transport Code,Mode of Transport,Commodity Code,Commodity,Qty Unit Code,Qty Unit,Qty,Alt Qty Unit Code,Alt Qty Unit,Alt Qty,Netweight (kg),Gross weight (kg),Trade Value (US$),CIF Trade Value (US$),FOB Trade Value (US$),Flag
HS,2013,2013,2013,2,0,1,Import,826,United Kingdom,GBR,0,World,WLD,,,,,,,,01,Live animals,1,No Quantity,,,,,,,638496202,,,0
HS,2013,2013,2013,2,0,2,Export,826,United Kingdom,GBR,0,World,WLD,,,,,,,,01,Live animals,1,No Quantity,,,,,,,618257677,,,0
...

API call: http://comtrade.un.org/api/get?max=50000&type=C&freq=A&px=HS&ps=2013&r=826&p=0&rg=all&cc=ALL&fmt=csv

Comma-separated Values (CSV), using same headings as JSON

If you want the CSV output using the same labels as JSON, just ask for the machine readable heading format (head=M)

pfCode,yr,period,periodDesc,aggrLevel,IsLeaf,rgCode,rgDesc,rtCode,rtTitle,rt3ISO,ptCode,ptTitle,pt3ISO,cmdCode,cmdDescE,qtCode,qtDesc,TradeQuantity,NetWeight,TradeValue,estCode
HS,2013,2013,2013,2,0,1,Import,826,United Kingdom,GBR,0,World,WLD,,,,,,,,01,Live animals,1,No Quantity,,,,,,,638496202,,,0
HS,2013,2013,2013,2,0,2,Export,826,United Kingdom,GBR,0,World,WLD,,,,,,,,01,Live animals,1,No Quantity,,,,,,,618257677,,,0
...

API call: http://comtrade.un.org/api/get?max=50000&type=C&freq=A&px=HS&ps=2013&r=826&p=0&rg=all&cc=ALL&fmt=csv&head=M

JavaScript Object Notation (JSON)

There are two major sections of the JSON response. The validation and dataset sections. The dataset is fairly simple - it is an array of all of the data returned. The validation section will have any errors found during validation of the dataset as well as query timing information. The count section includes information about the full dataset, so if you limit the returned data using max you can check validation.count.value to see if any information was truncated from the full query result.

The validation.status object includes details about why a request was rejected, if it was. When a request is successfully completed validation.status will have an "Ok" value, otherwise a validation error message will be shown. Please refer to Validation Status Codes section to learn more.

{
   "validation":{
      "status":{
         "name":"Ok",
         "value":0,
         "category":0,
         "description":"",
         "helpUrl":""
      },
      "message":null,
      "count":{
         "value":17559,
         "started":"2015-05-11T11:29:41.6096178-04:00",
         "finished":"2015-05-11T11:29:57.4572024-04:00",
         "durationSeconds":15.8475846
      },
      "datasetTimer":{
         "started":"2015-05-11T11:29:41.6096178-04:00",
         "finished":"2015-05-11T11:30:39.6044167-04:00",
         "durationSeconds":57.9947989
      }
   },
   "dataset":[
      {
         "pfCode":"HS",
         "yr":2013,
         "period":2013,
         "periodDesc":"2013",
         "aggrLevel":2,
         "IsLeaf":0,
         "rgCode":1,
         "rgDesc":"Import",
         "rtCode":826,
         "rtTitle":"United Kingdom",
         "rt3ISO":"GBR",
         "ptCode":0,
         "ptTitle":"World",
         "pt3ISO":"WLD",
         "ptCode2":null,
         "ptTitle2":"",
         "pt3ISO2":"",
         "cstCode":"",
         "cstDesc":"",
         "motCode":"",
         "motDesc":"",
         "cmdCode":"01",
         "cmdDescE":"Live animals",
         "qtCode":1,
         "qtDesc":"No Quantity",
         "qtAltCode":null,
         "qtAltDesc":"",
         "TradeQuantity":null,
         "AltQuantity":null,
         "NetWeight":null,
         "GrossWeight":null,
         "TradeValue":638496202,
         "CIFValue":null,
         "FOBValue":null,
         "estCode":0
      },
      {
         "pfCode":"HS",
         "yr":2013,
         "period":2013,
         "periodDesc":"2013",
         "aggrLevel":2,
         "IsLeaf":0,
         "rgCode":2,
         "rgDesc":"Export",
         "rtCode":826,
         "rtTitle":"United Kingdom",
         "rt3ISO":"GBR",
         "ptCode":0,
         "ptTitle":"World",
         "pt3ISO":"WLD",
         "ptCode2":null,
         "ptTitle2":"",
         "pt3ISO2":"",
         "cstCode":"",
         "cstDesc":"",
         "motCode":"",
         "motDesc":"",
         "cmdCode":"01",
         "cmdDescE":"Live animals",
         "qtCode":1,
         "qtDesc":"No Quantity",
         "qtAltCode":null,
         "qtAltDesc":"",
         "TradeQuantity":null,
         "AltQuantity":null,
         "NetWeight":null,
         "GrossWeight":null,
         "TradeValue":618257677,
         "CIFValue":null,
         "FOBValue":null,
         "estCode":0
      },
      ...
   ]
}

API call: http://comtrade.un.org/api/get?max=50000&type=C&freq=A&px=HS&ps=2013&r=826&p=0&rg=all&cc=AG2&fmt=json

Validation Status Codes

The validation.status object includes details about why a request was rejected, if it was. The user must follow the API rules and regulations while requesting data. If while doing a request there is a problem, user will get different responses depending on the situation, these responses include a validation.message describing the type of error and how the user could solve it. In the case the error is persisting please contact us at comtrade@un.org.

Complex queries will get error 5002 this response:


 {
  "validation": {
    "status": {
      "name": "Query complexity",
      "value": 5002,
      "category": 0,
      "description": "your query is too complex. Please simplify.",
      "helpUrl": "For more reference visit http://comtrade.un.org/data/doc/api/"
    },
    "message": "Too many months selected.",   
    }
}

Reaching more results than permitted will get error 5003 this response:


{
  "validation": {
    "status": {
      "name": "Result too large",
      "value": 5003,
      "category": 0,
      "description": "you do not have permissions to access such a large resultset",
      "helpUrl": "For more reference visit http://comtrade.un.org/data/doc/api/"
    },
    "message": "Maximum resultset is: 100000",   
    }
}

Invalid value parameters will get error 5004 this response:


{
  "validation": {
    "status": {
      "name": "Invalid parameter",
      "value": 5004,
      "category": 0,
      "description": "the selected query does not accept the passed option.",
      "helpUrl": "For more reference visit http://comtrade.un.org/data/doc/api/"
    },
    "message": "Invalid classification for trade type.",
    }
}

Examples and help

You may easily generate sample API request strings by visiting the data selection interface and executing a query. Click on the API call link below the results to see the API call used to generate the data request.

Detailed examples:

If there are use cases that confuse you or you find errors in the API please feel free to email comtrade@un.org for support or submit a bug report. Our resources are limited, but we'll try to get to all queries.