The UN Comtrade data extraction API

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:

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

• type trade data type (default = any) Valid values:
  • C Commodities (merchandise trade data)
  • S Services (trade in services data)
• freq (default = any) data set frequency: Valid values:
  • A Annual
  • M Monthly
• r (default = any) reporting area: the area that reported the trade to UNSD. See list of valid reporters (JSON, formatted for select2.js, pass "id" to parameter).
  

• ps time period (default = any): Depending on freq, time period can take either YYYY or YYYYMM. For example:

  Annual (YYYY): 2010

  Monthly (YYYY or YYYYMM): Individual periods as 201001.

• px classification (default = any): Trade data classification scheme. See list of valid classifications:

  HINT: data is not always available in every classification. Availability varies by time period and reporter. A good default is HS, meaning "Harmonized System (HS), as reported". To see what data is available in different classifications see the data availability section.
  WARNING: only older data was submitted to UN Comtrade in SITC. With rare exceptions no data will be returned in queries from 1992 or later if code ST, meaning "Standard International Trade Classification (SITC), as reported" is chosen. If you require data formatted in the SITC classification, it is better to use S1 for SITC Rev. 1 if you would like the longest time series or check the data availability section and use the SITC revision most appropriate for the data you are interested in.
  • HS Harmonized System (HS), as reported (e.g. if data was originally submitted to UN Comtrade in HS1996 then HS1996 is displayed) (full classification code list in JSON, formatted for select2.js)
  • H0 HS 1992 (full classification code list in JSON, formatted for select2.js)
  • H1 HS 1996 (full classification code list in JSON, formatted for select2.js)
  • H2 HS 2002 (full classification code list in JSON, formatted for select2.js)
  • H3 HS 2007 (full classification code list in JSON, formatted for select2.js)
  • H4 HS 2012 (full classification code list in JSON, formatted for select2.js)
  • ST Standard International Trade Classification (SITC), as reported (e.g. if data was originally submitted to UN Comtrade in SITC Rev. 1 then SITC Rev. 1 is displayed) (full classification code list in JSON, formatted for select2.js)
  • S1 SITC Revision 1 (full classification code list in JSON, formatted for select2.js)
  • S2 SITC Revision 2 (full classification code list in JSON, formatted for select2.js)
  • S3 SITC Revision 3 (full classification code list in JSON, formatted for select2.js)
  • S4 SITC Revision 4 (full classification code list in JSON, formatted for select2.js)
  • BEC Broad Economic Categories (BEC) (full classification code list in JSON, formatted for select2.js)
  • EB02 Extended Balance of Payments Services Classification (EB02) (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
• token authorization code Valid values: see authentication section above.

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:

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

• r (default = 0) reporting area: the area that reported the trade to UNSD. See list of valid reporters (JSON, formatted for select2.js, pass "id" to parameter).
  
• freq (default = A) data set frequency: Valid values:
  • A Annual
  • M Monthly

• ps time period (default = now): Depending on freq, time period can take either YYYY or YYYYMM or now or recent. For example:

  Annual (YYYY): 2010

  Monthly (YYYY or YYYYMM): Individual periods as 201001 or full years as 2010, automatically expands to query periods 201001,201002,201003,...,201012.

  The special code now can be used to ask for the most recently available period. For annual data this might be 2013, for monthly it will be the most recent single month. Depending on reporter data may not be available.

  The special code recent can be used to ask for the 5 most recently available periods, e.g. 2013,2012,2010,2009,2008 for annual or 201401,201312,201311,201310,201309.

• px classification (default values are HS for goods and EB02 for services): Trade data classification scheme. See list of valid classifications:

  HINT: data is not always available in every classification. Availability varies by time period and reporter. A good default is HS, meaning "Harmonized System (HS), as reported", whereas a service default is EB02, meaning "Extended Balance of Payments Services Classification". To see what data is available in different classifications see the data availability section.
  WARNING: only older data was submitted to UN Comtrade in SITC. With rare exceptions no data will be returned in queries from 1992 or later if code ST, meaning "Standard International Trade Classification (SITC), as reported" is chosen. If you require data formatted in the SITC classification, it is better to use S1 for SITC Rev. 1 if you would like the longest time series or check the data availability section and use the SITC revision most appropriate for the data you are interested in.
  • HS Harmonized System (HS), as reported (e.g. if data was originally submitted to UN Comtrade in HS1996 then HS1996 is displayed) (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • H0 HS 1992 (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • H1 HS 1996 (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • H2 HS 2002 (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • H3 HS 2007 (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • H4 HS 2012 (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • ST Standard International Trade Classification (SITC), as reported (e.g. if data was originally submitted to UN Comtrade in SITC Rev. 1 then SITC Rev. 1 is displayed) (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • S1 SITC Revision 1 (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • S2 SITC Revision 2 (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • S3 SITC Revision 3 (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • S4 SITC Revision 4 (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • BEC Broad Economic Categories (BEC) (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
  • EB02 Extended Balance of Payments Services Classification (EB02) (full classification code list in JSON, formatted for select2.js, pass "id" to cc parameter)
• p partner area (default = all): partner area. The area receiving the trade, based on the reporting areas data. See list of valid partners: (JSON, formatted for select2.js, pass "id" to parameter)
• rg trade regime / trade flow (default = all): The most common area 1 (imports) and 2 (exports), see list of valid trade flows: (JSON, formatted for select2.js, pass "id" to parameter)
• cc classification code (default = AG2): a commodity code valid in the selected classification. Full lists of codes for each classification are linked to above under the px parameter. Some codes are valid in all classifications:
  • TOTAL Total trade between reporter and partner, no detail breakdown.
  • AG1, AG2, AG3, AG4, AG5, AG6 Detailed codes at a specific digit level. For instance AG6 in HS gives all of the 6-digit codes, which are the most detailed codes that are internationally comparable. Not all classifications have all digit levels available. See the classification specific codes for more information.
  • ALL All codes in the classification.
• fmt output format: If none is supplied the returned type is based on the Accept header. Valid values are json or csv.
• max maximum records returned (default = 500) A valid integer in the range (Guest: [1, 50000], Authenticated: [1, account limit*], NOTE: Maximum limit is 250,000). If the number of records returned by the query exceed max results are truncated to this number. In output types supporting metadata (e.g. json) information about the total number of records that would have been returned is included.
• type trade data type (default = C) Valid values:
  • C Commodities (merchandise trade data)
  • S Services (trade in services data)
• head heading style (default = H) Changes the heading line (first line) in CSV output. Will also change Excel output once that is available. Valid values:
  • H Human readable headings, meant to be easy to understand. May contain special characters and spaces.
  • M Machine readable headings that match the JSON output, meant to be easy to parse. Does not contain special characters, spaces, etc.
• token authorization code Valid values: see authentication section above.
• IMTS (default = 2010) data fields/columns based on IMTS Concepts & Definitions
  • 2010[forthcoming] data that comply with IMTS 2010 Concepts & Definitions (addition of mode of transports, 2nd partner country, customs procedure codes, imports FOB, if applicable)
  • orig data that comply with earlier version of IMTS Concepts & Definitions

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.

• A simple bar chart using D3.
• Reading data into R from the API.

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.