The UN Comtrade bulk data API

Notice: this API is only available to users with a premium site license.

Curious if you can use this API? Go here: UN Comtrade Access Rights

Learn more about UN Comtrade Premium services. The core public API is available free of charge.

Introduction

The bulk data API gives users with permission to access the premium web services access to full data set downloads in a compressed CSV format. Entire classification-years may be downloaded. Reporter-classification-years may be accessed as well. Since the files have been already been generated this API provides a much faster interface to access large amounts of data. There are two main access points, one for bulk file availability and the other to download the bulk files.

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.

Download the full policy.

Authentication

You must authenticate using either your IP address or authorization code. Your account must have Web Service access rights. The token parameter is used to pass an authorization code.

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: none

Usage limit: 1000 requests per hour (per authorization code or IP address if no authorization code is used).
Effectively this means you may download the entire database every hour, since ~300 requests are required to download yearly snapshots of all classifications. The limit is only in place to protect against abuse.

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.

Bulk data availability request format

Data request takes the following form:

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

The output is in JavaScript Object Notation (JSON).

Parameters

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

[
   {
      "name":"type-C_r-all_ps-2013_freq-A_px-S1_pub-20150318_fmt-csv_ex-20150318.zip",
      "r":"ALL",
      "px":"S1",
      "ps":"2013",
      "type":"COMMODITIES",
      "freq":"ANNUAL",
      "publicationDate":"2015-03-18T00:00:00",
      "extractDate":"2015-03-18T00:00:00",
      "filesize":179461899,
      "downloadUri":"http://comtrade.un.org/api/get/bulk/C/A/2013/ALL/S1"
   },
   {
      "name":"type-C_r-all_ps-2013_freq-A_px-H2_pub-20150314_fmt-csv_ex-20150314.zip",
      "r":"ALL",
      "px":"H2",
      "ps":"2013",
      "type":"COMMODITIES",
      "freq":"ANNUAL",
      "publicationDate":"2015-03-14T00:00:00",
      "extractDate":"2015-03-14T00:00:00",
      "filesize":372954375,
      "downloadUri":"http://comtrade.un.org/api/get/bulk/C/A/2013/ALL/H2"
   },
   ...
]

API call: http://comtrade.un.org/api//refs/da/bulk?ps=2013

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.

Authentication problems will get error 5000 with the following response:

{
          "validation": {
            "status": {
              "name": "Authentication",
              "value": 5000,
              "category": 0,
              "description": "your login failed",
              "helpUrl": "For more reference visit http://comtrade.un.org/data/doc/api/"
            },
            "message": "Invalid username and/or password",
            }
        }

Authorization problems will get error 5001 with the following response:


        {
          "validation": {
            "status": {
              "name": "Authorization",
              "value": 5001,
              "category": 0,
              "description": "you do not have permissions to access this resource",
              "helpUrl": "For more reference visit http://comtrade.un.org/data/doc/api/"
            },
            "message": "Invalid token",
            }
        }

Bulk data download request format

Data request takes the following form:

http://comtrade.un.org/api/get/bulk/{type}/{freq}/{ps}/{r}/{px}?{token=}

Refer to data availability request format parametersfor descriptions of the parameters type (trade type), freq (frequency), ps (period), r (reporter), px (classification), and optionally token (see authentication).

Examples:

Commodity, annual, 2013, reporter code 152 (Chile), HS as reported, using authorization code authentication:

http://comtrade.un.org/api/get/bulk/C/A/2013/152/HS?token=myauthorizationcode

Commodity, annual, 2012, all data, HS, using IP address authentication (no token passed):

http://comtrade.un.org/api/get/bulk/C/A/2012/ALL/HS

Commodity, annual, 2005, all data, SITC Rev 3, using IP address authentication (no token passed):

http://comtrade.un.org/api/get/bulk/C/A/2005/ALL/S3

Services, annual, 2014, reporter code 251 (France), EBOPS 2002, using IP address authentication (no token passed):

http://comtrade.un.org/api/get/bulk/S/A/2014/251/EB02

Bulk data download response format

All responses are in the form of a ZIP archive. Each zip archive contains exactly one CSV file. The CSV file adheres to the format specified in the UN Comtrade API CSV response format documentation. If new fields have recently been added to the response format there may be a delay before they become available in the bulk files.

Comma-separated Values (CSV) format for goods [type=C]

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,Commodity Code,Commodity,Qty Unit Code,Qty Unit,Qty,Netweight (kg),Trade Value (US$),Flag
    
S3,2008,2008,2008,1,0,1,Import,4,Afghanistan,AFG,0,World,WLD,0,Food and live animals,1,No Quantity,,,309541080,0

S3,2008,2008,2008,1,0,2,Export,4,Afghanistan,AFG,0,World,WLD,0,Food and live animals,1,No Quantity,,,280276257,0


...

Comma-separated Values (CSV) format for services [type=S]

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,Mode of Transport Code,Mode of Transport,Commodity Code,Commodity,Netweight (kg),Gross weight (kg),Trade Value (US$),CIF Trade Value (US$),FOB Trade Value (US$),Flag
    
EB,2008,2008,2008,0,0,1,Import,4,Afghanistan,,0,World,,,,200,Total EBOPS Services,,,570089358,,,0

EB,2008,2008,2008,0,0,2,Export,4,Afghanistan,,0,World,,,,200,Total EBOPS Services,,,1217942038,,,0

...

Refresh schedule

Users should be aware that there is a delay between database update (Publication Date) and availability of corresponding bulk files (Extraction Date). They are refreshed as per the following schedule

Country data files

The country data files are refreshed weekly and made available on Friday.

Yearly/monthly data files containing all reporters

The yearly and monthly data files are refreshed monthly and made available on beginning of every month.