Data Extraction using Comtrade Web Service

General Information

Comtrade Web Service is a REST Web Service (see http://en.wikipedia.org/wiki/Representational_State_Transfer) so that data extraction requests need the right URL to be submitted.

Data, metadata (such as explanatory notes) and data availability can be accessible within web service framework.

Data Format

The web service offers two kinds: SDMX (see http://www.sdmx.org) and element-based-XML. Depending on what you need, both formats can be used independently.

In order to promote SDMX format, command line data extraction program was created (ComtradeTools). You can use it to extract data and metadata within SDMX and save it as CSV text format.

SDMX vs. Element-Based-XML

SDMX merges data and metadata information in one XML file. For an example, exchange rate and trade system (both of them are metadata) are included on data header. Due to its complexity, SDMX might require extensive learning effort.

On the other hand, element-based-XML is a very simple format, on which it can also be imported easily with other spreadsheets or databases, such as Microsoft Excel. However, metadata may not integrated with data.

Note: Complex query which includes commodity/country grouping is only available on element-based-XML.

Security & Authentication

Access to UN Comtrade database is restricted with IP authentication. A user must have site license account in UN Comtrade and Web Service access right is granted. However, access to metadata and data availability is not restricted.

Click here to check your access rights: http://comtrade.un.org/ws/CheckRights.aspx

Web Service Methods and Parameters

To access REST web service, you need page name (method) and query string (parameter). In fact, UN Comtrade database was built based on query string, such result page of Ireland Total Export in 2006 (http://comtrade.un.org/db/dqBasicQueryResults.aspx?cc=TOTAL&px=H2&r=372&y=2006).

dqBasicQueryResults.aspx is the page name (method to show result) and cc=TOTAL&px=H2&r=372&y=2006 are the query strings, of which cc is commodity code, px is commodity classification, r is reporter and y is year.

In order to get the result via web service, you need to change dqBasicQueryResults.aspx to get.aspx (for Element-Based-XML format) or getSdmxV1.aspx (for SDMX format) and change /db to /ws (web service) and add comp=false (set compression flag to disable, so that it can be viewed on a browser):

(http://comtrade.un.org/ws/get.aspx?cc=TOTAL&px=H2&r=372&y=2006&comp=false or

http://comtrade.un.org/ws/getSdmxV1.aspx?cc=TOTAL&px=H2&r=372&y=2006&comp=false)

Here is the list of common query string parameters:

Px = Commodity Classification

R = Reporter

Y = Year

CC = Commodity Code

P = Partner Country

Rg = Trade Flow

Data (restricted access)

The following data is available (depends on your access rights):

-          UN Comtrade (get.aspx, getSdmxV1.aspx)

-          TotalTrade (getTTotal.aspx, getConvFactor.aspx)

-          Tariff Line (getSdmxTariffLineV1.aspx)

Metadata and data availability (free access)

Reference Tables:

-          Country List (refs/getCountryList.aspx)

-          Commodity List (refs/getCommodityList.aspx)

URL examples:

-          Get 2 digit HS1996: http://comtrade.un.org/ws/refs/getCommodityList.aspx?px=H1&cc=??

-          Get all country codes: http://comtrade.un.org/ws/refs/getCountryList.aspx

Metadata:

-          Explanatory Notes (refs/getExplanatoryNotes.aspx)

Data Availability

-          Data Availability (refs/getDataAvailablity.aspx)

Asynchronous Web Service (Batch Web Service)

If web service request is equal with direct download, then asynchronous web service is equal to batch submission. It handles complex queries that are submitted to web service by executing it asynchronously. 

Web Services Access Points and its Parameters