Page tree
Skip to end of metadata
Go to start of metadata

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

Info

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

Youtube

Demo on how to use some of New Comtrade UIs: https://www.youtube.com/channel/UCZaf7CS136-yDaYQgE0d_FQ 

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.

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

                            Surname

                            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.

2.      For un.org users, click the @un.org account option. You will be directed to the UN enterprise login page. Your un.org 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:

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.


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

Description

Access

Preview

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

Public (no-registration)

Download

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

Registration required

Deliver

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

Subscription required

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://NewComtrade.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 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 https://comtrade.developer.azure-api.net/

·         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


Tariffline


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.

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

If you wish to use the UN Comtrade APIs, you need to have an account to obtain an API subscription key. 

Creating a new UN Comtrade B2C account

  1. Visit the following URL:https://comtrade.developer.azure-api.net/
  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.

IMPORTANT: Please send an email to comtrade@un.org confirming your registration and requesting access to New Comtrade Bulk API. Include the email address used on the registration and your contact details. Once we get the information (please allow a few days), we will notify you how to get your subscription key used to download bulk files.


Developer Portal


The Azure API Management is used to power the UN Comtrade APIs. It is accessible at https://comtrade.developer.azure-api.net/.

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://comtrade.developer.azure-api.net/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://comtrade.developer.azure-api.net/profile.

If this is the first time and you don’t have the subscription keys, you have to go to https://comtrade.developer.azure-api.net/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. Please notify comtrade@un.org that you have submitted a request so that we can approve your request.


Upon approval (the state would be shown “Active”), you can access the subscription keys on https://comtrade.developer.azure-api.net/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.

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/9276b9391090069cc73e0250164f39a63e089df9e07f93ef95ee2df98bd1fb02?subscription-key={yourSUBSCRIPTIONkeyGOEShere}To download a bulk file, the URL is provided when calling the data availability. See below for detailsPremium

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://newcomtradeapi.net/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 


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   

References

The list of reference tables can be downloaded in JSON format through the following endpoints.

Variable

Description

Frequency

The time interval at which observations occur

https://comtradeapi.un.org/files/v1/app/reference/Frequency.json


Customs Procedure Code

Customs or statistical procedure

https://comtradeapi.un.org/files/v1/app/reference/CustomsCodes.json

Mode of Transports

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


https://comtradeapi.un.org/files/v1/app/reference/ModeOfTransportCodes.json

 



Partner country/area

The partner country or geographic area for the respective trade flow


https://comtradeapi.un.org/files/v1/app/reference/partnerAreas.json


Reporter

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

https://comtradeapi.un.org/files/v1/app/reference/Reporters.json

 


Product

The classification of products – goods or services

BEC 4 and 5:
https://comtradeapi.un.org/files/v1/app/reference/BEC.json


EBOPS 2002, 2010 and SDMX:
https://comtradeapi.un.org/files/v1/app/reference/EB02.json


HS nomenclatures and its editions (HS is the combined codes across all editions):
https://comtradeapi.un.org/files/v1/app/reference/H0.json
https://comtradeapi.un.org/files/v1/app/reference/H1.json
https://comtradeapi.un.org/files/v1/app/reference/H2.json
https://comtradeapi.un.org/files/v1/app/reference/H3.json
https://comtradeapi.un.org/files/v1/app/reference/H4.json
https://comtradeapi.un.org/files/v1/app/reference/H5.json
https://comtradeapi.un.org/files/v1/app/reference/H6.json
https://comtradeapi.un.org/files/v1/app/reference/HS.json

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

https://comtradeapi.un.org/files/v1/app/reference/S1.json
https://comtradeapi.un.org/files/v1/app/reference/S2.json
https://comtradeapi.un.org/files/v1/app/reference/S3.json
https://comtradeapi.un.org/files/v1/app/reference/S4.json
https://comtradeapi.un.org/files/v1/app/reference/SS.json