Page History

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 https://comtrade.un.org/ 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 (https://unstats.un.org/wiki/display/comtrade), 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.

Login

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.

First time user

Existing user

Navigation Tab

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

Data

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.

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 2^nd 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 2^nd 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, 2^nd 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.

Bulk files (premium)

User interface to download bulk files.

Visualization

The visualization section can be accessed at: https://comtradeplus.un.org/Visualization and contains links to various data and metadata visualizations as below:

Labs

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.

Monitor

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.

Metadata

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 https://comtradeplus.un.org/DataAvailability. 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: https://comtrade.un.org/survey/Reports/. This external site captures the detailed reference and structural metadata on International Merchandise Trade Statistics

Publications

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

References

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: https://unstats.un.org/unsd/classifications/Econ. 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.

https://comtradeplus.un.org/DataAvailability

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

Tariffline

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 partners 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

Are you looking to access the UN Comtrade API?  You need to have an account to obtain an API subscription key.  Here is a quick summary of the steps you can follow to get started:

1. Visit the UN Comtrade Developer Portal https://comtradedeveloper.un.org/  and create a UN Comtrade B2C account if you haven't already.
2. Once you've created an account, you'll need to obtain an API key. This will allow you to make requests to the API and retrieve data.  Browse through the products page: https://comtradedeveloper.un.org/products and select the API Product based on your UN Comtrade subscription tier:
   • Free APIs
   • Premium Individual APIs
   • Premium PRO APIs
   • Premium TRIAL APIs
3. Choose your API product and provide a subscription name and click “Subscribe.”
4. Read the API documentation carefully to understand how to construct your requests and what data fields are available.
5. Use your API key to start making requests and retrieve the data you need.

By following these steps, you can quickly and easily access the UN Comtrade API.

Creating a new UN Comtrade B2C account

1. Visit the following URL: https://comtradedeveloper.un.org/
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 https://comtradedeveloper.un.org/.

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” https://comtradedeveloper.un.org/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 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 https://comtradedeveloper.un.org/profile.

If this is the first time and you don’t have the subscription keys, you have to go to https://comtradedeveloper.un.org/products 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 https://comtradedeveloper.un.org/profile. 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.

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 New Comtrade - data items - 17 Mar 2020.xlsx

https://comtradeapi.un.org/bulk/v1/get/{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

          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 

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: //comtradeapi.un.org/bulk/v1/file/792/9276b9391090069cc73e0250164f39a63e089df9e07f93ef95ee2df98bd1fb02, "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:

https://comtradeapi.un.org/bulk/v1/file/792/9276b9391090069cc73e0250164f39a63e089df9e07f93ef95ee2df98bd1fb02?subscription-key=1A2B3C4D5E6F304e7ea860b6faa627X8Z9   

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: https://pypi.org/project/comtradeapicall/. Instruction and examples are available at the project site in PyPi and at GitHub https://github.com/uncomtrade/comtradeapicall. 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,
                                             partner2Code=None,
                                             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

mydf = comtradeapicall.listReference()

mydf = comtradeapicall.getReference('partner')