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:
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.
- Going to the My account Account Info tab in the legacy interface. (URL: http://comtrade.un.org/db/u/uAccountInfo.aspx)
- Make sure your correct email is indicated at the top of the resulting page; otherwise, edit as necessary.
- Go to the bottom for your Authorization Code.
- 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 eitherYYYY
orYYYYMM
. 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 isHS
, 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 codeST
, meaning "Standard International Trade Classification (SITC), as reported" is chosen. If you require data formatted in the SITC classification, it is better to useS1
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):
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
orYYYYMM
ornow
orrecent
. For example:Annual (YYYY):
2010
Monthly (YYYY or YYYYMM): Individual periods as
201001
or full years as2010
, automatically expands to query periods201001,201002,201003,...,201012
.The special code
now
can be used to ask for the most recently available period. For annual data this might be2013
, 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 or201401,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 isHS
, meaning "Harmonized System (HS), as reported", whereas a service default isEB02
, 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 codeST
, meaning "Standard International Trade Classification (SITC), as reported" is chosen. If you require data formatted in the SITC classification, it is better to useS1
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) and2
(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
inHS
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 arejson
orcsv
. -
max
maximum records returned (default = 500) A valid integer in the range (Guest:
[1, 100000]
, Authenticated:[1, account limit*]
, NOTE: Maximum limit is 250,000). If the number of records returned by the query exceedmax
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
...
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
},
...
]
}
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.
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.