UN Comtrade API

To access the UN Comtrade API, you will need a UN Comtrade B2C account and a valid API subscription key.

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