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:
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
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.
- 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: 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
-
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).
-
freq (default =
any
) data set frequency: Valid values:- A Annual
- M Monthly
-
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)
-
type
trade data type (default =
any
) Valid values:- C Commodities (merchandise trade data)
- S Services (trade in services data)
- token authorization code Valid values: see authentication section above.
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.