Skip to content
UN Comtrade Help Center

UN Comtrade Help Center

  • UN Comtrade website

Getting Started

  • Welcome to UN Comtrade
  • Read Me First (Disclaimer)
  • Use Cases
  • How to Access UN Comtrade data?
  • Subscription Plans
  • UN Comtrade Data Processing and Dissemination Pipeline
  • Policy on use and re-dissemination
  • Premium Subscribers
  • How to create an account
  • Acquiring API Subscription Keys
  • Who do we contact for support?
  • Can I book a demo of the UN Comtrade platform?

FAQ

  • Policy on use and re-dissemination
  • FAQs on Use and Re-dissemination
  • List of References & Parameter Codes
  • Exports from one country may not always align perfectly with the imports of its trading partners.
  • Bilateral asymmetries
  • Issues with UN Comtrade Website?
  • Annual totals vs sum of monthly data
  • Can I book a demo of the UN Comtrade platform?
  • Why are some converted datasets not accessible in the UI?
  • What is “SITC LTS”?
  • Why does the commodity description for some HS codes differ slightly from the official WCO version?
  • Trade valuation
  • How to Access UN Comtrade data?
  • Mode of Transport and Trade Routes
  • Does UN Comtrade provide buyer/supplier-level data?
  • How should I interpret and use quantity data in UN Comtrade?
  • What is bulk file download?
  • How do I use wildcards to query data?
  • How to use UN Comtrade via World Integrated Trade Solution (WITS)
  • What are the data sources for UN Comtrade?
  • Which new data items have been added to UN Comtrade datasets?
  • How to retrieve data for “World” exports to a country in UN Comtrade?
  • What is data preview?
  • What is data delivery?
  • Conversion factors and current/constant value
  • Supplementary Quantity Units
  • Are 6-digit commodity codes included in 4-digit commodity codes or are they separate?
  • Reported and Converted Data: Commodity Conversion Issues
  • Premium Trial Subscription
  • Who do we contact for support?
  • Showcases in Visualization Labs

Premium

  • Premium Subscribers
  • UN Comtrade Tools
  • Menu: Bulk Files

Metadata

  • Seaborne Trade Estimates – Archive
  • Country nomenclature and groupings
  • Historical Data 1900-1960 on IMTS
  • Correlation between ISIC and SITC codes (or Commodity and Industry)
  • Conversion factors and current/constant value
  • Which new data items have been added to UN Comtrade datasets?
  • What are the data sources for UN Comtrade?
  • Supplementary Quantity Units
  • Reporters and Partners
  • Taiwan, Province of China Trade Data
  • Data Conversion
  • Intermediate Goods in Trade Statistics
  • HS 2017 code 3002.19 and HS 2022 code 3822.19
  • HS 2007 code 2916.36
  • Monetary and Non-Monetary Gold in Trade Classifications (SITC, HS)
  • Areas not elsewhere specified
  • Why are China’s re-imports so high?
  • Second Partner Country
  • UN Comtrade and UNData
  • Tariffline product code description
  • Shuttle Trade
  • Trade with itself
  • Reporter country codes and their custom areas
  • Reported and Converted Data: Commodity Conversion Issues
  • Quantity unit information in detailed level data
  • Data Confidentiality in UN Comtrade
  • EU in UN Comtrade
  • Definition of luxury goods
  • Exports from one country may not always align perfectly with the imports of its trading partners.
  • Changes in trade reporting practices of countries with colonies
  • Reporting Period – Calendar Year
  • Measurement of iron trade, specifically in used cars
  • Leasing of aircraft – financial leasing
  • Hong Kong trade with China
  • Historical data on International Merchandise Trade Statistics (1900-1960)
  • Free Zones and Bunkers
  • Food provided on airlines – Transportation Services
  • Country Codes
  • China: Data availability before 1984
  • Italy: Change in Statistical Territory

Definitions

  • Trade valuation
  • Bilateral asymmetries
  • Special Trade System
  • Modes of Supply
  • Economic Territory and Statistical Territory
  • Distinction between Exports and Re-exports / Imports and Re-imports

Do more

  • UN Comtrade Tools
  • Developer tools for UN Comtrade Data

User Guide

  • How to create an account
  • Home page
  • Menu: Data
  • Menu: Data Availability
  • Menu: Bulk Files
  • Menu: Metadata
  • UN Comtrade Tools
  • UN Comtrade API
  • Showcases in Visualization Labs
  • Premium Trial Subscription
  • What is data preview?
  • What is data delivery?
  • What is tariffline data?
  • How to query data
  • How do I use wildcards to query data?
  • Downloading all data by period
  • How to use UN Comtrade via World Integrated Trade Solution (WITS)

Methodology and Manuals

  • Concepts and definitions of International Merchandise Trade Statistics
  • Concepts and definitions of Statistics of International Trade in Services
  • UN Comtrade Data Processing and Dissemination Pipeline
  • Compilation Methodology
  • Historical Data 1900-1960 on IMTS
  • IMTS Publication List
  • HS, SITC, BEC conversion and correspondence tables
  • Quantity and Weight Data in UN Comtrade

Trade in Services

  • Negative values in trade in services
  • Modes of Supply
  • EBOPS 2002: Extended Balance of Payments Services Classification
View Categories
  • Home
  • Docs
  • User Guide
  • UN Comtrade API

UN Comtrade API

6 min read

UN Comtrade offers APIs with or without an API subscription key. However, to access a full set of APIs, you will need a UN Comtrade B2C account and a valid API subscription key. Note that a premium subscription allow access to all APIs, whereas free subscription allow access to some APIs. The API without subscription key is called a “preview” and it has a very limited API end points, and it is intended to have a quick view of the data.

  • To create a UN Comtrade B2C account, please see: How to create a UN Comtrade account
  • To request an API subscription key, please see: Acquiring API Subscription Keys

Preview APIs #

There is no need to create an account nor having API subscription key, the preview APIs would work as is. However, there is a limitation on number of records and rate limit to ensure a fair usage. If you face any performance issue using the preview APIs, you should use the API end points with subscription key instead. The API endpoints to preview data use the following URL:

public/v1/previewpreview final data
public/v1/getMetadatapreview metadata information
public/v1/getDApreview data availability

As an example, the following URL will preview the China export in 2023. Note: all parameters are described in the developer portal.

https://comtradeapi.un.org/public/v1/preview/C/A/HS?flowCode=X&reporterCode=156&period=2023

Developer Portal #

The Azure API Management is used to power the UN Comtrade APIs. It is accessible at https://comtradedeveloper.un.org/.

All available APIs (free or premium) are categorized under “Products” https://comtradedeveloper.un.org/products as follows:

  • Free APIs – This product comprises free APIs that do not require authorization. The subscription is automatically approved.
  • Premium Individual APIs – This product comprises all data APIs of Comtrade. Reserved for individual subscribers – authorization is required.
  • Premium Institutional Pro APIs – This product comprises all data APIs of Comtrade. Reserved for institutional subscribers – authorization is required.
  • Premium Trial APIs – This product comprises premium trial APIs with a restrictive rate limit per day.

The API endpoints to extract trade data, including the data availability are as follows: get, getTariffline, getDa, getDaTariffline, getLiveUpdate, getTariffline.

data/v1/getDaextract data availability – final data
data/v1/getDaTarifflineextract data availability – tariffline data
data/v1/getLiveUpdateextracts most recent publication updates
data/v1/getextracts final data
data/v1/getTarifflineextracts tariffline data
data/v1/getMetadataextracts metadata information

The API endpoints to download trade data in bulk format (pre-packaged compressed files) are: get, getTariffLine, getClassic.

bulk/v1/gettrade data availability and link to bulk trade data file
bulk/v1/getTarifflinetariffline data availability and link to bulk tariffline data file
bulk/v1/getClassictrade data availability and link to trade data file in classic format

Using your subscription key for calling APIs #

You can browse through the API endpoints/operations in the Developer Portal, and you can also try it using the interface. The examples below show some of usual use cases such as downloading bulk files.

API callsDescriptionSubscription Tier
https://comtradeapi.un.org/data/v1/getLiveUpdate?subscription-key={yourSUBSCRIPTIONkeyGOEShere}To show the progress on data releaseFree
https://comtradeapi.un.org/data/v1/get/C/A/HS?cmdCode=93&period=1998&reporterCode=124&partnerCode=0&flowCode=X&maxrecords=500&subscription-key={yourSUBSCRIPTIONkeyGOEShere}To extract small amount of trade data: commodity code 93, year 1998, reporter code 124, partner code 0, flow code XFree
https://comtradeapi.un.org/bulk/v1/file/792/9276b9391090069cc73e0250164f39a63e089dbd1fb02?subscription-key={yourSUBSCRIPTIONkeyGOEShere}To download a bulk file, the URL is provided when calling the data availability. See below for detailsPremium

Download the data with csv or txt format #

If you don’t use the format parameter, it will return a JSON format as default (you can also use format=json but it is not required). See below,

https://comtradeapi.un.org/data/v1/getDA/C/A/HS?period=2022&subscription-key=yourSubsKey

When you include the parameter format=csv or format=txt in your API call, the downloaded file will be a csv or text file. For example:

https://comtradeapi.un.org/data/v1/getDA/C/A/HS?period=2022&subscription-key=yourSubsKey&format=csv will download in csv format and it is comma separated;
https://comtradeapi.un.org/data/v1/getDA/C/A/HS?period=2022&subscription-key=yourSubsKey&format=txt  will download in txt format and it is TAB separated (same as bulk files).

Using API for files bulk download – Premium APIs only #

Once you have your subscription key, you will be able to query the data availability API for New Comtrade Bulk files using this url below. You can obtain the list of codes in different dimensions from this file Comtrade Data Items.

https://comtradeapi.un.org/bulk/v1/get/{type}/{frequency}/{classificationCode}?<reporterCode>&<period>&subscription-key={yourSUBSCRIPTIONkeyGOEShere}
Classic Format:
https://comtradeapi.un.org/bulk/v1/getClassic/{type}/{frequency}/{classificationCode}?<reporterCode>&<period>&subscription-key={yourSUBSCRIPTIONkeyGOEShere}

Parameters:

  • {} mandatory parameters:
    • type => C (commodities) or S (services)
    • frequency => A (annual) or M (monthly)
    • classificationCode => HS for original classification or specific HS editions of H5, H4, H3, etc.
  • <> optional parameters:
    • reporterCode  => M49 Trade country code e.g. 300 Greece
    • period => YYYY for Annual or YYYYMM for Monthly
  • Subscription-Key => Your personal subscription key

These are full examples of the bulk data availability API (the subscription-key is a sample).

  • 2011 Annual – Greece – H3 Classification
https://comtradeapi.un.org/bulk/v1/get/C/A/H3?reporterCode=300&period=2011&subscription-key=1A2B3C4D5E6F304e7ea860b6faa627X8Z9
  • February 2012 Monthly – Greece – HS Original Classification
https://comtradeapi.un.org/bulk/v1/get/C/M/HS?reporterCode=300&period=201202&subscription-key=1A2B3C4D5E6F304e7ea860b6faa627X8Z9
  • 2008 Annual – Greece – SITC Rev3 converted Classification (specify the version) 
https://comtradeapi.un.org/bulk/v1/get/C/M/S3?reporterCode=300&period=2008&subscription-key=1A2B3C4D5E6F304e7ea860b6faa627X8Z9 
  • All 2023 Monthly Data in H0 classification

https://comtradeapi.un.org/bulk/v1/get/C/M/H0?period=202301,202302,202303,202304,202305,202306,202307,202308,202309,202310,202311,202312&subscription-key=1A2B3C4D5E6F304e7ea860b6faa627X8Z9

The response of the API call includes a field called fileUrl to the bulk file.

Example result:

To download a file, you must include your Subscription key in the value of fileUrl, for example:

https://comtradeapi.un.org/bulk/v1/file/300/8713e7032869f910595a72ec1dfca2d190df5fa95297950f17478421be376bff?subscription-key=1A2B3C4D5E6F304e7ea860b6faa627X8Z9

Share This Article :
  • Facebook
  • X
  • LinkedIn
UN Comtrade ToolsShowcases in Visualization Labs
Table of Contents
  • Preview APIs
  • Developer Portal
  • Using your subscription key for calling APIs
  • Download the data with csv or txt format
  • Using API for files bulk download – Premium APIs only
© 2025 UN Comtrade Help Center • Built with GeneratePress