The new Comtrade | the United Nations comprehensive global trade data platform


Page is being drafted - preview to public. Some links may be broken.

New to UN Comtrade? The FAQ contains answers to most of your questions: New Comtrade FAQ for First Time User


Demo on how to use some of New Comtrade UIs: 

Table of Contents

Home page

Welcome to New Comtrade. It is the new UI for the UN Comtrade database, a repository of official international trade statistics and relevant analytical tables. Information about the application and data can be accessed via and select “new Comtrade.”

On this landing page, you can immediately do a quick search on Comtrade data. 

Figure 1. Main Landing Page

Item 1.1. The banner on top of the interface, as shown in figure 1, is always displayed. At first glance, it presents the location of UN Comtrade about the programme of the UN-DESA Statistics Division. As you hover over each banner item, it will provide links to categorical information available on the website.

Item 1.2. On the top right of the page, you can:  

  • Set your language of preference. Please note that at this time, the website can be set to English (En)/French (Fr)/Spanish (Es)languages.
  • (Optional) Login to the website for registered users. Please note that the data is accessible to non-registered users, with a limitation on the number of records and access to some features.

Item 1.3. This link brings the user to the UN Comtrade knowledgebase (, which contains information and documentation on UN Comtrade.

Item 1.4. The quick search feature is available to access the most recent and high-level trade data available. At this time, the default query selects the annual world trade total of the most recent year, but a user can edit the parameters and perform a very basic and quick query from this page.

Item 1.5 Below the quick search feature (item 1.4), a link to download data in bulk format is available for registered premium subscribers.

Item 1.6. Quick links are provided to the frequently visited pages of UN Comtrade.


Though login is optional, a user must register and log in to use the full features of the UN Comtrade database. The differences among anonymous, registered and premium users are outlined at FAQ.

Click on the Login link in the top right corner of the main page.

This will bring you to the login screen:

First time user

1.      Click on Sign up now to create an account.

2.      The following screen appears and will allow you to create a UN Comtrade B2C account. 

Enter a valid email address. Click on Send verification code.

3.      Check your inbox for the verification code. You will receive an email with the subject: “United Nations B2C account email verification code” and contain information like this.

4.      Copy and paste the code verification screen. Click on Verify code to complete the email verification.

5.      Once verified, you can continue with registration. You can now proceed by filling out the additional details:

                            New Password

                            Display Name

                            Given Name


                            Organization Code*

*Optional. If you belong to a registered organization or institution but you register using a different email domain,  you must provide this code to register under the same organizational or institutional account. Contact your UN Comtrade account administrator for details.

Click Create.

6.      Once you have successfully created your account, you will immediately be logged in and directed to the main landing page. You should now see the link on the top right, My Comtrade available. Depending on the level of your subscription, you may see "My Comtrade Free" or "My Comtrade Premium".

You will be prompted with an error message when:

     Username is blank

     Password is blank

     Incorrect username or password

Existing user

1.      Enter your registered email address and password and click Login. Please note IP authentication for legacy Comtrade doesn't apply for new Comtrade.

2.      For users, click the account option. You will be directed to the UN enterprise login page. Your email and UNITE ID password immediately give you access to the UN Comtrade database.

3.      For Google account users, click on the Google account shortcut. 

4.      Please note that we are in a process of adding other identity providers.


Navigation Tab

The navigation tab provides links to the main sections of the UN Comtrade website:


The Data menu links the types of data available in UN Comtrade. Each link directs the user to the standard query page for the selected type of data. (Note: each type of data will be discussed in the relevant section in this document.)

The query page is structured similarly across different data pages to provide an efficient way of data retrieval. Each query page is structured and provided with the standard query parameters or criteria for data retrieval and options to view and save the data.

Querying Data

Standard Query Page: For illustration purposes, see the example below for Trade Data:

Query parameters: Each query parameter has a drill-down list from which users can choose and submit single or multiple values to query. Users can also input or type a search text, and the drill-down list will return values that match the text or string.

For example, for query parameter Periods, the user can expand the list by clicking the chevron or expansion symbol on the right. This expands the available values for the parameter, and the user can scroll and choose by clicking on value(s) available.

A user can also input a search text on the query field. In this example, “5” was provided, and the drill-down list returns all periods with the number “5”.

Saved Parameters and Searches

As a standard feature, full query and query parameters may be saved for future use. This becomes useful for users who periodically retrieve data with the same parameters. This feature is available at both the parameter (field) and query levels. Note: to enable aggregation on specific parameters, and you have to select those parameters in the “aggregate by” option.

1.      To save your parameters, click the Save Group icon to the right of each parameter field. This will save the current values selected in the parameter field.

In this example, ASEAN member countries were selected as trade partners. The user clicks on the Save Group icon.

2.      A window will pop up and ask the user to provide a search name. A user provides “ASEAN Partners.” The user clicks on “Submit,” and the partner grouping is saved.

3.      The saved partner group will now appear under the Partners query field and be available for future queries.

4.      First, construct your query by selecting a value for each parameter to save your full query. Click on the Save Query icon on the bottom right.

A window will pop up and ask the user to provide a search name. A user provides the search name, “USA Imports From ASEAN.” The user clicks on “Submit,” and the query is saved

5.      These custom groupings and saved queries can be found and managed under My Comtrade:

Query Options

In addition to specifying selection criteria, the system offers two options for querying: 

  • Breakdown Mode

Accepted values: Plus or Classic. The Plus enables the breakdown of new data items in Comtrade+ notably detailed trade flow, mode of transport, customs procedure codes, and the 2nd partner (when reported by countries). Whereas the Classic, the selection criteria are automatically set to the following values: trade flows to exports, imports, re-imports, and re-exports), mode of transport to total, customs procedure codes to total, and the 2nd partner to World. The classic mode returns the same dataset as the legacy Comtrade.

  • Aggregate By

Accepted values: None, or any combinations of Commodity Code, Period, Reporter, Partner, 2nd Partner, Mode of Transports and Customs Procedure Codes. If the Aggregate By is active, then the trade values, netweight and gross weight will be aggregated along the selected combination. For example, the following selection will return four records because all reporters will be aggregated into single code.

And by adding the Period in the Aggregate By, the query will return two records.

Viewing and saving query results

Users can choose Preview, Download, or Deliver options to receive the requested data. See the table below for the differences.

Data Extraction Mode




The data will be shown on screen and be limited to 500 records (regardless of the actual results)

Public (no-registration)


The data will be downloaded directly and limited to 100K and 250K records for registered users and subscribers, respectively

Registration required


The data will be prepared in the background, and the link will be sent to the email. The data is limited to 2.5M records

Subscription required

Bulk files (premium)

User interface to download bulk files.


The visualization section can be accessed at: and contains links to various data and metadata visualizations as below:


A place to showcase innovative and experimental uses of UN Comtrade data. Explore visualizations of a huge volume of data and metadata, cutting-edge data extraction tools, and alternative dissemination platforms. It provides links to both internal and external sites.


Developed in the height of the COVID-19 pandemic, the dashboards aim to show the impact of the various economic domains, notably trade, transport, and travel.

Data availability

Due to the continuous data release policy, it shows the available data in the UN Comtrade database. It is an interactive dashboard where users can drill down on specific data categories, periods, and countries.


The metadata section contains external links to metadata, as follows:

Data availability

This page contains data availability and the metadata on the publication and explanatory notes. They can be accessed at This section describes the relevant information when processing the data, such as the data collection date, data source, and new or revised dataset.

Live update

Realtime feeds about data release

Decennial Survey

The decennial survey can be accessed at: This external site captures the detailed reference and structural metadata on International Merchandise Trade Statistics


This publications section contains external links to online and printed publications, as follows:

International Trade Statistics Yearbook (ITSY)

The yearbook provides an overview of the latest trade trends in goods and services, showing the country and product profiles of international trade, respectively, and is published in June and December.

Analytical Tables

The trade analytical tables are released in the Monthly Bulletin of Statistics (MBS).


This section contains external links to online and printed publications, as follows:

Reference Tables

The link to nomenclatures/classifications used in UN Comtrade covers countries, trade flows, products, mode of transport, and customs procedure codes.

Correlation Tables

The link to the conversion and correlation tables can be accessed at: This link provides access to the conversion and correlation tables among different versions of product classifications in HS, SITC, and BEC.

Content of Data

Data Availability

The data availability page returns a catalog of datasets in New Comtrade. It provides summary information of published file types available by dataset.

Similar to the trade data query page, a user can retrieve this catalog information by selecting the appropriate criteria as follows:

Type of Product – Goods or Services

Frequency – Annual or Monthly

Classification Code – HS, SITC, BEC for Goods, EBOPS for Services

Period – YYYY for Annual or YYYYMM for Monthly

Reporter – All or Individual Reporters

Publication Date – Publication date range

For example A user wants to know all available USA annual merchandise datasets published from January 1, 2019, to December 31, 2021. The parameter values would be the following:

Type of Product – Goods

Frequency – Annual

Classification Code – HS, As Reported

Period – All

Reporter – USA

Publication Date – 01/01/2019 – 12/31/2021

The user can choose to view the results on screen by

  1. clicking Preview to view the results on screen, or
  2. clicking on Download to save the results into a .csv file.

A snapshot of the results screen is returned below.  – need to update screenshot below:

From the result screen, the user can do the following:

Click on ‘Extended Columns’ and see item ‘A’ in the figure above. Expand the results table to include Reporter Code and Type Code as part of the results table.

Click on the download icon; see item ‘B’ in the figure above. The results file will be downloaded immediately.

User can also click more information on the tip right information icon, toggle between the list or cube viewing format and the eye icon to see metadata.

Trade Data

This interface returns trade statistics for goods and services based on the following parameters: type of product, frequency, classification code, commodity code, periods, reporter, partner, second partner, trade flows, modes of transport, and customs code. Users can provide more than a single criterion as the parameter.

To query data, see the earlier section on querying data.

Search tips:

·         For faster results, avoid having “ALL” in the selection criteria

·         Availability of the content depends on reporting countries/areas; as an example, some may not have a breakdown by mode of transport

·         Log in for more customization features and to enable the download button

·         The Preview returns a max of 500 records regardless of the actual results

·         Do you know the codes already? Enable the edit mode (pencil icon) for faster input

·         Use “Deliver” for large unattended data extraction (subscription only)

·         Interested in using API instead of UI? Go to the UN Comtrade developer portal at

·         Want to know an actual number of records based on your selection? Use the count button

For more complex queries, you can enable the text box editing by clicking the pencil icon. Then, the codes can be inputted, separated by commas.

Further, it is possible to calculate the custom grouping based on the inputted code by setting the relevant aggregation parameter in the “Aggregate By” box


The tariffline data is the closest to the original microdata provided by countries/areas. The pre-aggregation and classification conversion are not applied; therefore, there is no aggregated data or converted classification. The trade values were converted to USD for comparability, and all nomenclatures are standardized except the commodity. Some countries may report at tariff line level (more than six-digit HS codes).

The user interface is the same as the Trade Data, including the features to save searches and a list of codes.

Bulk Files (Premium)

This interface enables access to full dataset downloads in compressed CSV formats. Entire classification periods may be downloaded. Reporter-classification-period may be accessed as well. Since the files have already been generated, this provides quicker access to large amounts of data. Please be aware that the data is compressed using gzip. Please note that we no longer provide a single file for ALL reporters on a single period due to that the amount of data processed and disseminated have now increased 10 times. It's easier for users to download the data in separated bulk files by each country as soon as it's available. 

Example 1: User requests for 2018 annual merchandise trade data for all reporters in their reported classification

Example 2: User requests for 2018 December merchandise trade data for Australia in H4 classification

Example 3: User requests for 2018 trade in services data for all reporters in EBOPS 2002 classification

UN Comtrade API Management

To access the UN Comtrade API, you need to create an account on the UN Comtrade Developer Portal, obtain an API subscription key, and then use that key to make API requests to retrieve trade data.

Here's a concise guide to help you get started:

  1. Visit the UN Comtrade Developer Portal at and sign up for a UN Comtrade B2C account if you don't already have one.
  2. After creating your account, the next step is to obtain an API key. This key will enable you to send requests to the API and retrieve data. Visit the products page at and select the API product that aligns with your UN Comtrade subscription tier. 
    1. Free APIs
    2. Premium Individual APIs
    3. Premium Institutional Pro APIs
    4. Premium Trial APIs
  3. Click on the API product that matches your subscription tier, provide a subscription name, and click "Subscribe."
  4. Thoroughly review the API documentation to gain a clear understanding of how to structure your requests and explore the available data fields.
  5. Begin using your API key to make requests and access the data you require.

By following these steps, you can swiftly and seamlessly access the UN Comtrade API.

Creating a new UN Comtrade B2C account

  1. Visit the following URL:
  2. Click ‘Azure Active Directory B2C’
  3. A pop-up window will prompt you to sign up. Click on the ‘Sign up now’ link. If you prefer, you can use Google account. Existing users of United Nations or UNICEF can use their own email address
  4. If you use ‘sign up’ link please use the guide below, otherwise proceed to the next step Obtaining your subscription key below.
  5. Write the email address associated to your Comtrade subscription and click ‘Send verification code’.
    You will receive an email with a verification code like this:
  6. Use the verification code in the registration page and click ‘Verify code’ button.
  7. After verification, proceed to fill up the form with a password and your contact details. Once completed click the ‘Create’ button at the bottom of the page.
  8. Once your account has been created, you will receive an automated email confirming your registration.

Developer Portal

The Azure API Management is used to power the UN Comtrade APIs. It is accessible at

After logging in using UN Comtrade Azure B2C credentials, you should go to the following screens:

All available APIs (free or premium) are categorized using “Products” as follows:

  • Free APIs

 The free APIs that do not require authorization. The subscription is automatically approved.

  • Premium Individual APIs

This product comprises of all data APIs of Comtrade. Reserved for individual subscribers – authorization is required.
The main APIs are to extract a small amount of trade data including extracting the data availability and the endpoints are as follows: get, getDa, getDaTariffline, getLiveUpdate, getTariffline and to download trade data using bulk format (prepared compressed file). There are several endpoints: get (trade data availability), getBulkFile (trade data file), getTariffLine (tariff line data availability), getTariffLineFile (tariff line data file) 

  • Premium Institutional Pro APIs

This product comprises of all data APIs of Comtrade. Reserved for institutional subscribers – authorization is required. The list of APIs is the same with "Premium Individual APIs" with unlimited API calls.

Obtaining your subscription key for New Comtrade APIs.

After confirming your registration, we will grant you access to the New Comtrade Bulk API where you will find your subscription key on this page

If this is the first time and you don’t have the subscription keys, you have to go to and select the API products that you need based on your UN Comtrade subscription tiers: free, premium individual and premium pro.

In the API product page, add the subscription name, and click “Subscribe”

After clicking “Subscribe”, the state would be “Submitted” if you select premium APIs, and you need to wait for approval in order to activate the key. If you select free APIs, the request is automatically approved, and you can use your key immediately.

IMPORTANT: You will receive a notification in your registered email that you have submitted a request for a subscription key. 

Upon approval (the state would be shown “Active”), you can access the subscription keys on Click on the ‘Show’ link of the Primary key, and your subscription key will be shown.

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{yourSUBSCRIPTIONkeyGOEShere}To show the progress on data releaseFree{yourSUBSCRIPTIONkeyGOEShere}To extract small amount of trade data: commodity code 93, year 1998, reporter code 124, partner code 0, flow code XFree{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,  

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: will download in csv format and it is comma separated;  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 New Comtrade - data items - 17 Mar 2020.xlsx{type}/{frequency}/{classificationCode}?<reporterCode>&<period>&subscription-key={yourSUBSCRIPTIONkeyGOEShere}

{} mandatory parameters

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

Subscription-Key => Your personal subscription key

reporterCode  => M49 Trade country code e.g. 300 Greece

period => YYYY for Annual or YYYYMM for Monthly

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

  • 2011 Annual - Greece - H3 Classification


  • February 2012 Monthly – Greece – HS Original Classification


The response of the API call includes a field called fileUrl which will indicate the url to the bulk file.

Example result:

  "request": {
    "reporterCode": "792",
    "period": "2020",
    "freqCode": "A",
    "typeCode": "C",
    "clCode": "HS",
    "publishedDateFrom": null,
    "publishedDateTo": null,
    "isOrig": null
  "elapsedTime": "0.54 secs",
  "count": 1,
  "data": [
      "fileUrl": https: //, "fileSize": "176MB", "isOriginalClassification": true,
      "reporterCode": 792,
      "freqCode": "A",
      "typeCode": "C",
      "classificationCode": "H5",
      "refPeriodId": 202001,
      "period": 2020,
      "publicationDate": "2021-07-06T07:43:18Z",
      "partitionKey": "792",
      "rowKey": "9276b9391090069cc73e0250164f39a63e089df9e07f93ef95ee2df98bd1fb02",
      "timestamp": "2021-09-30T22:16:11.3890895+00:00",
      "eTag": "W/\"datetime'2021-09-30T22%3A16%3A11.3890895Z'\""
  "error": ""

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

Using Python Package to Extract the Data

As an alternative of calling the APIs directly, the Python package comtradeapicall can be utilized. This python package is not part of the UN Comtrade offerings. Please contact the original developer for any questions. As an open-source project, it's provided for users' convenience and available at the Python Package Index: Instruction and examples are available at the project site in PyPi and at GitHub See below.

# Extracting tariffline data into a data frame
mydf = comtradeapicall.previewTarifflineData(typeCode='C', freqCode='M', clCode='HS', period='202205',
                                             reporterCode='36', cmdCode='91,90', flowCode='M', partnerCode=36,
                                             customsCode=None, motCode=None, maxRecords=500, format_output='JSON',
                                             countOnly=None, includeDesc=True)

# Downloading tariffline data to specific folder
comtradeapicall.bulkDownloadTarifflineFile(subscription_key, directory, typeCode='C', freqCode='A', clCode='HS',
                                           period='2010', reporterCode=504, decompress=True)

Comtrade R Package

Some users prefer R for data extraction. There are a number of Comtrade R packages developed by the users. The roadmap to adapt to new Comtrade API also depends on the users. For upgrade inquiries, please contact the original developers.

Parameter Codes List / Reference Table

The list of reference tables can be downloaded in JSON format through the following endpoints.
As an alternative, use the Python package comtradeapicall. Or this Excel ComtradePlus - data items - 17 Mar 2020.xlsx

Code List


List all reference tables

Show list of reference tables
mydf = comtradeapicall.listReference()
List of data itemsList of data items/variables used in UN Comtrade


The time interval at which observations occur

Customs Procedure Code

Customs or statistical procedure

Mode of Transports

The mode of transport used when goods enter or leave the economic territory of a country

Partner country/area

The partner country or geographic area for the respective trade flow

Obtain list of partner codes
mydf = comtradeapicall.getReference('partner')


The country or geographic area to which the measured statistical phenomenon relates

Quantity UnitsThe unit for quantity and alternate quantity data items


The classification of products – goods or services
BEC 4 and 5:

EBOPS 2002, 2010 and SDMX (EB is a combined list):

HS nomenclatures and its editions (HS is the combined codes across all editions):

SITC nomenclature and its revision (SS is the combined codes across all editions):